User Webhook Events: Payloads for the user.* Triggers

User events cover the people on your CloudTalk account: profile changes (user.created, user.updated, user.deleted) and real-time availability (user.status_changed). These are account-level webhooks, delivered to the endpoints you register under Account → Webhooks. See the overview. All examples show the full request body, including the envelope. Fields with empty values are omitted from payloads: they are never sent as null. 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.

user.created

Fires when a new user is added to your account. The payload carries the user’s full profile (name, email, role, language, extension, timestamps), how their outbound number is chosen, and, when CloudTalk can resolve them, the call groups they belong to and the numbers assigned to them. Use it to automatically provision the new team member in your CRM, helpdesk or workforce-management tools.

Example

{
  "event_id": "018f4a2b-9c3d-8f1e-9b2a-3c4d5e6f7081",
  "type": "user.created",
  "version": "v1",
  "occurred_at": "2026-08-17T09:34:21.512Z",
  "company_id": "123456",
  "data": {
    "id": "4207",
    "name": "Jane Doe",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "role": "agent",
    "language": "en",
    "extension": "1042",
    "created_at": "2026-08-17T09:34:20Z",
    "modified_at": "2026-08-17T09:34:20Z",
    "default_outbound_number": {
      "mode": "specific",
      "number": {
        "id": "9911",
        "number_e164": "+12025550143",
        "internal_name": "Sales line",
        "number_type": "fixed",
        "country": "US"
      }
    },
    "groups": [
      { "id": "501", "name": "Sales", "extension": "07" },
      { "id": "502" }
    ],
    "associated_numbers": [
      {
        "id": "9911",
        "number_e164": "+12025550143",
        "internal_name": "Sales line",
        "number_type": "fixed",
        "country": "US"
      },
      {
        "id": "9914",
        "number_e164": "+18005550199",
        "internal_name": "Support line",
        "number_type": "toll_free",
        "country": "US"
      }
    ]
  }
}

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.
`default_outbound_number`	object	How the user’s outbound caller number is chosen. Always present.
`default_outbound_number.mode`	string	`specific`: one fixed number, given in `number`. `automatic`: CloudTalk picks the number closest to the contact’s location on each call. `smart_rotation`: CloudTalk cycles through the user’s numbers on each call. `number` never appears with `automatic` or `smart_rotation`, because no single number applies.
`default_outbound_number.number`	object	The fixed number, present only when `mode` is `specific` and CloudTalk could resolve it. Absent under `specific` when the user has no default set, the number was deleted, or the lookup could not complete.
`default_outbound_number.number.id`	string	The number’s id in CloudTalk.
`default_outbound_number.number.number_e164`	string	The phone number, in E.164 format where available, otherwise the number’s public caller id.
`default_outbound_number.number.internal_name`	string	Your own label for the number.
`default_outbound_number.number.number_type`	string	The number type, for example `fixed`, `mobile`, or `toll_free`. See number types.
`default_outbound_number.number.country`	string	The number’s country as an ISO 3166-1 alpha-2 code, for example `US`.
`groups`	object[]	The call groups (queues) the user belongs to. Best effort: absence does not prove the user belongs to no group.
`groups[].id`	string	The group’s id in CloudTalk.
`groups[].name`	string	Your own label for the group. Omitted when the group has no label: the id is always present.
`groups[].extension`	string	The group’s dialable extension, as a string so a leading zero survives.
`associated_numbers`	object[]	The numbers explicitly assigned to the user: the ones offered in their outbound picker. Each entry has the same shape as `default_outbound_number.number`. This is a separate setting from the default: the default number is included only if it is also assigned. Best effort: absence does not prove the user has no assigned numbers.
`associated_numbers[].id`	string	The number’s id in CloudTalk.
`associated_numbers[].number_e164`	string	The phone number, in E.164 format where available.
`associated_numbers[].internal_name`	string	Your own label for the number.
`associated_numbers[].number_type`	string	The number type. See number types.
`associated_numbers[].country`	string	ISO 3166-1 alpha-2 country code.
`truncated`	string[]	Present only when a very long field had to be shortened to keep the event deliverable. Today it can only name `associated_numbers`, cut after 50 entries. Absent means nothing was shortened.

user.updated

Fires when a user’s profile changes: their name, email, role, language, extension, outbound number selection, assigned numbers or group membership. The payload carries the user’s full, current profile (the same shape as user.created), so you can overwrite the profile fields in your copy to stay in sync. To find out what changed, compare with the version you previously stored. Treat groups and associated_numbers with more care: both are resolved best effort, so their absence means either that the set is empty or that CloudTalk could not resolve it at that moment. If the difference matters to you, confirm the current membership through the API before clearing your stored copy.

Example

{
  "event_id": "018f4a2b-9c3d-8f1e-9b2a-3c4d5e6f7082",
  "type": "user.updated",
  "version": "v1",
  "occurred_at": "2026-08-17T10:12:05.004Z",
  "company_id": "123456",
  "data": {
    "id": "4207",
    "name": "Jane Doe",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "role": "supervisor",
    "language": "de",
    "extension": "1042",
    "created_at": "2026-08-17T09:34:20Z",
    "modified_at": "2026-08-17T10:12:04Z",
    "default_outbound_number": {
      "mode": "smart_rotation"
    },
    "groups": [
      { "id": "501", "name": "Sales", "extension": "07" },
      { "id": "502" }
    ],
    "associated_numbers": [
      {
        "id": "9911",
        "number_e164": "+12025550143",
        "internal_name": "Sales line",
        "number_type": "fixed",
        "country": "US"
      },
      {
        "id": "9914",
        "number_e164": "+18005550199",
        "internal_name": "Support line",
        "number_type": "toll_free",
        "country": "US"
      }
    ]
  }
}

user.deleted

Fires when a user is removed from your account. Because the user no longer exists, the payload carries only their id: it matches the id from earlier user.created and user.updated events. Use it to deactivate or archive that person in your connected systems.

Example

{
  "event_id": "018f4a2b-9c3d-8f1e-9b2a-3c4d5e6f7083",
  "type": "user.deleted",
  "version": "v1",
  "occurred_at": "2026-08-17T11:02:44.310Z",
  "company_id": "123456",
  "data": {
    "id": "4207"
  }
}

Field	Type	Description
`id`	string	The deleted user’s id.

user.status_changed

Fires every time a user’s availability changes: when they go online, pick an away status, go offline, or start and finish a call. Use it to power live wallboards, presence indicators, or workforce-management tools that need to know who is available right now.

Example

{
  "event_id": "018f4a2b-9c3d-8f1e-9b2a-3c4d5e6f7084",
  "type": "user.status_changed",
  "version": "v1",
  "occurred_at": "2026-08-17T10:30:00Z",
  "company_id": "123456",
  "data": {
    "user_id": "4207",
    "status": "idle",
    "sub_status": "Lunch",
    "sub_status_id": "19"
  }
}

Field	Type	Description
`user_id`	string	The user whose status changed.
`status`	string	The user’s new availability. One value per event, from the list below. New values may be added over time; handle unknown values gracefully rather than failing.
`sub_status`	string	The name of the status the user has selected, as it appears in CloudTalk: Online, Lunch, Meeting, or any custom status your account has created. Free text, not a fixed list. On `on_call` it carries the status the user had picked before the call.
`sub_status_id`	string	The stable id of that selected status. An admin can rename a status at any time, so key any automation on this field rather than on `sub_status`.

What each status means

CloudTalk resolves a user’s availability from three inputs, in this order: whether they are connected at all, whether they are in a call, and which status they picked themselves. When a call ends, the status returns to the value the picked status resolves to. The first input that applies wins, so a user in a call reads as on_call no matter which status label they chose.

Status	Meaning
`online`	The user is connected and available to take calls. Their chosen status is one that counts as available, such as Online.
`idle`	The user is connected but not available. This is what every “away” style status resolves to: Busy, Break, Lunch, Meeting, Training, and any custom status your account has created. `sub_status` tells you which one.
`offline`	The user is not available to take calls, either because they set themselves Offline or because they are not connected.
`on_call`	The user is currently on a call. This overrides whatever status they picked; the picked status stays in `sub_status`.

This is a high-frequency event on busy accounts. The payload is deliberately minimal: join user_id against the profile data you received from user.created and user.updated. Switching between two statuses that resolve to the same status value, for example Lunch to Meeting, does produce an event: status stays idle and sub_status changes.

​user.created

​user.updated

​user.deleted

​user.status_changed

​What each status means

user.created

user.updated

user.deleted

user.status_changed

What each status means