Send a message

POST /v1/conversations/{conversation_id}/messages

Send the next message in a chat started through the API, and get the agent's reply as a chat.turn — or, with stream: true, as server-sent events. One message at a time: wait for the reply before sending the next. Needs chats:write. An Idempotency-Key is optional: the same message again returns the reply it already got.

Parameters

Name	In	Type	Required	Description
`conversation_id`	path	string (uuid)	Yes
`Idempotency-Key`	header	string	No	Your own id for this message. Optional.

Body

Sent as JSON. A field this operation does not take is refused, so a typo fails loudly.

Field	Type	Required	Description
`attachment_ids`	array of string (uuid)	No	Pictures to send with it, from `POST /v1/attachments`.
`message`	string	Yes	What the person wrote.
`stream`	boolean	No	Send the reply as it is written, as server-sent events. `Accept: text/event-stream` does the same.

Answer

200 with ChatTurn.

With stream: true, the same answer arrives as server-sent events instead — see Chat and streaming.

Errors

Every error is a problem document with a stable code.

Status	When
`401`	The key is missing, mistyped, unknown, revoked or expired.
`402`	The organization's credit is used up.
`403`	The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something.
`404`	This key reaches no such chat, or it was not started through the API.
`409`	The chat has ended or reached its length, the agent is still answering the last message, or this is not a chat.
`422`	The message, or its Idempotency-Key, does not fit.
`429`	Too many requests for this key or its organization; see `Retry-After`.
`500`	Something went wrong on our side. Quote the `request_id` to support.

Examples

Send the next message

#!/bin/sh
# Send the next message
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  --json '{
  "message": "For four people, at seven."
}'

Stream the reply as it is written

#!/bin/sh
# Stream the reply as it is written
curl -sS --fail-with-body -N -X POST "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  --json '{
  "message": "Can I bring my dog?",
  "stream": true
}'

Try it

Sends this request to the API from your browser, with a test key. Nothing it does rings a phone.