Send a message
POST https://api.129.212.147.181.sslip.io/v1/sessions/{session}/messages
One turn of the conversation, in any phase. Send what the user typed as text, or answer pending_question with a typed answer (from a widget). Answering an earlier question again changes that answer.
Returns the turn: the user's message, the assistant's reply (its question is what to ask next, or null) and the session after both. If the model fails, reply.status is failed with an error; the session is unchanged and you can send the message again.
Path parameters
Headers
Bearer dg_test_… or Bearer dg_live_…
Your reference for the end user (a user ID, a hash; never an email).
A session is bound to the subject it was created with, and every call
on it must send the same value or it is 404. Set it from your own
login, never from what the browser sent. Required to create and list
sessions unless your organisation has subjects turned off.
Retrying with the same key and body returns the original response. Kept 24 hours.
Body
What the user typed.
Several answers at once, usually every question of pending_step. All are checked first: one bad answer rejects the message and nothing is saved. Send answer or answers, not both.
Returns
200 OK: a Turn object. The turn.
Errors
| Status | Code | What to do |
|---|---|---|
| 422 | parameter_missing | Send text, answer, or both. |
| 422 | question_invalid | Answer pending_question.id, or a question already answered. |
| 422 | answer_invalid | error.fields says what the question expects; for a form question, one of its option values. |
| 409 | turn_in_progress | Another message to this session is being handled. Retry when it returns. |
| 409 | session_closed | The session was closed and takes no more messages. Start a new one. |
| 404 | session_not_found | Check the ID, and that Docgen-Subject is the subject the session was created for. |
| 410 | session_deleted | The session was deleted with its conversation and answers. Start a new one. |
| 503 | provider_unavailable | This turn needs a model; live keys get this until one is configured. |
Any endpoint can also return the common errors (bad key, rate limit, idempotency).