Chats

A chat is one text session with a text agent, the text counterpart of a call. Start it with POST /v1/chats, send messages with POST /v1/chats/{chat_id}/messages (the reply comes back on that request, as JSON or a stream), and end it with POST /v1/chats/{chat_id}/end. Prompt, tools and handoffs behave as they do on a call. A chat stays open until the agent’s end_call tool or POST /v1/chats/{chat_id}/end ends it. One the person stops writing in ends 24 hours after their last message (close_reason: "inactivity_timeout"), and only then gets its analysis and session.completed webhook. If you know your user has left, end the chat yourself. Chats also start when a message arrives on Telegram or WhatsApp. Those chats are driven by the channel: sending a message to one over the API, or minting a token for it, is refused with 409.

Start a chat

curl -X POST https://api.talqing.com/v1/chats \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    "contact_key": "user-42",
    "userdata": { "name": "Priya", "plan": "gold" },
    "vars": { "support_region": "in" }
  }'

const chat = await talqing.chats.create({
  createChatRequest: {
    agent_id: "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    contact_key: "user-42",
    userdata: { name: "Priya", plan: "gold" },
    vars: { support_region: "in" },
  },
});

chat = talqing.chats.create(
    agent_id="9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    contact_key="user-42",
    userdata={"name": "Priya", "plan": "gold"},
    vars={"support_region": "in"},
)

uuid

The text agent that answers (published version unless agent_version says otherwise). agent, agent_version, agent_override and agent_team work as on a call; see per-call configuration. A non-text agent is refused.

string

Your stable id for the person, 1–256 characters. Must not start with a reserved prefix. It is what links a person’s chats for memory and history. Omit it for a single-use key with no past.

object

What the agent knows about the person, read as {{userdata.field}}. Merged onto the contact’s record, so it carries into later chats. See userdata.

object

String values for the agents’ declared {{vars.*}}, fixed for this chat. See variables.

Response 201:

{
  "id": "5d0e7c1a-8a53-4f0e-9d0b-3c8a1f2b6e44",
  "conversation_id": "0b7f2c9e-1d34-4a6b-8e21-9f5c3a7d6b10",
  "contact_key": "user-42",
  "agent": { "agent_id": "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704", "name": "Support", "channel": "text" },
  "status": "open",
  "close_reason": null,
  "created_at": "2026-10-01T09:14:02Z",
  "started_at": null,
  "ended_at": null,
  "cost": null,
  "analysis": null,
  "userdata": { "name": "Priya", "plan": "gold" }
}

started_at stays null until the first message; nothing runs or is charged before then.

Starting a chat ends the contact’s open chat with the same agent (close_reason: "replaced"). A contact can hold open chats with different agents.
A workspace with no credit is refused with 402.

Send a message

curl -X POST "https://api.talqing.com/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"client_message_id\": \"$(uuidgen | tr 'A-Z' 'a-z')\",
    \"message\": \"My order 10432 never arrived. What happens now?\"
  }"

import { randomUUID } from "node:crypto";

const turn = await talqing.chats.messages.create({
  chat_id: chat.id,
  chatMessageRequest: {
    client_message_id: randomUUID(),
    message: "My order 10432 never arrived. What happens now?",
  },
});
for (const item of turn.items) {
  if (item.type === "message") console.log(item.text);
}

from uuid import uuid4

turn = talqing.chats.messages.create(
    chat["id"],
    client_message_id=str(uuid4()),
    message="My order 10432 never arrived. What happens now?",
)
for item in turn["items"]:
    if item["type"] == "message":
        print(item["text"])

Field	Type	Meaning
`client_message_id`	uuid, required	You generate it. Re-sending the same id returns the same turn instead of posting twice, so retries are safe.
`message`	string	Up to 100,000 characters. May be empty only when `files` is not.
`files`	array	Up to 4 `{ "data_url", "filename" }` objects. See files.
`stream`	boolean, default `false`	Answer as `text/event-stream`. See stream the reply.

Response 200, the whole turn:

{
  "input": { "id": "a41c2f0e-…", "type": "message", "role": "user", "text": "My order 10432 never arrived. What happens now?" },
  "status": "done",
  "error": null,
  "superseded_by_item_id": null,
  "items": [
    { "id": "c93e…", "type": "function_call", "direction": "internal", "trigger_item_id": "a41c2f0e-…" },
    { "id": "d07a…", "type": "function_call_output", "direction": "internal", "trigger_item_id": "a41c2f0e-…" },
    { "id": "e5b2…", "type": "message", "role": "assistant", "direction": "outbound", "text": "Order 10432 was returned to the depot yesterday…", "trigger_item_id": "a41c2f0e-…" }
  ],
  "chat_status": "open"
}

Items are trimmed here; each is a full item.

Field	Meaning
`input`	Your message, as stored.
`status`	`done`, `error`, `canceled` (superseded), or `running` (still working after 120 seconds).
`error`	The reason, when `status` is `error`.
`superseded_by_item_id`	On `canceled`: the newer message that took over.
`items`	Everything the turn produced, oldest first, including tool calls and outputs.
`chat_status`	`ended` when the agent ended the chat on this turn. Stop sending.

The request waits up to 120 seconds. A running turn finishes in the background; read the reply later from GET /v1/chats/{chat_id}/items. A message to an ended chat is refused with 409. The latest message wins. If message B arrives while A is still being answered, A’s request returns status: "canceled" with superseded_by_item_id set to B, and B’s request returns the reply. A superseded message is not charged.

Stream the reply

With "stream": true the same request answers as server-sent events:

`event`	Payload	When
`assistant.started`	`trigger_item_id`	The reply has begun.
`assistant.delta`	`trigger_item_id`, `text`	One chunk. Deltas append; they are not cumulative.
`assistant.completed`	`trigger_item_id`, `text`, `item_ids`, `session_id`	The reply is whole; `text` is all deltas joined.
`item.created`	one item	Each item the turn produces.
`turn.result`	the JSON turn body above	Last frame; the stream then closes.

Each frame carries its name in an event field. The stream stays open until the turn ends, with a keep-alive comment every 15 seconds. turn.result is read from the database, so it is authoritative even if a delta was dropped. A refused request (ended chat, a file over 20 MB) is a normal HTTP error, not a stream. Frame shapes: streaming.

End a chat

curl -X POST "https://api.talqing.com/v1/chats/$CHAT_ID/end" \
  -H "Authorization: Bearer $TALQING_API_KEY"

await talqing.chats.end({ chat_id: chat.id });

talqing.chats.end(chat["id"])

Returns 202 with the chat, marked ended at once (the next message is a 409). Ending an ended chat is a no-op. Then, in the background:

The agent’s on_exit hook runs; anything it says is saved to the chat’s items.
Analysis runs (on by default for text agents) and fills analysis.
The chat is priced and session.completed is sent. See webhook events.

`close_reason`	Ended by
`end_call`	The agent’s `end_call` tool. That turn returns `chat_status: "ended"`; `on_exit` runs after the response.
`api_end`	`POST /v1/chats/{chat_id}/end`.
`replaced`	A new chat for the same contact (on WhatsApp or Telegram, whatever its agent), an outbound post that chose another agent, or a channel trigger pointed at a different agent.
`messages_off`	The WhatsApp or Telegram messages trigger was turned off or deleted.
`inactivity_timeout`	24 hours without a message from the person. Replies from the agent, posts and instructions don’t count.

From a browser

Never put a personal access token in browser code. Your server starts the chat, mints a chat token for it, and passes the response to the page:

curl -X POST "https://api.talqing.com/v1/chats/$CHAT_ID/token" \
  -H "Authorization: Bearer $TALQING_API_KEY"

{
  "chat_id": "5d0e7c1a-8a53-4f0e-9d0b-3c8a1f2b6e44",
  "token": "eyJhbGciOi…",
  "expires_at": "2026-10-01T10:14:02Z",
  "api_url": "https://api.talqing.com"
}

(SDKs: talqing.chats.tokens.create(...).) The token lasts one hour, is pinned to one chat, and is refused with 409 for an ended chat. As a Bearer token, from any origin, it opens exactly four routes for that chat: GET /v1/chats/{chat_id}, GET /v1/chats/{chat_id}/items, POST /v1/chats/{chat_id}/messages and POST /v1/chats/{chat_id}/end. A token holder is treated as the customer: items are only the customer_visible ones (no tool calls or handoffs), and the chat reads back with cost: null, analysis: null and userdata: {}. TalqingChat from @talqing/client wraps those routes. It streams every send and calls fetchToken again shortly before expiry, so have your endpoint mint a token for the same chat:

import { TalqingChat } from "@talqing/client";

const chat = new TalqingChat({
  // Your endpoint: POST /v1/chats once, then POST /v1/chats/{chat_id}/token.
  fetchToken: async () => (await fetch("/api/chat-token", { method: "POST" })).json(),
});

const { events, result } = chat.send("Where is my order?");
for await (const event of events) {
  if (event.event === "assistant.delta") render(event.text);
}
const turn = await result;
if (turn.chat_status === "ended") closeChatBox();

chat.items() reloads the history after a page refresh; chat.end() ends the chat. A browser cannot start a chat or choose a contact_key. Full client reference: React SDK.

Files

Attach up to four files per message, of any type, as base64 data: URLs of up to 20 MB each:

{
  "client_message_id": "b1c9c8a2-7c4b-4f5e-9a0d-4c1c2a3b4d5e",
  "message": "Can you check the total on this invoice?",
  "files": [
    { "data_url": "data:application/pdf;base64,JVBERi0xLjQK...", "filename": "invoice.pdf" }
  ]
}

The type is read from the bytes, never from the data: mime. What the agent does with each file:

File	The agent
A photo (JPEG, PNG, WebP)	Sees it when its model has `vision: true`; otherwise it is told it cannot view it
A PDF or Word (`.docx`) file	Reads its text, and a PDF’s scanned pages as images on a `vision` model
A voice note or audio file (Ogg, MP3, M4A, WAV, AAC, AMR)	Reads what was said, when it has a speech-to-text model (voice notes)
A contact card (`.vcf`)	Reads each card’s name, phone numbers, emails and organization
Anything else	Is told it arrived and that it cannot open it

Every file is stored either way: text and files arrive as one item and one turn, and come back on the item’s attachments, each with a signed URL and url_expires_at. A file is refused with 400 only when it cannot be stored: empty, over 20 MB, or not a valid data URL. Limits: documents. In a browser, talqingFileDataUrl(file) from @talqing/client checks a File, downscales a photo and encodes it into the data_url.

Voice notes

A text agent hears voice notes only when you give it a speech-to-text model: config.stt, off (null) by default. Each note is transcribed in one request, on your own provider key, before the agent replies, so only models with file_transcription set in GET /v1/catalog qualify: today every xAI, Sarvam, Raya, OpenAI gpt-transcribe, ElevenLabs scribe_v2, Deepgram Nova-3 and OpenRouter model. config.language applies to it as on a call; Auto detects.

{ "stt": { "provider": "sarvam", "model": "saaras:v4" }, "language": null }

The transcript is stored on the attachment (status: "transcribed", transcript, duration_seconds), so every later agent in the conversation reads it too. A note that arrived while the agent had no stt stays pending and is transcribed on the next turn of an agent that has one. A file that cannot be decoded, or that the provider refuses, is failed with a failed_reason. Transcription is billed per second of audio at the model’s rate, as a line on the chat’s cost.

Read chats back

Endpoint	Returns
`GET /v1/chats`	Newest first. Filters: `agent_id`, `contact_key`, `status` (`open`, `ended`, `all` default). `limit` ≤ 200.
`GET /v1/chats/{chat_id}`	The chat, with `cost` so far and, once ended, `analysis`.
`GET /v1/chats/{chat_id}/detail`	The chat plus health snapshot, cost lines, `vars` and event trace. Not available to chat tokens.
`GET /v1/chats/{chat_id}/items`	Its items. `order=asc` (default) or `desc` for the newest page; `limit` ≤ 500, `offset`.
`DELETE /v1/chats/{chat_id}`	Erases an ended chat’s content (`202`); `409` while open. The chat row and cost stay.

Re-running or previewing analysis on an ended chat: call analysis. A chat is a session of its conversation, so it also appears under GET /v1/conversations/{conversation_id}/sessions beside calls. See conversations.

Items

`type`	What it is
`message`	Something the person or the agent said.
`function_call`	A tool call, with its arguments.
`function_call_output`	What the tool returned.
`agent_handoff`	The chat moved to another agent.
`agent_config_update`	The running agent’s configuration changed mid-chat.

Field	Values
`direction`	`inbound`, `outbound`, `internal` (tool calls, handoffs).
`visibility`	`customer_visible`, `internal`.
`trigger_item_id`	The inbound message that caused this item.
`turn_status`, `turn_error`	On an inbound message: `running`, `done`, `error`, `canceled`.
`delivery_status`	`not_applicable` (API chats), `pending`, `sending`, `sent`, `failed`, `skipped` (messaging channels).

Items also carry session_id, agent_id, agent_version, attachments and per-turn metrics.

Hooks, handoffs and memory

on_enter runs once, on the first message; on_exit runs once, when the chat ends.
A handoff lasts for the rest of the chat: the new agent answers every later message. Within a chat the agent sees the whole chat so far, or what the handoff’s context passed it plus everything since. See handoffs.
What a new chat knows of earlier ones is the agent’s conversation.context (none, summary, transcript), as on calls. See conversation memory.

Cost and retention

$0.0001 per answered message (turn finished done) is the platform fee on text, drawn from credits. canceled and error turns are free. Model spend goes to your provider key. See pricing and credits.
cost fills in while the chat is open and is final once it ends.
Credit is checked at start (402) and again when a chat resumes after sitting idle. Out of credit then, the turn returns status: "error" and the agent does not run.
Under a retention policy, content is deleted retention_days after the chat ends. Open chats are never purged.

Website chat guide

A text agent in your own React app, end to end.

Conversations

Sessions, items and a person’s whole history.

Get started

Build

Guides

Start a chat

Send a message

Stream the reply

End a chat

From a browser

Files

Voice notes

Read chats back

Items

Hooks, handoffs and memory

Cost and retention

Next

Website chat guide

Conversations

​Start a chat

​Send a message

​Stream the reply

​End a chat

​From a browser

​Files

​Voice notes

​Read chats back

​Items

​Hooks, handoffs and memory

​Cost and retention

​Next

Website chat guide

Conversations

Start a chat

Send a message

Stream the reply

End a chat

From a browser

Files

Voice notes

Read chats back

Items

Hooks, handoffs and memory

Cost and retention

Next