Skip to main content

Conversation events

A project can send an HTTP POST to your own endpoint when something happens in a conversation:

EventSent when
call.startedA voice call connects, on a phone number or the website widget.
call.endedA voice call ends. Carries its length and why it ended.
transcript.readyA conversation's transcript is stored, on any channel. Carries the transcript.

Use them to sync calls into your CRM, start follow-up work when a call ends, or archive transcripts in your own systems.

Conversation events are available on plans that include webhooks.

Add an endpoint​

  1. In your project, open Settings → Webhooks.
  2. Click Add endpoint.
  3. Enter the endpoint URL. It must use https:// and point at a public address.
  4. Optionally add a description, such as CRM sync.
  5. Choose the events to send. All three are selected by default.
  6. Click Add endpoint.

The endpoint's signing secret is shown once, right after you add it. Copy it into your receiver's configuration, then verify the signature of every request.

A project can have up to 10 endpoints. Each one receives every event it subscribes to.

Manage endpoints​

Each endpoint in Settings → Webhooks shows its events and its last delivery: the outcome, the HTTP status your endpoint answered, and when.

ActionWhat it does
Send test eventSends one signed webhook.test event right away and shows your endpoint's answer. Test events aren't retried or billed.
Active switchPauses or resumes the endpoint. A paused endpoint receives nothing.
Show signing secret (key icon)Shows the endpoint's current secret.
Rotate secretIssues a new secret. The next request is signed with it, and the old one stops verifying at once.
EditChanges the URL, description or events.
DeleteRemoves the endpoint and its secret.

The Last event outcome is Delivered when your endpoint answered 2xx, or Failed when it answered a status that isn't retried or the retries ran out. It is updated once an event's delivery is finished, so an event still being retried shows the previous outcome.

Payload​

Every event has the same envelope:

FieldDescription
idA unique ID for the event, starting evt_. Every endpoint that receives the event gets the same id.
typeThe event type, also sent in the X-VoisX-Event header.
created_atWhen the event happened, in ISO 8601 UTC.
project_idThe project the conversation belongs to.
dataThe event's details, below.

call.started​

{
"id": "evt_6c1f0e2a9b8d4c7e8f1a2b3c4d5e6f70",
"type": "call.started",
"created_at": "2026-10-31T09:30:00.000000+00:00",
"project_id": 345,
"data": {
"session_id": "MZ1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
"agent_id": 12,
"channel": "phone"
}
}

call.ended​

{
"id": "evt_0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d",
"type": "call.ended",
"created_at": "2026-10-31T09:31:13.000000+00:00",
"project_id": 345,
"data": {
"session_id": "MZ1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
"agent_id": 12,
"channel": "phone",
"duration_seconds": 73.4,
"end_reason": "caller_hangup"
}
}

transcript.ready​

{
"id": "evt_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
"type": "transcript.ready",
"created_at": "2026-10-31T09:31:14.000000+00:00",
"project_id": 345,
"data": {
"session_id": "MZ1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
"agent_id": 12,
"turn_count": 2,
"transcript": [
{ "role": "assistant", "text": "Hello, this is Asha from Acme Travel. How can I help?", "timestamp": "2026-10-31T09:30:01Z" },
{ "role": "user", "text": "I'd like to change my booking.", "timestamp": "2026-10-31T09:30:05Z" }
]
}
}

Data fields​

FieldEventsDescription
session_idAllThe conversation's ID, the same one Calls & transcripts shows. Use it to join the three events of one call.
agent_idAllThe agent that handled the conversation.
channelcall.started, call.endedphone for a phone number or SIP trunk, widget for the website widget.
duration_secondscall.endedThe call's length in seconds, to one decimal place.
end_reasoncall.endedWhy the call ended: caller_hangup, browser_closed, agent_ended, transferred, silence_hangup, max_call_duration or error.
turn_counttranscript.readyThe number of turns in transcript.
transcripttranscript.readyThe conversation, oldest turn first. Each turn has role (user or assistant), text and timestamp.

New fields may be added to data at any time. Ignore fields you don't use.

When events are sent​

  • call.started and call.ended are sent for voice calls only.
  • transcript.ready is sent for every channel. For a voice call it follows call.ended. For a text chat it is sent once the chat has been idle for 5 minutes. If the chat continues later, another transcript.ready is sent when it next goes idle, with the full transcript so far.
  • The transcript is the one the console shows. If your project masks personal data, the transcript is masked the same way.
  • Events are sent only while the organization's plan includes webhooks. Endpoints are kept if the plan changes, and you can still see and delete them.

Retries and duplicates​

Events are delivered, retried and signed as described in Outbound delivery:

  • Answer 2xx within 10 seconds. Do slow work after you answer.
  • Timeouts, 408, 425, 429 and 5xx answers are retried up to 5 times over about 2 hours. Other statuses are final.
  • A retried request has the same X-VoisX-Delivery header and the same body. Store the X-VoisX-Delivery values you have handled and skip repeats.
  • Events can arrive out of order, for example when a call.started is retried after its call.ended arrived. Use created_at to order them.

Billing​

Each event your endpoint accepts counts as one webhook event delivery in your usage. Test events aren't counted. See Usage and billing.

Was this page helpful?