Conversation events
A project can send an HTTP POST to your own endpoint when something happens in a conversation:
| Event | Sent when |
|---|---|
call.started | A voice call connects, on a phone number or the website widget. |
call.ended | A voice call ends. Carries its length and why it ended. |
transcript.ready | A 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
- In your project, open Settings → Webhooks.
- Click Add endpoint.
- Enter the endpoint URL. It must use
https://and point at a public address. - Optionally add a description, such as
CRM sync. - Choose the events to send. All three are selected by default.
- 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.
| Action | What it does |
|---|---|
| Send test event | Sends one signed webhook.test event right away and shows your endpoint's answer. Test events aren't retried or billed. |
| Active switch | Pauses or resumes the endpoint. A paused endpoint receives nothing. |
| Show signing secret (key icon) | Shows the endpoint's current secret. |
| Rotate secret | Issues a new secret. The next request is signed with it, and the old one stops verifying at once. |
| Edit | Changes the URL, description or events. |
| Delete | Removes 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:
| Field | Description |
|---|---|
id | A unique ID for the event, starting evt_. Every endpoint that receives the event gets the same id. |
type | The event type, also sent in the X-VoisX-Event header. |
created_at | When the event happened, in ISO 8601 UTC. |
project_id | The project the conversation belongs to. |
data | The 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
| Field | Events | Description |
|---|---|---|
session_id | All | The conversation's ID, the same one Calls & transcripts shows. Use it to join the three events of one call. |
agent_id | All | The agent that handled the conversation. |
channel | call.started, call.ended | phone for a phone number or SIP trunk, widget for the website widget. |
duration_seconds | call.ended | The call's length in seconds, to one decimal place. |
end_reason | call.ended | Why the call ended: caller_hangup, browser_closed, agent_ended, transferred, silence_hangup, max_call_duration or error. |
turn_count | transcript.ready | The number of turns in transcript. |
transcript | transcript.ready | The 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.startedandcall.endedare sent for voice calls only.transcript.readyis sent for every channel. For a voice call it followscall.ended. For a text chat it is sent once the chat has been idle for 5 minutes. If the chat continues later, anothertranscript.readyis 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
2xxwithin 10 seconds. Do slow work after you answer. - Timeouts,
408,425,429and5xxanswers are retried up to 5 times over about 2 hours. Other statuses are final. - A retried request has the same
X-VoisX-Deliveryheader and the same body. Store theX-VoisX-Deliveryvalues you have handled and skip repeats. - Events can arrive out of order, for example when a
call.startedis retried after itscall.endedarrived. Usecreated_atto 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.