Call Webhook Events: Payloads for the call.* Triggers

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 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. All examples on this page show the full request body, including the envelope. Fields with empty values are omitted from payloads rather than sent as null. The one exception is tags[].name on 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 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.

Example

{
  "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.
`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. 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.
`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.
`user`	User	The assigned user. See 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; user identifies the user being rung.

Example

{
  "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; user identifies the user who answered.

Example

{
  "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.

Example

{
  "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. 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.

Example

{
  "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. Don’t expect recording details on call.ended.

Example

{
  "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.
`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`.
`internal_number`	object	The CloudTalk-side number the call ran through. Same shape as on `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. `[]` when none.
`contacts_truncated`	boolean	Present and `true` when `contacts` carries less than the full detail of every matched contact. See large contact sets.
`contacts_total`	integer	How many contacts matched the call before any trimming. Absent when none matched. See large contact sets.
`user`	User	The user on the call. See 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 endpoint to retrieve the recording with your API credentials.

Example

{
  "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.
`contacts_truncated`	boolean	Present and `true` when `contacts` carries less than the full detail of every matched contact. See large contact sets.
`contacts_total`	integer	How many contacts matched the call before any trimming. Absent when none matched. See 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.

Example

{
  "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.

​Common objects

​The contact object

​The user object

​Number types

​Large contact sets

​call.started

​call.ringing

​call.answered

​call.held

​call.resumed

​call.ended

​call.recording_ready

​call.tags_modified

Common objects

The contact object

The user object

Number types

Large contact sets

call.started

call.ringing

call.answered

call.held

call.resumed

call.ended

call.recording_ready

call.tags_modified