Reply to an inquiry
Aufruf, Parameter, Antwort und Fehler von POST /v1/inquiries/{id}/messages.
Zuletzt aktualisiert:
Sends a reply to the person who inquired. This reaches a person outside the office, so it follows the same policy as the MCP tool draft_reply: with the scope approve AND the automation of the office set to automatic for replies, the message is queued for delivery right away and the answer is 201 with a proposal in status approved (queued, not yet delivered). Otherwise nothing is sent: a proposal waits for a person in the office to approve it in Athaus, and the answer is 202 with status pending and a Location header. Poll GET /proposals/{id} to see what became of it: executed means delivered. The text is checked against the facts of the property; a claim that is not on the property is rejected with 400. A newer proposal of the same kind for the same inquiry replaces an open one (expired). Idempotency-Key is required. Needs write access to inquiries and the scope propose.
Braucht den Scope propose und mindestens die Stufe write auf inquiries.
Aufruf
POST https://api.athaus.ai/v1/inquiries/{id}/messagesParameter
Pfad
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
id | string (uuid) | ja | UUID of the inquiry. |
Kopf
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
Athaus-Version | string | nein | Optional and carries nothing a client needs: the version is the path. Accepted when it says v1 or 1. Any other value is a 400 api_version_unsupported. |
Idempotency-Key | string | ja | Required: this operation reaches people outside the office, and a message cannot be taken back. Send a fresh UUID per message and reuse it only to retry the same request: the same key with the same body returns the first answer (a stored 202 stays a 202 with the same proposal) and sends nothing twice. 1 to 255 characters, kept for 24 hours, scoped to the API key and this operation. A different body under the same key is a 422; while the first request still runs it is a 409. Without the header the answer is 400 idempotency_key_missing. |
Rumpf
JSON mit Content-Type: application/json. Ein Feld, das die API nicht kennt, ist ein 400, und errors[].name nennt das Feld. Der Rumpf ist Pflicht.
| Feld | Typ | Beschreibung |
|---|---|---|
text | string | The reply to the person who inquired, 1 to 8000 characters, plain text. It is checked against the facts of the property before anything is sent. |
Beispiel
curl -X POST "https://api.athaus.ai/v1/inquiries/0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17/messages" \
-H "Authorization: Bearer ath_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"text":"Guten Tag, vielen Dank für Ihre Anfrage. Die Wohnung ist noch verfügbar. Gern zeige ich sie Ihnen diese Woche."}'Antwort
Bei Erfolg kommt 201 oder 202 mit Proposal.
Proposal
| Feld | Typ | Beschreibung |
|---|---|---|
object | string | Immer proposal. |
id | string | UUID of the proposal. |
status | string | Eines von pending, approved, executed, failed, rejected, expired. |
action | string | What the proposal does once it is approved. The list is open: new actions arrive, and a client treats an unknown one as a proposal it follows by status. Eines von inquiry.reply, inquiry.follow_up, listing.publish. |
target | object | What the action is about: an inquiry, or the listing (its listingId) to publish. |
target.object | string | Eines von inquiry, listing. |
target.id | string | |
text | string | The message that goes to the person who inquired; for listing.publish a sentence naming the listing. Where a human changed a message before approving, the changed text. |
livemode | boolean | false for a proposal of the test office (test keys): approving it records the message as sent in the thread with a note that it was not delivered, and nothing leaves Athaus. |
createdAt | string (date-time) | |
decidedAt | string (date-time) | null | When a human, an API key with the scope decide or the automation of the office said yes or no, or the proposal expired. Null while pending. |
decidedBy | object | null | The API key that said yes or no. Null while pending and when a person or the office's automation decided. |
decidedBy.object | string | Immer api_key. |
decidedBy.id | string | |
decidedBy.name | string | null | |
executedAt | string (date-time) | null | When the message was delivered, or the listing went online. Null until then. |
Köpfe der Antwort
| Kopf | Beschreibung |
|---|---|
Request-Id | Identifies this request. Quote it in a support request. |
Athaus-Version | The API version of this response: v1. |
Athaus-Release | The release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it. |
ETag | A strong entity tag of this state of the resource. Send it as If-Match to change or delete the resource only if it is unchanged, or as If-None-Match to read it only if it changed. |
RateLimit-Policy | The quota policy of the bucket that applies. |
RateLimit | Remaining quota and seconds until the bucket is full again. |
Idempotent-Replayed | true when this is the stored answer to an earlier request with the same Idempotency-Key. |
Location | The proposal: /v1/proposals/{id}. |
Fehler
Jeder Fehler kommt als Problem Details. Verzweige auf code, nicht auf title oder detail.
| Status | Codes | Bedeutung |
|---|---|---|
400 | invalid_id, api_version_unsupported, invalid_body, idempotency_key_missing | Invalid request. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_permissions, plan_required | The key lacks a right, or the plan does not include API access. |
404 | not_found | Nothing under this ID. |
409 | address_missing, automation_disabled, idempotency_key_in_use, idempotency_outcome_unknown | The request conflicts with the state of the resource (for example a duplicate), or with an idempotency key. |
413 | payload_too_large | The request body is larger than 512 KB. |
415 | invalid_input | The request body is not JSON. Send Content-Type: application/json. |
422 | idempotency_key_reused | The idempotency key was already used with a different request body. |
429 | rate_limited | Rate limit exceeded. |
500 | internal_error | Server error. |
Weiter lesen
REST-API: Anmeldung mit einem API-Key
Jeder Aufruf von /v1 trägt einen API-Key als Bearer-Token. Wo du ihn bekommst, welche Scopes er trägt und was nicht geht.
REST-API: Fehler als Problem Details
Jeder Fehler von /v1 ist ein Problem nach RFC 9457 mit echtem HTTP-Status, einem Code zum Verzweigen und einer Request-Id für den Support.