Skip to content

Commit c92cab5

Browse files
GGuineaGGuinea
authored
feat(docs): extend customer object with omnichannel and phone number (#1620)
1 parent 2feecad commit c92cab5

File tree

19 files changed

+307
-70
lines changed

19 files changed

+307
-70
lines changed

‎payloads/messaging/v3.6/agent-chat-api/users/customer.json‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"email": "t.anderson@example.com",
66
"email_verified": false,
77
"avatar": "https://example.com/avatars/1.png",
8+
"phone_number": "+18008529001",
89
"visit": {
910
"started_at": "2017-10-12T15:19:21.010200Z",
1011
"ended_at": "2017-10-12T15:21:01.000000Z",
@@ -60,5 +61,26 @@
6061
"ticket_id": "0c04cb99-817a-4935-9d62-137c89a74388",
6162
"created_at": "2017-10-12T15:19:21.010200Z"
6263
}],
63-
"state": "browsing"
64+
"state": "browsing",
65+
"omnichannel": {
66+
"fb_messenger": [
67+
{
68+
"ID": "fb_messenger_id",
69+
"Name": "Thomas Anderson",
70+
"FirstName": "Thomas",
71+
"LastName": "Anderson",
72+
"ProfilePicURL": "https://example.com/avatars/1.png",
73+
"Gender": "male",
74+
"Locale": "EN_US",
75+
"IsVerifiedUser": true
76+
}
77+
],
78+
"twilio": [
79+
{
80+
"+18008529001": {
81+
"phone_number": "+18008529001"
82+
}
83+
}
84+
]
85+
}
6486
}

‎payloads/messaging/v3.6/customer-chat-api/users/customer.json‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"email": "t.anderson@example.com",
66
"email_verified": false,
77
"avatar": "https://example.com/avatar.png",
8+
"phone_number": "+18008529001",
89
"session_fields": [
910
{
1011
"custom_key": "custom_value"
@@ -14,5 +15,26 @@
1415
}
1516
],
1617
"present": true,
17-
"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
18+
"events_seen_up_to": "2017-10-12T15:19:21.010200Z",
19+
"omnichannel": {
20+
"fb_messenger": [
21+
{
22+
"ID": "fb_messenger_id",
23+
"Name": "Thomas Anderson",
24+
"FirstName": "Thomas",
25+
"LastName": "Anderson",
26+
"ProfilePicURL": "https://example.com/avatars/1.png",
27+
"Gender": "male",
28+
"Locale": "EN_US",
29+
"IsVerifiedUser": true
30+
}
31+
],
32+
"twilio": [
33+
{
34+
"+18008529001": {
35+
"phone_number": "+18008529001"
36+
}
37+
}
38+
]
39+
}
1840
}

‎payloads/messaging/v3.7/agent-chat-api/users/customer.json‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"email": "t.anderson@example.com",
66
"email_verified": false,
77
"avatar": "https://example.com/avatars/1.png",
8+
"phone_number": "+18008529001",
89
"visit": {
910
"started_at": "2017-10-12T15:19:21.010200Z",
1011
"ended_at": "2017-10-12T15:21:01.000000Z",
@@ -60,5 +61,26 @@
6061
"ticket_id": "0c04cb99-817a-4935-9d62-137c89a74388",
6162
"created_at": "2017-10-12T15:19:21.010200Z"
6263
}],
63-
"state": "browsing"
64+
"state": "browsing",
65+
"omnichannel": {
66+
"fb_messenger": [
67+
{
68+
"ID": "fb_messenger_id",
69+
"Name": "Thomas Anderson",
70+
"FirstName": "Thomas",
71+
"LastName": "Anderson",
72+
"ProfilePicURL": "https://example.com/avatars/1.png",
73+
"Gender": "male",
74+
"Locale": "EN_US",
75+
"IsVerifiedUser": true
76+
}
77+
],
78+
"twilio": [
79+
{
80+
"+18008529001": {
81+
"phone_number": "+18008529001"
82+
}
83+
}
84+
]
85+
}
6486
}

‎payloads/messaging/v3.7/customer-chat-api/users/customer.json‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"email": "t.anderson@example.com",
66
"email_verified": false,
77
"avatar": "https://example.com/avatar.png",
8+
"phone_number": "+18008529001",
89
"session_fields": [
910
{
1011
"custom_key": "custom_value"
@@ -14,5 +15,26 @@
1415
}
1516
],
1617
"present": true,
17-
"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
18+
"events_seen_up_to": "2017-10-12T15:19:21.010200Z",
19+
"omnichannel": {
20+
"fb_messenger": [
21+
{
22+
"ID": "fb_messenger_id",
23+
"Name": "Thomas Anderson",
24+
"FirstName": "Thomas",
25+
"LastName": "Anderson",
26+
"ProfilePicURL": "https://example.com/avatars/1.png",
27+
"Gender": "male",
28+
"Locale": "EN_US",
29+
"IsVerifiedUser": true
30+
}
31+
],
32+
"twilio": [
33+
{
34+
"+18008529001": {
35+
"phone_number": "+18008529001"
36+
}
37+
}
38+
]
39+
}
1840
}

‎src/pages/messaging/agent-chat-api/changelog/index.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,8 @@ The developer preview version provides a preview of the upcoming changes to the
6363
- [**ticket_created**](/messaging/agent-chat-api/rtm-pushes/#ticket_created)
6464
- [**ticket_deleted**](/messaging/agent-chat-api/rtm-pushes/#ticket_deleted)
6565
- [**customer_statistics_updated**](/messaging/agent-chat-api/rtm-pushes/#customer_statistics_updated)
66+
- The [**Customer**](/messaging/agent-chat-api/data-structures#customer) data structure now contains information about phone number and omnichannel data (when available).
67+
- 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`.
6668

6769
### Status
6870

‎src/pages/messaging/agent-chat-api/data-structures/index.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -412,10 +412,12 @@ It is not possible to send a System event in API version 3.6.
412412
| `email_verified` | optional | Specifies if the customer confirmed their email address. See [Request Email Verification](/messaging/customer-chat-api/v3.6/#request-email-verification). |
413413
| `session_fields` | optional | An array of custom object-enclosed `key:value` pairs. Expires along with the session. |
414414
| `name` | optional | |
415+
| `phone_number` | optional | |
415416
| `events_seen_up_to` | optional | RFC 3339 datetime string |
416417
| `visit` | optional | |
417418
| `present` | optional | |
418419
| `statistics` | optional | |
420+
| `omnichannel` | optional | |
419421

420422
# Other common structures
421423

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

‎src/pages/messaging/agent-chat-api/index.mdx‎

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

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

20092011
#### Request
20102012

2011-
| Parameter | Required | Data type | Notes |
2012-
| ---------------- | -------- | ---------- | ---------------------------------------------------------------------------------- |
2013-
| `id` | Yes | `string` | UUID v4 format is required |
2014-
| `name` | No | `string` | |
2015-
| `email` | No | `string` | |
2016-
| `avatar` | No | `string` | URL of the customer's avatar |
2017-
| `session_fields` | No | `[]object` | An array of custom object-enclosed `key:value` pairs. Respects the order of items. |
2013+
| Parameter | Required | Data type | Notes |
2014+
| --------------------------------------------- | -------- | ---------- | ---------------------------------------------------------------------------------- |
2015+
| `id` | Yes | `string` | UUID v4 format is required |
2016+
| `name` | No | `string` | |
2017+
| `email` | No | `string` | |
2018+
| `avatar` | No | `string` | URL of the customer's avatar |
2019+
| `phone_number` | No | `string` | E.164 format. |
2020+
| `session_fields` | No | `[]object` | An array of custom object-enclosed `key:value` pairs. Respects the order of items. |
2021+
| `omnichannel` | No | `object` | |
2022+
| `omnichannel.fbmessenger` | No | `object` | |
2023+
| `omnichannel.fbmessenger.id` | Yes | `string` | Required only when `omnichannel.fbmessenger` is included. |
2024+
| `omnichannel.fbmessenger.name` | No | `string` | |
2025+
| `omnichannel.fbmessenger.first_name` | No | `string` | |
2026+
| `omnichannel.fbmessenger.last_name` | No | `string` | |
2027+
| `omnichannel.fbmessenger.profile_pic` | No | `string` | |
2028+
| `omnichannel.fbmessenger.gender` | No | `string` | |
2029+
| `omnichannel.fbmessenger.locale` | No | `string` | |
2030+
| `omnichannel.fbmessenger.is_verified_user` | No | `bool` | |
2031+
| `omnichannel.twilio` | No | `object` | |
2032+
| `omnichannel.twilio.phone_number` | Yes | `string` | Required only when `omnichannel.twilio` is included. |
20182033

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

‎src/pages/messaging/agent-chat-api/rtm-pushes/index.mdx‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -615,12 +615,26 @@ Indicates that customer's data changed. The push payload contains the updated fi
615615
"name": "Thomas Anderson",
616616
"email": "t.anderson@example.com",
617617
"avatar": "https://example.com/avatars/1.jpg",
618+
"phone_number": "+14155552671",
618619
"type": "customer",
619620
"session_fields": [{
620621
"custom_key": "custom_value"
621622
}, {
622623
"another_custom_key": "another_custom_value"
623-
}]
624+
}],
625+
"omnichannel": {
626+
"fb_messenger": [
627+
{
628+
"id": "4f0ad8d8-1b7e-4519-8400-fa955eb11d12",
629+
"name": "Anderson"
630+
}
631+
],
632+
"twilio": [
633+
{
634+
"phone_number": "+14155552671"
635+
}
636+
]
637+
}
624638
}
625639
```
626640

‎src/pages/messaging/agent-chat-api/rtm-reference/index.mdx‎

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ The basics on authorization, server pinging, and scopes in the Agent Chat RTM AP
3838

3939
### Authorization
4040

41-
**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.
41+
**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.
4242

4343
### Server pinging
4444

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

21032105
</Text>
21042106
<Code>
@@ -2204,13 +2206,26 @@ Updates customer's properties.
22042206

22052207
#### Request
22062208

2207-
| Parameter | Required | Data type | Notes |
2208-
| ---------------- | -------- | ---------- | ---------------------------------------------------------------------------------- |
2209-
| `id` | Yes | `string` | UUID v4 format is required. |
2210-
| `name` | No | `string` | |
2211-
| `email` | No | `string` | |
2212-
| `avatar` | No | `string` | URL of the customer's avatar |
2213-
| `session_fields` | No | `[]object` | An array of custom object-enclosed `key:value` pairs. Respects the order of items. |
2209+
| Parameter | Required | Data type | Notes |
2210+
| --------------------------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------- |
2211+
| `id` | Yes | `string` | UUID v4 format is required. |
2212+
| `name` | No | `string` | |
2213+
| `email` | No | `string` | |
2214+
| `avatar` | No | `string` | URL of the customer's avatar |
2215+
| `phone_number` | No | `string` | E.164 format. |
2216+
| `session_fields` | No | `[]object` | An array of custom object-enclosed `key:value` pairs. Respects the order of items. |
2217+
| `omnichannel` | No | `object` | |
2218+
| `omnichannel.fbmessenger` | No | `object` | |
2219+
| `omnichannel.fbmessenger.id` | Yes | `string` | Required only when `omnichannel.fbmessenger` is included. |
2220+
| `omnichannel.fbmessenger.name` | No | `string` | |
2221+
| `omnichannel.fbmessenger.first_name` | No | `string` | |
2222+
| `omnichannel.fbmessenger.last_name` | No | `string` | |
2223+
| `omnichannel.fbmessenger.profile_pic` | No | `string` | |
2224+
| `omnichannel.fbmessenger.gender` | No | `string` | |
2225+
| `omnichannel.fbmessenger.locale` | No | `string` | |
2226+
| `omnichannel.fbmessenger.is_verified_user` | No | `bool` | |
2227+
| `omnichannel.twilio` | No | `object` | |
2228+
| `omnichannel.twilio.phone_number` | Yes | `string` | Required only when `omnichannel.twilio` is included. |
22142229

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

0 commit comments

Comments
 (0)