> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Call Webhook Events: Payloads for the call.* Triggers
> Reference for CloudTalk's call webhook events (call.started, call.ringing, call.answered, call.held, call.resumed, call.ended, call.recording_ready, and call.tags_modified) with example payloads and field definitions.
Call events track a call through its whole life. Every event for one call carries the same `call_uuid`, so you can join them into a single timeline:
`call.started` → `call.ringing` → `call.answered` → `call.held` / `call.resumed` → `call.ended` → `call.recording_ready`
One more event sits outside that sequence: [`call.tags_modified`](#call-tags-modified) fires whenever tags are added to or removed from a call, during the call or long after it ended. These are account-level webhooks, delivered to the endpoints you register under **Account → Webhooks**. See the [overview](/guides/webhooks/overview).
All examples on this page show the full request body, including the [envelope](/guides/webhooks/overview#the-event-envelope). Fields with empty values are omitted from payloads rather than sent as `null`. The one exception is `tags[].name` on [`call.tags_modified`](#call-tags-modified), which is explicitly nullable; accept `null` there. Fields shown in **bold** are always present. A bold field nested inside an optional object is always present whenever that object is. Everything else is optional.
## Common objects
Two objects appear across call events.
### The contact object
Each entry in `contacts` is a contact from your account that matches the call. Every field except `id` is included only when it has a value.
| Field | Type | Description |
| --------------- | --------- | ---------------------------------------------------------------------------------- |
| **`id`** | string | The contact's id in CloudTalk. |
| `type` | string | The contact kind: `contact` or `lead`. |
| `name` | string | The contact's display name. |
| `company` | string | Company name on the contact card. |
| `title` | string | Job title. |
| `industry` | string | Industry label. |
| `website` | string | Website URL. |
| `address` | string | Street address. Related fields: `city`, `state`, `zip`. |
| `phones` | string\[] | The contact's phone numbers, in E.164 format. |
| `emails` | string\[] | The contact's email addresses. |
| `country` | object | The contact's country: `{ "name": "United States", "country_code": "US" }`. |
| `tags` | string\[] | Tag names on the contact. |
| `custom_fields` | object | Your custom fields as a key-value map of strings. |
| `external_urls` | object\[] | Named external links on the contact. Each item: `{ "name": "...", "url": "..." }`. |
| `source` | string | Where the contact record originated. |
| `created_at` | string | When the contact was created. |
| `modified_at` | string | When the contact was last modified. |
### The user object
The `user` field identifies the CloudTalk user handling the call. It is omitted (never `null`) when no user is assigned yet. Every field except `id` is included only when it has a value. The same object appears wherever a user is referenced on other events: `favorite_user` on contacts, `user` on messages, and `callers[].user` on Conversation Intelligence events.
| Field | Type | Description |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`id`** | string | The user's id in CloudTalk. |
| `name` | string | Display name. |
| `first_name` | string | First name. |
| `last_name` | string | Last name. |
| `email` | string | The user's email address. |
| `role` | string | The user's role. Current values: `admin`, `agent`, `supervisor`, `analyst`. Other values are possible on some accounts, and new ones may be added over time; handle unknown values gracefully rather than failing. |
| `language` | string | The user's default language. |
| `extension` | string | The user's internal extension. |
| `created_at` | string | When the user was created, UTC ISO 8601. |
| `modified_at` | string | When the user's profile was last changed, UTC ISO 8601. |
### Number types
Every number object (`internal_number` on call and message events, `default_outbound_number.number` and `associated_numbers[]` on user events) carries a `number_type` with one of these values:
| Value | Meaning |
| ----------------- | ------------------------------ |
| `fixed` | A landline (geographic) number |
| `mobile` | A mobile number |
| `toll_free` | A toll-free number |
| `premium_rate` | A premium-rate number |
| `shared_cost` | A shared-cost number |
| `voip` | A VoIP number |
| `personal_number` | A personal number |
| `pager` | A pager number |
| `uan` | A universal access number |
| `emergency` | An emergency number |
| `voicemail` | A voicemail access number |
New values may be added over time; handle unknown values gracefully rather than failing.
### Large contact sets
A call can match many contacts, and a number shared by many contacts does so routinely. To keep every payload deliverable, the first **10** matching contacts are included in full; any beyond that are included as `{ "id": "44211" }` only, carrying the id and nothing else, and the event carries `"contacts_truncated": true`. Fetch the details of the id-only entries from the [Contacts API](/api-reference) when you need them.
Every event that carries `contacts` also carries `contacts_total`, the number of contacts that matched before any trimming. Compare it with the length of `contacts`:
* **Equal**: every matched contact is present, some as id only. You are missing detail, not contacts.
* **Greater**: the matched set was so large that trailing ids had to be dropped to keep the event deliverable. You are missing contacts entirely and cannot tell which; fetch the call's contacts from the API instead.
One more case sets `contacts_truncated` at any list size: a single very large contact record (many custom fields, phone numbers or emails) is reduced to `{ "id" }` when the set would otherwise exceed its size budget. When nothing was trimmed, `contacts_truncated` is absent.
This applies to every call event that carries `contacts`: `call.started`, `call.ringing`, `call.answered`, `call.ended`, and `call.recording_ready`.
## call.started
Fires the moment a call begins: as soon as an inbound call reaches your account or an outbound call is placed, before anyone picks up. Use it to pop the caller's record in your CRM, start tracking a live call on a wallboard, or kick off any workflow that needs to know a conversation is underway.
```json Example theme={"system"}
{
"event_id": "1a2b3c4d-5e6f-8a1b-9c2d-3e4f5a6b7c8d",
"type": "call.started",
"version": "v1",
"occurred_at": "2026-08-17T09:34:21.512Z",
"company_id": "123456",
"data": {
"call_uuid": "018f7d3a-2b4c-7e5f-9a6b-1c2d3e4f5a6b",
"direction": "inbound",
"external_number": "+12025550143",
"internal_number": {
"number_e164": "+12025550178",
"id": "9911",
"internal_name": "Sales line",
"number_type": "fixed",
"country": "US"
},
"group": {
"id": "501",
"name": "Sales",
"extension": "07"
},
"contacts": [
{
"id": "44210",
"type": "contact",
"name": "Jane Doe",
"company": "Acme Corp",
"phones": ["+12025550143"],
"emails": ["jane.doe@example.com"],
"country": { "name": "United States", "country_code": "US" },
"tags": ["vip", "priority"],
"custom_fields": { "crm_id": "ACME-0042" },
"source": "manual",
"created_at": "2026-05-04T10:00:00Z",
"modified_at": "2026-08-01T12:30:00Z"
}
],
"contacts_total": 1,
"user": {
"id": "987654",
"name": "John Smith",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"role": "agent",
"language": "en",
"extension": "1001"
}
}
}
```
| Field | Type | Description |
| --------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`call_uuid`** | string | The call's unique id, shared by every event in this call's lifecycle. |
| `direction` | string | The call direction: `inbound` or `outbound`. |
| `external_number` | string | The external party's phone number, in E.164 format. Absent when the caller withheld it; `caller_id_status` then says why. |
| `caller_id_status` | string | Why the external party's number is absent, when the caller withheld it (CLIR): `withheld`, `unavailable`, `restricted`, `unknown`, or `blocked`. Present only in that case, so `external_number` and `caller_id_status` never appear together. Read `unknown` loosely: it covers both a carrier that signalled UNKNOWN and a sentinel we could not attribute. |
| `internal_number` | object | The CloudTalk-side number the call ran through. Present whenever the source event carried a number. |
| **`internal_number.number_e164`** | string | The number in E.164 format, exactly as the call carried it. |
| `internal_number.id` | string | The number's id in CloudTalk. Present only when the number resolves to one your account owns. |
| `internal_number.internal_name` | string | Your own label for the number. |
| `internal_number.number_type` | string | The number type, for example `fixed`, `mobile`, or `toll_free`. See [number types](#number-types). |
| `internal_number.country` | string | The number's country as an ISO 3166-1 alpha-2 code, for example `US`. |
| `group` | object | The call group (queue) the call came through. Best effort: absence does not prove the call had no group. |
| **`group.id`** | string | The group's id in CloudTalk. |
| `group.name` | string | Your own label for the group. |
| `group.extension` | string | The group's dialable extension, as a string so a leading zero survives. |
| **`contacts`** | Contact\[] | Contacts from your account matching the call. See [the contact object](#the-contact-object). Always present; `[]` when nothing matched. |
| `contacts_truncated` | boolean | Present and `true` when `contacts` carries less than the full detail of every matched contact: more than 10 matched, or a very large contact was reduced to its id. Absent when nothing was trimmed. See [large contact sets](#large-contact-sets). |
| `contacts_total` | integer | How many contacts matched the call before any trimming. Absent when none matched. Compare with the length of `contacts`; see [large contact sets](#large-contact-sets). |
| `user` | User | The assigned user. See [the user object](#the-user-object). Often not yet present on `call.started` for inbound calls. |
## call.ringing
Fires when a call starts ringing on a specific user's phone or app. Use it to alert the right person in your own tools, show who is being called on a live dashboard, or prepare a screen pop before the user picks up.
The payload has the same shape as [`call.started`](#call-started); `user` identifies the user being rung.
```json Example theme={"system"}
{
"event_id": "2b3c4d5e-6f70-8b2c-9d3e-4f5a6b7c8d9e",
"type": "call.ringing",
"version": "v1",
"occurred_at": "2026-08-17T09:34:24.030Z",
"company_id": "123456",
"data": {
"call_uuid": "018f7d3a-2b4c-7e5f-9a6b-1c2d3e4f5a6b",
"direction": "inbound",
"external_number": "+12025550143",
"internal_number": {
"number_e164": "+12025550178",
"id": "9911",
"internal_name": "Sales line",
"number_type": "fixed",
"country": "US"
},
"group": {
"id": "501",
"name": "Sales",
"extension": "07"
},
"contacts": [
{
"id": "44210",
"name": "Jane Doe",
"company": "Acme Corp",
"phones": ["+12025550143"],
"emails": ["jane.doe@example.com"]
}
],
"contacts_total": 1,
"user": {
"id": "987654",
"name": "John Smith",
"email": "john.smith@example.com",
"role": "agent",
"extension": "1001"
}
}
}
```
A call that rings several users in sequence or in parallel can produce more than one `call.ringing` event. Each identifies the user being rung.
## call.answered
Fires when a call is picked up and the conversation begins. Use it to log pickup times, start measuring talk time, or update a live view of ongoing conversations.
The payload has the same shape as [`call.started`](#call-started); `user` identifies the user who answered.
```json Example theme={"system"}
{
"event_id": "3c4d5e6f-7081-8c3d-9e4f-5a6b7c8d9e0f",
"type": "call.answered",
"version": "v1",
"occurred_at": "2026-08-17T09:34:29.877Z",
"company_id": "123456",
"data": {
"call_uuid": "018f7d3a-2b4c-7e5f-9a6b-1c2d3e4f5a6b",
"direction": "inbound",
"external_number": "+12025550143",
"internal_number": {
"number_e164": "+12025550178",
"id": "9911",
"internal_name": "Sales line",
"number_type": "fixed",
"country": "US"
},
"group": {
"id": "501",
"name": "Sales",
"extension": "07"
},
"contacts": [
{
"id": "44210",
"name": "Jane Doe",
"company": "Acme Corp",
"phones": ["+12025550143"],
"emails": ["jane.doe@example.com"]
}
],
"contacts_total": 1,
"user": {
"id": "987654",
"name": "John Smith",
"email": "john.smith@example.com",
"role": "agent",
"extension": "1001"
}
}
}
```
## call.held
Fires when a call is placed on hold. Use it to measure hold time, keep live dashboards accurate, or trigger reminders when a hold runs long.
Hold events carry the call reference and, when the hold is attributable to one, the user. Join on `call_uuid` with the other lifecycle events for contact and number context.
```json Example theme={"system"}
{
"event_id": "4d5e6f70-8192-8d4e-9f5a-6b7c8d9e0f1a",
"type": "call.held",
"version": "v1",
"occurred_at": "2026-08-17T09:36:05.120Z",
"company_id": "123456",
"data": {
"call_uuid": "018f7d3a-2b4c-7e5f-9a6b-1c2d3e4f5a6b",
"user": {
"id": "987654",
"name": "John Smith",
"email": "john.smith@example.com",
"role": "agent",
"extension": "1001"
}
}
}
```
| Field | Type | Description |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **`call_uuid`** | string | The call's unique id: join hold periods to the call's other events. |
| `user` | User | The user who put the call on hold. See [the user object](#the-user-object). Omitted when the hold isn't attributable to a single user. |
## call.resumed
Fires when a call is taken off hold. Pair it with `call.held` to calculate hold durations, or use it to keep live call status accurate.
The payload has the same shape as [`call.held`](#call-held).
```json Example theme={"system"}
{
"event_id": "5e6f7081-92a3-8e5f-9a6b-7c8d9e0f1a2b",
"type": "call.resumed",
"version": "v1",
"occurred_at": "2026-08-17T09:37:12.443Z",
"company_id": "123456",
"data": {
"call_uuid": "018f7d3a-2b4c-7e5f-9a6b-1c2d3e4f5a6b",
"user": {
"id": "987654",
"name": "John Smith",
"email": "john.smith@example.com",
"role": "agent",
"extension": "1001"
}
}
}
```
When computing hold durations, tolerate unpaired events: a `call.resumed` can arrive without a preceding `call.held`, and delivery order is not guaranteed. Pair on `call_uuid` and order by `occurred_at`.
## call.ended
Fires when a call finishes and its final details have been processed: direction, the numbers involved, start time, durations, whether the call was recorded, and whether it went to voicemail, together with the matched contacts and the user who handled it. Use it to log completed calls in your CRM or helpdesk, trigger post-call follow-ups, or feed reporting the moment a call wraps up.
If the call was recorded, the recording is announced separately (sometimes minutes later) by [`call.recording_ready`](#call-recording-ready). Don't expect recording details on `call.ended`.
```json Example theme={"system"}
{
"event_id": "1f3a9c2e-6b4d-8a2f-9c1d-7e5f3a2b4c6d",
"type": "call.ended",
"version": "v1",
"occurred_at": "2026-08-17T09:41:23.512Z",
"company_id": "123456",
"data": {
"call_id": "143223459",
"call_uuid": "018f4a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
"direction": "incoming",
"external_number": "+12025550143",
"internal_number": {
"number_e164": "+12025550178",
"id": "9911",
"internal_name": "Sales line",
"number_type": "fixed",
"country": "US"
},
"started_at": "2026-08-17T09:38:05Z",
"ended_at": "2026-08-17T09:41:23Z",
"talking_time": 154,
"waiting_time": 44,
"duration": 198,
"recorded": true,
"is_voicemail": false,
"contacts": [
{
"id": "2499629",
"type": "contact",
"name": "Jane Doe",
"company": "Acme Corp",
"phones": ["+12025550143"],
"emails": ["jane.doe@example.com"],
"tags": ["vip"],
"source": "api",
"created_at": "2026-05-01T08:00:00Z",
"modified_at": "2026-08-10T12:34:56Z"
}
],
"contacts_total": 1,
"user": {
"id": "705013",
"name": "John Roe",
"first_name": "John",
"last_name": "Roe",
"email": "john.roe@example.com",
"role": "agent",
"language": "en",
"extension": "1001"
}
}
}
```
| Field | Type | Description |
| -------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`call_id`** | string | The call's id in call history. Also carried by `call.recording_ready` and usable with the [call history API](/api-reference). |
| **`call_uuid`** | string | The same call reference used by the live lifecycle events. |
| `direction` | string | The call direction: `incoming`, `outgoing`, `internal`, or `monitor`. Note this differs from the live events' `inbound` / `outbound` values. |
| `external_number` | string | The external party's phone number, in E.164 format. Absent when the caller withheld it; `caller_id_status` then says why. |
| `caller_id_status` | string | Why the external party's number is absent (CLIR): `withheld`, `unavailable`, `restricted`, `unknown`, or `blocked`. See [`call.started`](#call-started). |
| `internal_number` | object | The CloudTalk-side number the call ran through. Same shape as on [`call.started`](#call-started): `number_e164` (always present), plus `id`, `internal_name`, `number_type` and `country` when the number resolves to one your account owns. |
| `started_at` | string | When the call started, UTC ISO 8601. |
| `ended_at` | string | When the call ended, UTC ISO 8601. On this event the envelope's `occurred_at` is the same instant, the call's end, rather than the moment CloudTalk finished processing it. |
| `talking_time` | integer | Talking time in seconds. Omitted when not available; never reported as a misleading `0`. |
| `waiting_time` | integer | Time before the conversation started, in seconds (`duration` minus `talking_time`). |
| `duration` | integer | Total call duration in seconds. |
| `recorded` | boolean | Whether the call was recorded. When `true`, expect a `call.recording_ready` event to follow. |
| `is_voicemail` | boolean | Whether the call ended in voicemail. |
| **`contacts`** | Contact\[] | Matched contacts. See [the contact object](#the-contact-object). `[]` when none. |
| `contacts_truncated` | boolean | Present and `true` when `contacts` carries less than the full detail of every matched contact. See [large contact sets](#large-contact-sets). |
| `contacts_total` | integer | How many contacts matched the call before any trimming. Absent when none matched. See [large contact sets](#large-contact-sets). |
| `user` | User | The user on the call. See [the user object](#the-user-object). |
## call.recording\_ready
Fires when a call's recording (including voicemail messages) has been stored and is available. This is an asynchronous event: it fires after `call.ended`, sometimes minutes later. Use it to kick off post-call workflows such as QA review, coaching, or attaching the recording reference to your CRM record of the call.
It fires for **every recorded call**. The only prerequisite is that call recording is switched on for that direction in your account settings; transcription and Conversation Intelligence are not required.
The event does not include a download link. Use `call_id` with the [Recording media](/api-reference/calls/recording-media) endpoint to retrieve the recording with your API credentials.
```json Example theme={"system"}
{
"event_id": "2b4c6d8e-0f1a-8c3e-9d5f-1a2b3c4d5e6f",
"type": "call.recording_ready",
"version": "v1",
"occurred_at": "2026-08-17T09:41:31.208Z",
"company_id": "123456",
"data": {
"call_id": "143223459",
"call_uuid": "018f4a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
"contacts": [
{
"id": "2499629",
"type": "contact",
"name": "Jane Doe",
"company": "Acme Corp",
"phones": ["+12025550143"],
"emails": ["jane.doe@example.com"]
}
],
"contacts_total": 1
}
}
```
| Field | Type | Description |
| -------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **`call_id`** | string | The call's id in call history: matches `call.ended`'s `call_id` for the same call. |
| **`call_uuid`** | string | The same call reference as all other call events. |
| `contacts` | Contact\[] | Contacts matched to the call. See [the contact object](#the-contact-object). |
| `contacts_truncated` | boolean | Present and `true` when `contacts` carries less than the full detail of every matched contact. See [large contact sets](#large-contact-sets). |
| `contacts_total` | integer | How many contacts matched the call before any trimming. Absent when none matched. See [large contact sets](#large-contact-sets). |
Voicemail recordings arrive as regular `call.recording_ready` events. To tell whether a recording is a voicemail, check `is_voicemail` on the matching `call.ended` event (same `call_id`).
## call.tags\_modified
Fires when tags are added to or removed from a call: by a user during or after the call, or by an automation. Use it to mirror call tagging into your CRM or ticketing system, trigger follow-ups when a specific tag is applied, or drive reporting on how calls are categorised.
Each event describes **one change**: the direction (`added` or `removed`) and the tags involved. It is a delta, not the call's full tag list; to know a call's current tags, fetch the call from the API rather than reconstructing them from a sequence of events.
```json Example theme={"system"}
{
"event_id": "6f708192-a3b4-8f6a-9b7c-8d9e0f1a2b3c",
"type": "call.tags_modified",
"version": "v1",
"occurred_at": "2026-08-17T09:43:10.221Z",
"company_id": "123456",
"data": {
"call_id": "143223459",
"call_uuid": "018f4a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
"tag_action": "added",
"tags": [
{ "id": "311", "name": "billing" },
{ "id": "415", "name": "follow-up" }
]
}
}
```
| Field | Type | Description |
| ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`call_uuid`** | string | The call the tags were changed on: the same reference as all other call events. |
| `call_id` | string | The call's id in call history. Omitted when the tags were changed on a call that is still in progress and has no call-history record yet. |
| **`tag_action`** | string | `added`: the tags were attached to the call. `removed`: they were detached from it. The tags themselves are never created or deleted by this event; only their assignment to this call changed. |
| **`tags`** | object\[] | The tags in this change: at least one. |
| **`tags[].id`** | string | The tag's id. Correlate on this rather than on `name`, which can be renamed. |
| `tags[].name` | string \| null | The tag's name at the time of the change. `null` only if the tag itself was deleted from your account in the meantime. |
Unlike the other call events, `call.tags_modified` carries no `contacts` or `user`. For that context, join on `call_uuid` with the `call.started` or `call.ended` event you stored, or fetch the call from the API.
## Related topics
- [User Webhook Events: Payloads for the user.* Triggers](/guides/webhooks/events/users.md)
- [Message Webhook Events: Payloads for the message.* Triggers](/guides/webhooks/events/messages.md)
- [Contact Webhook Events: Payloads for the contact.* Triggers](/guides/webhooks/events/contacts.md)