Text chat

Talk to an agent in text over the API. Start a chat, send messages, read the transcript and end it, with no phone call.

A chat is a text conversation with one of your agents. It uses the same agent that answers your calls: same prompt, model and functions. You send a message, wait for the reply, and repeat. There is no audio.

Chats suit support widgets, in-app assistants and testing a prompt without dialing. Your API key stays on your server, so for a chat box on a web page, have your backend call the API for the visitor.

How chats differ from calls

Prompt agents only. Flow agents and multi-prompt agents are refused with agent_type_not_supported.
The agent must keep its transcript. An agent that opts out of transcript storage, or redacts it, is refused with chat_requires_storage. A chat is its messages.
You drive the turns. Each request sends one message and returns the agent's reply. Nothing is spoken, so there is no interruption or silence handling.
Each reply is billed to your prepaid credit. When the credit is spent, sending is refused with a 402.
Webhooks differ. chat_started, chat_ended and chat_analyzed fire for chats. See Webhook events.

Start a chat

Create the chat

Pass the agent_id. Optionally pass agent_version to talk to a published version (omitted, you get the draft), metadata for your own labels, and dynamic_variables to fill {{placeholders}} in the prompt. See Prompt agents.

curl https://api.dialgem.com/v1/chats \
  -H "X-API-Key: $DIALGEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_ID",
    "metadata": { "ticket": "T-1042" },
    "dynamic_variables": { "customer_name": "Ada" }
  }'

The response has a chat_id, a chat_status of ongoing, and messages. If the agent has a first_message, it is already the first entry.

Send a message

The request waits for the agent's reply. content is required and can be up to 4000 characters.

curl https://api.dialgem.com/v1/chats/CHAT_ID/messages \
  -H "X-API-Key: $DIALGEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Can I come in on Tuesday?" }'

The response is { chat_id, chat_status, messages }. messages holds only the new entries, in order: your message, any function calls the agent made, and its reply. Each entry has a message_id, a role and a created_timestamp. Roles are user, agent, tool_call_invocation and tool_call_result.

End it

curl -X POST https://api.dialgem.com/v1/chats/CHAT_ID/end \
  -H "X-API-Key: $DIALGEM_API_KEY"

Ending twice is fine and changes nothing. An agent can also end the chat itself with its end-call function; the reply then comes back with chat_status set to ended. The chat records an end_reason of user_ended or agent_ended.

Read the transcript

Fetch one chat to get its full messages, a plain-text transcript (lines like User: ... and Agent: ...), message_count, your metadata and, after it ends, an analysis.

curl https://api.dialgem.com/v1/chats/CHAT_ID \
  -H "X-API-Key: $DIALGEM_API_KEY"

The analysis is produced shortly after the chat ends, so it can be empty on the first read. Fetch again, or wait for the chat_analyzed webhook. To analyse an ended chat again with the agent's current settings, call POST /v1/chats/CHAT_ID/rerun-analysis.

List, label and delete

GET /v1/chats lists chats newest first. Filter with agent_id and status (ongoing or ended), and page with limit (1 to 100, default 50) and pagination_key. List entries leave out messages; fetch one chat for them.

PATCH /v1/chats/CHAT_ID replaces the whole metadata object. DELETE /v1/chats/CHAT_ID removes the chat and its messages.

Errors to handle

Status	Code	Meaning
409	`chat_busy`	Another reply is still being written. Wait, then send again.
409	`chat_ended`	The chat has ended. Start a new one.
409	`message_limit`	The chat has reached its message cap. Start a new one.
422	`agent_type_not_supported`	The agent is not a prompt agent.
502	`model_error`	The model did not answer. Nothing was saved; send the same message again.

Send one message at a time per chat. Message sends are not retried automatically by the SDKs, because a retry after an unclear failure could add the message twice.

Every route is listed under Chats in the API reference. SDK setup is on the TypeScript and Python pages.