Conversations

A conversation is one thread with one person: a web chat, a Telegram thread, a single phone call, or — on one of your numbers — a mix of phone calls, WhatsApp calls and WhatsApp messages (surface says which; each item’s channel says how it arrived). Each call or chat inside it is a session. A person can have many conversations; what ties them together is contact_key, your stable id for the person, not conversation_id, which is new on every call for an agent that starts clean. Read one run on calls; read a person’s history here.

List a person’s conversations

GET /v1/conversations returns customer threads on every channel, most recently active first. CoPilot threads are not included.

curl -G https://api.talqing.com/v1/conversations \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  --data-urlencode "contact_key=user-42" \
  --data-urlencode "status=all"

const page = await talqing.conversations.list({ contact_key: "user-42", status: "all" });
for (const thread of page.items) console.log(thread.id, thread.surface, thread.last_message_at);

page = talqing.conversations.list(contact_key="user-42", status="all")
for thread in page["items"]:
    print(thread["id"], thread["surface"], thread["last_message_at"])

Parameter	Default	Meaning
`contact_key`	—	Only this person’s threads.
`agent_id`	—	Threads this agent ran a session in.
`status`	`active`	`active`, `inactive` or `all`. `inactive` is outreach the person has not answered or replied to yet; the default hides it.
`limit`, `offset`	100, 0	Max 200.

Endpoints

Endpoint	Returns
`GET /v1/conversations/{conversation_id}`	The header: `contact_key`, `ref` (the contact below), `agent_id` and `agent_name` (of the newest session), `surface`, `status`, `last_message_text`, `last_message_at`, `summary`, `userdata`, `metadata`.
`GET /v1/conversations/{conversation_id}/items`	The transcript, a page (default 200, max 500). `order=asc` (default) from the start; `order=desc` the newest window, chronological within the page.
`GET /v1/conversations/{conversation_id}/sessions`	The sessions behind the thread, newest first.
`GET /v1/conversations/{conversation_id}/snapshot`	One health verdict over the whole thread, in the shape of a call’s `snapshot`.
`GET /v1/conversations/{conversation_id}/trace`	The runtime trace across its sessions, oldest first; filter with `after` and `before`.
`PATCH /v1/conversations/{conversation_id}`	Edit `summary`, `userdata` or `metadata`.
`GET /v1/conversations/{conversation_id}/events`	Live SSE stream — see streaming.

userdata on a conversation is the contact’s: what tools have stored about this person across all their conversations, identical on every thread with the same contact_key. What one call ended with is session.userdata on the call.

The contact

ref describes the person the thread is with:

Field	Meaning
`contact_key`	`phone:<your number>:<their number>` for anyone reaching one of your numbers by phone or WhatsApp; your own key for web calls and chats; `telegram:…`, `stream:…`, or `whatsapp:<your number>:<id>` for a WhatsApp user who hides their number.
`kind`	`phone`, `integration`, `stream` or `web`.
`number`, `peer`	Your number and theirs, on a `phone` contact.
`whatsapp_window_expires_at`	When free-form WhatsApp messages stop being allowed: 24 hours after their last WhatsApp message or call. Null if they never contacted you on WhatsApp.
`integration_id`	The Telegram or WhatsApp integration, on an `integration` contact.
`display_name`	Their WhatsApp or Telegram name, else their number.

Items

Field	Meaning
`type`	`message`, `function_call`, `function_call_output`, `agent_handoff` or `agent_config_update`.
`direction`	`inbound`, `outbound` or `internal`.
`role`	`developer`, `system`, `user`, `assistant` or `tool`.
`channel`	How it reached you or the person: `phone_call`, `whatsapp_call`, `whatsapp_message`, `web_call`, `chat`, `telegram`, `stream`.
`text`	Null (never empty) on an image-only message.
`attachments`	Images, with signed URLs minted at read time.
`visibility`	`customer_visible` or `internal`.
`scope`	`conversation`, or `turn` for context given to one reply only.
`delivery_status`, `delivery_error`	On outbound items: where it got to (see delivery), and why it failed.
`post_type`, `author`, `idempotency_key`	On items posted: `template`, `agent_text`, `note` or `instruction`; who posted it; your key.
`turn_status`, `turn_error`	On a message that started a turn: `running`, `done`, `error` or `canceled`, and why.
`origin`	On user messages: `speech`, `typed` or `keypad`.
`agent_id`, `agent_version`	Which agent wrote it; reads a handed-off thread line by line.
`metrics`, `latency`, `elapsed`	Turn timings, the reply’s latency stages, and the elapsed-time stamp the model saw.
`client_message_id`, `provider_message_id`, `trigger_item_id`	Your id, the channel’s id, and the inbound item this answers.

Sessions

The sessions list is how you read a multi-agent or multi-call thread: one row per run.

Field	Meaning
`id`	The session; also its `GET /v1/calls/{session_id}` or `GET /v1/chats/{chat_id}` id.
`agent`, `agent_version`, `agent_version_id`	`{agent_id, name, channel}` and the version that ran; `agent_version` is `"draft"` for the unpublished draft.
`type`, `channel`, `status`	How it reached the agent, `voice`/`video`/`text`, and its state.
`vars`	The `{{vars.*}}` values it started with.
`close_reason`, `close_reason_label`	How it ended.
`analysis`	`status`, `summary`, `outcome`, `fields` — see call analysis.
`usage`, `cost`, `duration_s`	Its metering and cost; `cost` is null until billed.
`metrics`	`e2e_latency`, `llm_node_ttft`, `tts_node_ttfb`, `transcription_delay`, `end_of_turn_delay`, `turns`. On a chat, `e2e_latency` is message arrival to first token.
`error`, `started_at`, `ended_at`	Unhandled error, and its window.

The thread snapshot sums cost over priced sessions only and is null when none are priced.

Correct what an agent knows

PATCH with userdata changes what the next turn sees as {{userdata.field}}, for every conversation with this person. Each field you send (summary, userdata, metadata) replaces that whole object; omitted fields are left alone.

curl -X PATCH https://api.talqing.com/v1/conversations/4d2e9a71-58c3-4b0e-8f16-2a9d3c7e1b45 \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userdata": {"plan": "enterprise", "account_id": "AC-8812"}}'

In the dashboard

Conversations is the inbox: one row per thread with surface, agent and last message, filterable by agent. A thread shows the transcript with its health verdict, the sessions behind it and per-reply latency, and updates live.

Calls

One voice or video session in full.

Conversation memory

What a new call knows about earlier ones.

Get started

Build

Guides

List a person’s conversations

Endpoints

The contact

Items

Sessions

Correct what an agent knows

In the dashboard

Calls

Conversation memory

​List a person’s conversations

​Endpoints

​The contact

​Items

​Sessions

​Correct what an agent knows

​In the dashboard

Calls

Conversation memory

List a person’s conversations

Endpoints

The contact

Items

Sessions

Correct what an agent knows

In the dashboard