Webhook events

What Talqing POSTs to your webhook URL. Creating a subscription, verifying the signature, delivery rules and testing are on webhooks.

Envelope

Every event has the same outer shape:

{
  "id": "b3f1c2d94a7e4f0a8c6d5e2b1a9f3c7d",
  "type": "session.completed",
  "created_at": "2026-08-30T15:49:30.792290+00:00",
  "tenant_id": "7c1e4a2b-90d3-4f18-8b62-0e5a3c9d7f41",
  "agent_id": "9c2f1a44-3d0b-4a6e-8f21-5b7c0e93a4d1",
  "data": {}
}

Field	Type	Meaning
`id`	string	Event id: 32 hex characters, no dashes. Same value as the `X-Talqing-Delivery` header, and the same on every webhook the event fans out to. Deduplicate on it.
`type`	string	The event type.
`created_at`	string	ISO 8601 with a `+00:00` offset.
`tenant_id`	string	Your workspace.
`agent_id`	string / null	The agent the event concerns. Always null on `agent.deleted` (the id is in `data`), `task_run.completed`, `conversation.item.status`, `webhook.test` and every `email_batch.` and `whatsapp_batch.` event. Otherwise null when no saved agent is involved, such as a session that ran an agent defined inline in the request.
`data`	object	The type’s payload, below.

Event types

Type	Fires when	`data`
`agent.created`	An agent is created	`agent_id`, `name`
`agent.updated`	An agent’s draft is written; also on version rollback	`agent_id`, `name`; on rollback `agent_id`, `version`
`agent.published`	An agent is published; also on version rollback	`agent_id`, `version`
`agent.deleted`	An agent is deleted	`agent_id`, `name`
`session.queued`	`POST /v1/calls/outbound` handed a dial to the carrier, before anyone answered. Single outbound calls only, not batches	See `session.queued` below
`session.started`	A call connects, or a chat receives its first message	See `session.started` below
`session.in_progress`	Same moment and same payload as `session.started`, on phone and WhatsApp calls only	Same as `session.started`
`session.refused`	An inbound call or a new WhatsApp/Telegram chat was turned away before any agent ran	See `session.refused` below
`recording.ready`	A call’s audio reached storage	See `recording.ready` below
`session.completed`	A call or chat ended and its analysis and billing are done	See `session.completed` below
`batch.started`	A call batch begins dialling	The `GET /v1/calls/batches/{batch_id}` body
`batch.completed`	Every recipient of a call batch reached a terminal state (not sent for a cancelled or failed batch)	Same
`batch.failed`	A call batch stopped after ten consecutive setup failures; `failure_reason` says why	Same
`email_batch.started`	Drafting claimed its first row	The `GET /v1/email/batches/{batch_id}` body
`email_batch.drafted`	Drafting finished; the batch waits for review	Same
`email_batch.paused`	Drafting paused itself after ten failures in a row; `resume` continues	Same
`email_batch.failed`	Drafting stopped for good; `failure_reason` says why	Same
`email_batch.send.started`	A send began working through its rows, at its scheduled time if it has one	The `GET /v1/email/batches/{batch_id}/sends/{send_id}` body
`email_batch.send.completed`	Every row the send covers was sent or failed	Same
`email_batch.send.paused`	A send paused itself after ten provider failures in a row; rows stay queued	Same
`email_batch.send.failed`	A send stopped on an account-level refusal; unsent rows return to drafts	Same
`whatsapp_batch.started`	A WhatsApp batch’s first message is going out	The `GET /v1/whatsapp/batches/{batch_id}` body
`whatsapp_batch.completed`	Every row was sent or failed	Same
`whatsapp_batch.paused`	The batch paused itself (credential, template, wallet or messaging-limit problem, or repeated failures); `failure_reason` says which	Same
`whatsapp_batch.failed`	The batch stopped for good (sender deleted, or its creator may no longer send)	Same
`task_run.completed`	A task run reached `completed`, `failed` or `canceled` — inline, background or drafting an email row. Sent once per run, not for a try that is retried	The run as `GET /v1/task-runs` lists it: `id`, `task_id`, `task_name`, `task_version`, `status`, `error`, `output`, `metadata`, `idempotency_key`, `background`, `tries`, `created_at`, `started_at`, `ended_at`, `duration_ms`, `provider_cost`, `billing_status`, `content_deleted_at`, `content_expires_at`. No trace, config or inputs
`conversation.item.status`	An outbound WhatsApp or Telegram message moved: an agent’s reply, a posted item or a batch template	See `conversation.item.status` below
`conversation.attachment.received`	A file a person sent on WhatsApp or a web chat was stored, before any agent reads it. One event per file	See `conversation.attachment.received` below
`tool.invoked`	The model called one of your custom tools, before its arguments are validated	`tool`, `session_id`, `conversation_id`, `arguments`
`tool.failed`	A custom tool raised, including arguments that failed its schema and a long-running tool failing after it was acknowledged	`tool`, `session_id`, `conversation_id`, `error`
`webhook.test`	You test-fire a webhook. Not subscribable	`message`, `webhook_id`

GET /v1/webhooks/event-types returns {"all": [...], "live": [...]}: all is every subscribable type. live currently omits session.queued and session.in_progress, which are nonetheless delivered. For one call, events are dispatched in this order: session.queued (single outbound only), session.started and session.in_progress, recording.ready, session.completed. Each is a separate request, so do not rely on arrival order.

conversation.item.status

One event per move of an outbound channel message’s delivery_status. Receipts arrive out of order and repeat, but a message only ever moves forward, so you get each status at most once.

Field	Type	Meaning
`item_id`	string	The conversation item.
`conversation_id`	string	Its thread.
`contact_key`	string	The person.
`session_id`	string / null	The chat it belongs to, if any.
`post_type`	string / null	`template`, `agent_text`, `note` or `instruction` when it was posted (a batch template is `template`); null for an agent’s reply.
`idempotency_key`	string / null	The key it was posted with.
`status`	string	`held`, `queued`, `sent`, `delivered`, `read`, `undelivered`, `failed`, `skipped` or `expired`. See delivery.
`provider_message_id`	string / null	The BSP’s id for the message.
`error_code`	string / null	The provider’s error code on a failure, e.g. Twilio’s `63016`.
`error`	string / null	Why it failed or was skipped.
`at`	string	When it moved.

conversation.attachment.received

One event per file a person sent, as soon as it is stored. A document arrives with status: "pending"; the event is not sent again once the agent reads it.

Field	Type	Meaning
`conversation_id`	string	Its thread.
`item_id`	string	The message it came on.
`session_id`	string / null	The chat it belongs to, if any.
`contact_key`	string	The person.
`channel`	string	`whatsapp_message` or `chat`.
`attachment`	object	The file as `list_conversation_items` returns it, `kind` `image`, `document`, `audio`, `contact` or `file`, with a signed `url`. An `audio` file is announced on arrival, before it is transcribed.
`at`	string	When it was received.

The url lives one hour, because this payload lands in logs. For a fresh one, call GET /v1/attachments/{attachment_id}.

session.queued

Field	Type	Meaning
`session_id`	string	Readable on `GET /v1/calls/{session_id}` with `status: "queued"`.
`conversation_id`	string
`agent_id`	string / null	Null for an inline agent.
`type`	string	Always `SIP_OUTBOUND`.
`channel`	string	Always `voice`.
`phone_number_id`	string	The number dialling out.
`from_e164`, `to_e164`	string

session.started

A chat sends it once, when its first message arrives, not on POST /v1/chats.

Field	Type	Meaning
`session_id`	string
`conversation_id`	string / null
`agent_id`	string / null	Null for an inline agent.
`version`	integer / null	The published version answering; null for a draft or inline agent.
`channel`	string	`voice`, `video` or `text`.
`type`	string	`WEB`, `SIP_INBOUND`, `SIP_OUTBOUND`, `WHATSAPP_INBOUND`, `STREAM` or `TEXT`.
`phone_number_id`, `integration_id`, `from_e164`, `to_e164`	string / null	Calls only. `integration_id` is the WhatsApp number a WhatsApp call arrived on. Absent (not null) on chats.
`metadata`	object	Labels your inbound webhook set; `{}` otherwise.

If you subscribe to everything you receive both session.started and session.in_progress for every phone call; count one of them.

session.refused

Sent once for every inbound session refused at the door: the workspace is out of credits, the caller’s number is unreadable, calling is off on the WhatsApp number, the agent is unpublished, the same call arrived twice, or your inbound webhook did not answer. A WhatsApp or Telegram chat is refused only by the inbound webhook; a chat message turned away for credits or an unpublished agent sends no event. Neither session.started nor session.completed follows.

Field	Type	Meaning
`session_id`	string	Readable on `GET /v1/calls/{session_id}` or `GET /v1/chats/{chat_id}`.
`type`	string	`SIP_INBOUND`, `WHATSAPP_INBOUND`, `STREAM` or `TEXT`.
`channel`	string	`voice` or `text`.
`agent_id`	string / null	The agent that would have answered.
`from`, `to`	string / null	The caller’s number and yours.
`contact_key`, `conversation_id`	string / null	Set when the session was refused after it was filed against the person, as an inbound webhook refusal is.
`close_reason`	string	See close reasons.
`error`	object / null	`{type, message}`; for `inbound_webhook_failed`, `message` says what your server did.
`metadata`	object	Always `{}`: a refused session has no labels.

recording.ready

Sent once audio is in storage, before session.completed. Not sent for a call with no stored audio.

Field	Type	Meaning
`session_id`, `conversation_id`, `agent_id`	string / null
`duration_s`	number	Audio length.
`bytes`	integer	File size.
`url`	string / null	Signed download link. Null if signing failed.
`url_expires_at`	string	One hour after dispatch.
`expires_at`	string / null	When retention deletes this call’s content; null when retention is unlimited (the default).

url is a credential valid for an hour. Copy the file or strip the field before you log the event. GET /v1/calls/{session_id}/recording mints a fresh link.

session.completed

The end-of-session report and the only event carrying the outcome. It is built from the stored session, so it matches GET /v1/calls/{session_id}.

A call sends it once, after finalize, recording, analysis and billing.
A chat sends it once, when the chat ends (the agent’s end_call, POST /v1/chats/{chat_id}/end, or replacement by a newer chat). A chat nobody ends never sends it; a chat that ended with no messages sends neither this nor session.started.
A session whose worker died before ending sends none. Reconcile from GET /v1/calls with start/end.

Field	Type	Meaning
`session_id`	string
`conversation_id`	string / null	This session’s thread. Changes per call for an agent that starts clean, so do not correlate customers on it.
`contact_key`	string / null	Your stable id for the person. Correlate on this.
`agent_id`, `agent_name`	string / null	The agent that answered.
`agent_version`	integer / `"draft"` / null	`"draft"` for the unpublished draft; null for an inline agent.
`agent_overridden`	boolean	The call carried a per-call override.
`agent_inline`	boolean	The agent was defined in the request.
`channel`	string	`voice`, `video` or `text`.
`type`	string	`WEB`, `SIP_INBOUND`, `SIP_OUTBOUND`, `WHATSAPP_INBOUND`, `STREAM` or `TEXT`.
`status`	string	`completed`, `failed` or `canceled`.
`close_reason`	string / null	How it ended — see close reasons.
`started_at`, `ended_at`	string / null	ISO 8601.
`duration_s`	integer / null	Talqing’s part of the call only; time a caller spent with a transfer target is not counted.
`from_e164`, `to_e164`	string / null	Phone legs; null on web and text.
`batch_id`	string / null	The call batch that placed this call.
`integration_id`	string / null	The WhatsApp number a WhatsApp call arrived on.
`resumed_from_call_id`	string / null	The call this one resumed.
`userdata`	object	What the agent’s tools wrote during the session. `{}` when nothing.
`metadata`	object	Labels your inbound webhook set; `{}` otherwise.
`analysis`	object	`status` (`none`, `pending`, `completed`, `failed`, `skipped`), `skip_reason` (`too_short`, `call_failed`, `produces_nothing`), `summary`, `outcome` (`success`, `failure`, `unknown`), `outcome_rationale`, `fields`. Never merged into `userdata`. See call analysis.
`transcript`	array	Every item, oldest first. See below.
`cost`	object / null	The pricing breakdown; null until billing computed it or when the usage could not be priced. See below.
`transfer`	object / null	Null unless a transfer was attempted. See below.
`recording`, `screen_recording`	object	See below. Neither carries a URL.

transcript rows

Field	Type	Meaning
`id`	string	Item id.
`item_id`	string / null	The runtime’s own item id.
`type`	string	`message`, `function_call`, `function_call_output`, `agent_handoff` or `agent_config_update`.
`scope`	string	`conversation`, or `turn` for context the model was given for one reply only.
`metrics`	object / null	Turn timings on message items.
`attachments`	array	Image metadata only, no link.
`data`	object	`role`, `text` on a message; `name`, `arguments` on a tool call; `output`, `is_error` on its result; `text` on a handoff (`Handed off to Billing`).

cost

Field	Type	Meaning
`provider_cost`	number	Charged by providers to your own keys. Reported, never collected by Talqing.
`platform_fee`	number	Debited from your credit balance.
`total_charge`	number	The sum.
`duration_s`	integer / null	Billed duration.
`platform_fee_per_minute`	number / null	Call rate; null on chats.
`platform_fee_per_message`	number / null	Chat rate; null on calls.
`answered_messages`	integer / null	Chat messages charged; null on calls.
`llm`, `stt`, `tts`, `realtime`, `avatar`	array	One priced line per provider and model: `provider`, `model`, `cost`, usage quantities and the `rates` applied. LLM lines add `purpose` (`conversation` or `analysis`) and `priority`.

How to read it is on costs.

transfer

Field	Type	Meaning
`mode`	string	`cold` or `warm`.
`transport`	string	`refer` or `bridge` (every warm transfer bridges).
`destination`	string	The number dialled.
`outcome`	string	`connected` or `failed`.
`detail`	string / null	Why it did not connect; null when it connected.
`sip_status`	object / null	The carrier’s response, e.g. `{"code": 486, "phrase": "Busy Here"}`.
`on_failure`	string / null	`continue` or `end_call`; null when it connected.
`at`	string	When it happened.

There is no separate transfer event: a transfer ends the session, so session.completed follows immediately.

recording and screen_recording

Field	Type	Meaning
`state`	string	`available` (the only playable state), `none`, `pending`, `expired`, `failed`, `not_shared` or `deleted`. For `screen_recording`, `none` means screen recording was off and `not_shared` means nobody shared.
`started_at`	string / null
`duration_s`	number / null
`bytes`	integer / null
`expires_at`	string / null	When retention deletes this call’s content.

Fetch a link with GET /v1/calls/{session_id}/recording; see recordings.

Using the API

Endpoints

Envelope

Event types

conversation.item.status

conversation.attachment.received

session.queued

session.started

session.refused

recording.ready

session.completed

transcript rows

cost

transfer

recording and screen_recording

​Envelope

​Event types

​conversation.item.status

​conversation.attachment.received

​session.queued

​session.started

​session.refused

​recording.ready

​session.completed

​transcript rows

​cost

​transfer

​recording and screen_recording

Envelope

Event types

conversation.item.status

conversation.attachment.received

session.queued

session.started

session.refused

recording.ready

session.completed

transcript rows

cost

transfer

recording and screen_recording