Skip to content

feat(docs): extend customer object with omnichannel and phone number #1620

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
oliwiapolec merged 30 commits into from
Dec 15, 2025
Merged

feat(docs): extend customer object with omnichannel and phone number #1620

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
adb710f
feat(docs): extend customer object with omnichannel and phone number
GGuinea Nov 17, 2025
eef55c6
feat(docs): current version updates
GGuinea Nov 20, 2025
4e3b9ad
feat(docs): even more omnichannel fixes
GGuinea Nov 20, 2025
33e5c48
feat(docs): remove payloads, filled changelog
GGuinea Nov 20, 2025
c369456
feat(docs): fixups
GGuinea Nov 20, 2025
802bcbb
feat(docs): cr reveiw
GGuinea Dec 2, 2025
2ce017b
feat(docs): fixup
GGuinea Dec 3, 2025
3611784
Update src/pages/messaging/agent-chat-api/rtm-reference/index.mdx
GGuinea Dec 10, 2025
1dfd3ef
Update src/pages/messaging/agent-chat-api/v3.7/index.mdx
GGuinea Dec 10, 2025
9cbf060
Update src/pages/messaging/agent-chat-api/v3.7/rtm-reference/index.mdx
GGuinea Dec 10, 2025
d264e43
Update src/pages/messaging/customer-chat-api/data-structures/index.mdx
GGuinea Dec 10, 2025
0a0ce09
Update src/pages/messaging/agent-chat-api/index.mdx
GGuinea Dec 10, 2025
c07027f
Update src/pages/messaging/customer-chat-api/v3.7/data-structures/ind…
GGuinea Dec 10, 2025
fc157ec
Update src/pages/messaging/agent-chat-api/v3.7/data-structures/index.mdx
GGuinea Dec 10, 2025
4065f47
Update src/pages/messaging/customer-chat-api/index.mdx
GGuinea Dec 10, 2025
bc4b3ba
Update src/pages/messaging/customer-chat-api/v3.7/data-structures/ind…
GGuinea Dec 10, 2025
274c3e6
Update src/pages/messaging/customer-chat-api/v3.7/rtm-reference/index…
GGuinea Dec 10, 2025
8bf454d
Update src/pages/messaging/customer-chat-api/rtm-reference/index.mdx
GGuinea Dec 10, 2025
862a029
Update src/pages/messaging/customer-chat-api/v3.7/index.mdx
GGuinea Dec 10, 2025
e4e2a4e
Update src/pages/messaging/customer-chat-api/rtm-reference/index.mdx
GGuinea Dec 10, 2025
8ca81b9
Update src/pages/messaging/customer-chat-api/v3.7/rtm-reference/index…
GGuinea Dec 10, 2025
8baf4a3
Update src/pages/messaging/customer-chat-api/rtm-reference/index.mdx
GGuinea Dec 10, 2025
16fe9ff
Update src/pages/messaging/agent-chat-api/rtm-reference/index.mdx
GGuinea Dec 10, 2025
0905177
Update src/pages/messaging/agent-chat-api/v3.7/rtm-reference/index.mdx
GGuinea Dec 10, 2025
45d55af
Update src/pages/messaging/agent-chat-api/rtm-reference/index.mdx
GGuinea Dec 10, 2025
c58c5d5
Update src/pages/messaging/agent-chat-api/v3.7/index.mdx
GGuinea Dec 10, 2025
f18bd5c
Update src/pages/messaging/agent-chat-api/v3.7/rtm-reference/index.mdx
GGuinea Dec 10, 2025
98f0b5b
Update src/pages/messaging/customer-chat-api/v3.7/rtm-reference/index…
GGuinea Dec 10, 2025
e01b1d7
Update src/pages/messaging/agent-chat-api/v3.7/index.mdx
GGuinea Dec 10, 2025
60ad1b8
feat(docs): fixup v123
GGuinea Dec 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 23 additions & 1 deletion payloads/messaging/v3.6/agent-chat-api/users/customer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
"email": "t.anderson@example.com",
"email_verified": false,
"avatar": "https://example.com/avatars/1.png",
"phone_number": "+18008529001",
"visit": {
"started_at": "2017-10-12T15:19:21.010200Z",
"ended_at": "2017-10-12T15:21:01.000000Z",
Expand Down Expand Up @@ -60,5 +61,26 @@
"ticket_id": "0c04cb99-817a-4935-9d62-137c89a74388",
"created_at": "2017-10-12T15:19:21.010200Z"
}],
"state": "browsing"
"state": "browsing",
"omnichannel": {
"fb_messenger": [
{
"ID": "fb_messenger_id",
"Name": "Thomas Anderson",
"FirstName": "Thomas",
"LastName": "Anderson",
"ProfilePicURL": "https://example.com/avatars/1.png",
"Gender": "male",
"Locale": "EN_US",
"IsVerifiedUser": true
}
],
"twilio": [
{
"+18008529001": {
"phone_number": "+18008529001"
}
}
]
}
}
24 changes: 23 additions & 1 deletion payloads/messaging/v3.6/customer-chat-api/users/customer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
"email": "t.anderson@example.com",
"email_verified": false,
"avatar": "https://example.com/avatar.png",
"phone_number": "+18008529001",
"session_fields": [
{
"custom_key": "custom_value"
Expand All @@ -14,5 +15,26 @@
}
],
"present": true,
"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
"events_seen_up_to": "2017-10-12T15:19:21.010200Z",
"omnichannel": {
"fb_messenger": [
{
"ID": "fb_messenger_id",
"Name": "Thomas Anderson",
"FirstName": "Thomas",
"LastName": "Anderson",
"ProfilePicURL": "https://example.com/avatars/1.png",
"Gender": "male",
"Locale": "EN_US",
"IsVerifiedUser": true
}
],
"twilio": [
{
"+18008529001": {
"phone_number": "+18008529001"
}
}
]
}
}
24 changes: 23 additions & 1 deletion payloads/messaging/v3.7/agent-chat-api/users/customer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
"email": "t.anderson@example.com",
"email_verified": false,
"avatar": "https://example.com/avatars/1.png",
"phone_number": "+18008529001",
"visit": {
"started_at": "2017-10-12T15:19:21.010200Z",
"ended_at": "2017-10-12T15:21:01.000000Z",
Expand Down Expand Up @@ -60,5 +61,26 @@
"ticket_id": "0c04cb99-817a-4935-9d62-137c89a74388",
"created_at": "2017-10-12T15:19:21.010200Z"
}],
"state": "browsing"
"state": "browsing",
"omnichannel": {
"fb_messenger": [
{
"ID": "fb_messenger_id",
"Name": "Thomas Anderson",
"FirstName": "Thomas",
"LastName": "Anderson",
"ProfilePicURL": "https://example.com/avatars/1.png",
"Gender": "male",
"Locale": "EN_US",
"IsVerifiedUser": true
}
],
"twilio": [
{
"+18008529001": {
"phone_number": "+18008529001"
}
}
]
}
}
24 changes: 23 additions & 1 deletion payloads/messaging/v3.7/customer-chat-api/users/customer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
"email": "t.anderson@example.com",
"email_verified": false,
"avatar": "https://example.com/avatar.png",
"phone_number": "+18008529001",
"session_fields": [
{
"custom_key": "custom_value"
Expand All @@ -14,5 +15,26 @@
}
],
"present": true,
"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
"events_seen_up_to": "2017-10-12T15:19:21.010200Z",
"omnichannel": {
"fb_messenger": [
{
"ID": "fb_messenger_id",
"Name": "Thomas Anderson",
"FirstName": "Thomas",
"LastName": "Anderson",
"ProfilePicURL": "https://example.com/avatars/1.png",
"Gender": "male",
"Locale": "EN_US",
"IsVerifiedUser": true
}
],
"twilio": [
{
"+18008529001": {
"phone_number": "+18008529001"
}
}
]
}
}
2 changes: 2 additions & 0 deletions src/pages/messaging/agent-chat-api/changelog/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,8 @@ The developer preview version provides a preview of the upcoming changes to the
- [**ticket_created**](/messaging/agent-chat-api/rtm-pushes/#ticket_created)
- [**ticket_deleted**](/messaging/agent-chat-api/rtm-pushes/#ticket_deleted)
- [**customer_statistics_updated**](/messaging/agent-chat-api/rtm-pushes/#customer_statistics_updated)
- The [**Customer**](/messaging/agent-chat-api/data-structures#customer) data structure now contains information about phone number and omnichannel data (when available).
- The **Update Customer** ([Web](/messaging/agent-chat-api/#update-customer) & [RTM](/messaging/agent-chat-api/rtm-reference/#update-customer)) method has new fields, `phone_number` and `omnichannel`.

### Status

Expand Down
3 changes: 3 additions & 0 deletions src/pages/messaging/agent-chat-api/data-structures/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -412,10 +412,12 @@ It is not possible to send a System event in API version 3.6.
| `email_verified` | optional | Specifies if the customer confirmed their email address. See [Request Email Verification](/messaging/customer-chat-api/v3.6/#request-email-verification). |
| `session_fields` | optional | An array of custom object-enclosed `key:value` pairs. Expires along with the session. |
| `name` | optional | |
| `phone_number` | optional | |
| `events_seen_up_to` | optional | RFC 3339 datetime string |
| `visit` | optional | |
| `present` | optional | |
| `statistics` | optional | |
| `omnichannel` | optional | |

# Other common structures

Expand Down Expand Up @@ -524,3 +526,4 @@ The **Deleted Event** is returned to agents with the `normal` role in place of t
| `deleted` | always | |
| `author_id` | optionally | |
| `custom_id` | optionally | |

29 changes: 22 additions & 7 deletions src/pages/messaging/agent-chat-api/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1900,11 +1900,13 @@ Returns the info about the customer with a given `id`.
| `name` | string | Customer's name. Returned only if set. |
| `email` | string | Customer's email. Returned only if set. |
| `avatar` | string | Customer's avatar. Returned only if set. |
| `phone_number` | string | Customer's phone number. Returned only if set. |
| `created_at` | string | Specifies when the customer's identity was created. |
| `session_fields` | []object | An array of custom object-enclosed `key:value` pairs. Returned only if set. Available for the session duration. |
| `statistics` | object | Counters for started threads, opened pages, etc. |
| `visit` | object | Geolocation and opened pages from the customer's most recent online visit. Returned only if the customer logged in at least once. |
| `chat_ids` | []string | IDs of a customer's chats. Returned only if the customer had at least one chat. |
| `omnichannel` | object | An object of the customer's [omnichannel data](/messaging/agent-chat-api/data-structures/#customer). |

</Text>
<Code>
Expand Down Expand Up @@ -2008,13 +2010,26 @@ The webhook will be sent only if the customer has active chats.

#### Request

| Parameter | Required | Data type | Notes |
| ---------------- | -------- | ---------- | ---------------------------------------------------------------------------------- |
| `id` | Yes | `string` | UUID v4 format is required |
| `name` | No | `string` | |
| `email` | No | `string` | |
| `avatar` | No | `string` | URL of the customer's avatar |
| `session_fields` | No | `[]object` | An array of custom object-enclosed `key:value` pairs. Respects the order of items. |
| Parameter | Required | Data type | Notes |
| --------------------------------------------- | -------- | ---------- | ---------------------------------------------------------------------------------- |
| `id` | Yes | `string` | UUID v4 format is required |
| `name` | No | `string` | |
| `email` | No | `string` | |
| `avatar` | No | `string` | URL of the customer's avatar |
| `phone_number` | No | `string` | E.164 format. |
| `session_fields` | No | `[]object` | An array of custom object-enclosed `key:value` pairs. Respects the order of items. |
| `omnichannel` | No | `object` | |
| `omnichannel.fbmessenger` | No | `object` | |
| `omnichannel.fbmessenger.id` | Yes | `string` | Required only when `omnichannel.fbmessenger` is included. |
| `omnichannel.fbmessenger.name` | No | `string` | |
| `omnichannel.fbmessenger.first_name` | No | `string` | |
| `omnichannel.fbmessenger.last_name` | No | `string` | |
| `omnichannel.fbmessenger.profile_pic` | No | `string` | |
| `omnichannel.fbmessenger.gender` | No | `string` | |
| `omnichannel.fbmessenger.locale` | No | `string` | |
| `omnichannel.fbmessenger.is_verified_user` | No | `bool` | |
| `omnichannel.twilio` | No | `object` | |
| `omnichannel.twilio.phone_number` | Yes | `string` | Required only when `omnichannel.twilio` is included. |

Apart from `id`, which is a required parameter, you also need to include **one of the optional** parameters.

Expand Down
16 changes: 15 additions & 1 deletion src/pages/messaging/agent-chat-api/rtm-pushes/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -615,12 +615,26 @@ Indicates that customer's data changed. The push payload contains the updated fi
"name": "Thomas Anderson",
"email": "t.anderson@example.com",
"avatar": "https://example.com/avatars/1.jpg",
"phone_number": "+14155552671",
"type": "customer",
"session_fields": [{
"custom_key": "custom_value"
}, {
"another_custom_key": "another_custom_value"
}]
}],
"omnichannel": {
"fb_messenger": [
{
"id": "4f0ad8d8-1b7e-4519-8400-fa955eb11d12",
"name": "Anderson"
}
],
"twilio": [
{
"phone_number": "+14155552671"
}
]
}
}
```

Expand Down
31 changes: 23 additions & 8 deletions src/pages/messaging/agent-chat-api/rtm-reference/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ The basics on authorization, server pinging, and scopes in the Agent Chat RTM AP

### Authorization

**Agent authorization** is handled with access tokens. Find out how to get an **access token** from [agent authorization flows](/authorization/agent-authorization/). You need to authorize within 30 seconds from establishing the connection. Otherwise, the connection will be closed. Given that the connection is continuosly maintained, you only need to authorize once.
**Agent authorization** is handled with access tokens. Find out how to get an **access token** from [agent authorization flows](/authorization/agent-authorization/). You need to authorize within 30 seconds from establishing the connection. Otherwise, the connection will be closed. Given that the connection is continuously maintained, you only need to authorize once.

### Server pinging

Expand Down Expand Up @@ -2094,11 +2094,13 @@ Returns the info about the customer with a given `id`.
| `name` | string | Customer's name. Returned only if set. |
| `email` | string | Customer's email. Returned only if set. |
| `avatar` | string | Customer's avatar. Returned only if set. |
| `phone_number` | string | Customer's phone number. Returned only if set. |
| `created_at` | string | Specifies when the customer's identity was created. |
| `session_fields` | []object | An array of custom object-enclosed `key:value` pairs. Returned only if set. Available for the session duration. |
| `statistics` | object | Counters for started threads, opened pages, etc. |
| `visit` | object | Geolocation and opened pages from the customer's most recent online visit. Returned only if the customer logged in at least once. |
| `chat_ids` | []string | IDs of a customer's chats. Returned only if the customer had at least one chat. |
| `omnichannel` | object | An object of the customer's [omnichannel data](/messaging/agent-chat-api/data-structures/#customer). |

</Text>
<Code>
Expand Down Expand Up @@ -2204,13 +2206,26 @@ Updates customer's properties.

#### Request

| Parameter | Required | Data type | Notes |
| ---------------- | -------- | ---------- | ---------------------------------------------------------------------------------- |
| `id` | Yes | `string` | UUID v4 format is required. |
| `name` | No | `string` | |
| `email` | No | `string` | |
| `avatar` | No | `string` | URL of the customer's avatar |
| `session_fields` | No | `[]object` | An array of custom object-enclosed `key:value` pairs. Respects the order of items. |
| Parameter | Required | Data type | Notes |
| --------------------------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------- |
| `id` | Yes | `string` | UUID v4 format is required. |
| `name` | No | `string` | |
| `email` | No | `string` | |
| `avatar` | No | `string` | URL of the customer's avatar |
| `phone_number` | No | `string` | E.164 format. |
| `session_fields` | No | `[]object` | An array of custom object-enclosed `key:value` pairs. Respects the order of items. |
| `omnichannel` | No | `object` | |
| `omnichannel.fbmessenger` | No | `object` | |
| `omnichannel.fbmessenger.id` | Yes | `string` | Required only when `omnichannel.fbmessenger` is included. |
| `omnichannel.fbmessenger.name` | No | `string` | |
| `omnichannel.fbmessenger.first_name` | No | `string` | |
| `omnichannel.fbmessenger.last_name` | No | `string` | |
| `omnichannel.fbmessenger.profile_pic` | No | `string` | |
| `omnichannel.fbmessenger.gender` | No | `string` | |
| `omnichannel.fbmessenger.locale` | No | `string` | |
| `omnichannel.fbmessenger.is_verified_user` | No | `bool` | |
| `omnichannel.twilio` | No | `object` | |
| `omnichannel.twilio.phone_number` | Yes | `string` | Required only when `omnichannel.twilio` is included. |

Apart from `id`, which is a required parameter, you also need to include **one of the optional** parameters.

Expand Down
Loading