Chat and streaming

The same agents your visitors talk to on your website can chat from your app, your back office or a channel we do not support yet. A chat needs the chats:write permission.

Start a chat

The first message starts it:

#!/bin/sh
# Start a chat
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/chats" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  -H "Idempotency-Key: chat-20931" \
  --json '{
  "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f",
  "message": "Hello, I would like to book a table.",
  "variables": {
    "first_name": "Sara"
  }
}'

The answer is a chat.turn: the agent's greeting in opening (first turn only — show it above the reply), its reply, and the conversation_id to send the next message to. variables are read only when a chat starts, so nothing said later can change what the agent was told about the person. An Idempotency-Key is optional here: the same request with the same key returns the same chat.

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."
}'

The agent keeps the history; you keep the id. There is nothing else to keep in step — no turn to count, no transcript to send.

One message at a time. A message sent while the agent is still answering the previous one is refused with 409 conversation_busy: wait for the reply. A message sent again with the same Idempotency-Key returns the same reply without asking the agent twice — streamed, if the retry asks for a stream. If the first attempt's reply failed, the retry gets that failure again (502 upstream_unavailable); send the message under a new key to ask once more.

A chat follows its agent: once the agent is unpublished, archived or deleted, the chat takes no more messages (409 agent_not_published), and each message is answered by the agent's published version, never by edits that have not been published.

Stream the reply

Send stream: true — or Accept: text/event-stream — and the reply arrives as it is written, as server-sent events:

#!/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
}'

Read done rather than gluing the deltas together. It carries the conversation id, what was collected and whether the agent has finished, which the deltas do not.

Send a picture

Where the agent accepts images, upload one first, then name it in the next message's attachment_ids — up to four a message:

#!/bin/sh
# Upload a picture to send. Send the id it returns in a message's attachment_ids.
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/attachments" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  -F "agent_id=3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" \
  -F "file=@photo.jpg;type=image/jpeg"

A picture nobody sends is deleted after six hours.

End it

#!/bin/sh
# End a call or a chat
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

A chat also ends on its own after a while without messages. A message to an ended chat is refused with 409 conversation_ended; start a new one.

Limits

Chats are charged like chats in the console, from the organization's credit — chats made with a test key too, because they use the agent's real model. When the credit runs out, a message is refused with 402 insufficient_credit.