> ## 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. # User Webhook Events: Payloads for the user.* Triggers > Reference for CloudTalk's user webhook events (user.created, user.updated, user.deleted, and user.status_changed) with example payloads and field definitions. 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](/guides/webhooks/overview). All examples show the full request body, including the [envelope](/guides/webhooks/overview#the-event-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. ```json Example theme={"system"} { "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](/guides/webhooks/events/calls#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](/guides/webhooks/events/calls#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`](#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. ```json Example theme={"system"} { "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. ```json Example theme={"system"} { "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. ```json Example theme={"system"} { "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. ## Related topics - [Call Webhook Events: Payloads for the call.* Triggers](/guides/webhooks/events/calls.md) - [Contact Webhook Events: Payloads for the contact.* Triggers](/guides/webhooks/events/contacts.md) - [Message Webhook Events: Payloads for the message.* Triggers](/guides/webhooks/events/messages.md)