A chat is a typed conversation with the same agent that takes your calls: its instructions, functions, knowledge and transfer rules all apply, only nothing is spoken. Your server sends each message and gets the agent's whole reply back in the answer. Chats are billed per message the person sends, and each one is a call record: it is listed under Calls (marked Text), analyzed, sent to your webhooks and deleted with a caller's data like any call.
curl https://evasay.com/api/v1/voice/chats \
-X POST \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{ "agent_id": "AGENT_ID", "message": "Do you deliver on Sundays?", "user_id": "u_42" }'
{
"data": {
"chat_id": "vc_…",
"reply": "We do, between 10 am and 4 pm. Would you like to book a slot?",
"cards": [],
"quick_replies": [],
"ended": false
}
}
user_id (your id for the person) and variables (values the agent and its functions may trust) work as for web call tokens.cards and quick_replies are what the agent would show on a web call (see Calls on your website and in your app).curl https://evasay.com/api/v1/voice/chats/CHAT_ID/messages \
-X POST \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{ "message": "Yes, this Sunday at noon." }'
The answer has the same fields. A message is at most 500 characters. Send one at a time and wait for its reply: a message sent while the agent is still answering gets 409 chat_busy, and one sent less than a second after the last gets 429 rate_limited.
If the worker running the chat has gone (a restart), a new chat carries it on with the conversation so far and answers your message; the answer then has continued_from with the old chat's id. Use the new chat_id from then on.
A chat ends after 30 minutes without a message, two hours after it started, at 100 messages, when the agent ends it, or when you end it:
curl https://evasay.com/api/v1/voice/chats/CHAT_ID/end \
-X POST \
-H "Authorization: Bearer sk-your-key"
It is then analyzed, sent to your webhooks as call.ended and billed. A message to a chat that has ended gets 409 chat_ended. To go on, start a new chat with previous_chat_id: the agent is given the earlier conversation (its last 50 messages), and the new chat's record starts empty. ended: true in a reply means the agent ended the chat with that reply.
A workspace may have a number of chats open at once, apart from its calls; when they are all open, a new chat gets 429 chat_limit until one ends.
| Code | Status | When |
|---|---|---|
invalid_message | 400 | No message, or longer than 500 characters |
chat_not_found | 404 | No such chat in the workspace (or previous_chat_id is not one) |
chat_busy | 409 | The agent is still answering the last message |
chat_ended | 409 | The chat is over; start a new one with previous_chat_id |
chat_message_limit | 409 | The chat has taken 100 messages |
rate_limited | 429 | Less than a second after the last message |
chat_limit | 429 | The workspace has as many chats open as it may |
insufficient_credits | 402 | Not enough credits to start a chat |
chat_timeout | 504 | The agent did not finish its reply in time; try again |
chat_unavailable | 503 | The agent could not answer right now; try again |
The widget and the hosted page offer talking and typing; in Agent → Deploy you can offer only one of them. Typed conversations on a page are billed per message like chats. See Calls on your website and in your app.