Get customer
Returns the info about the customer with a givenid.
Specifics
| Action | get_customer |
| Required scopes | customers:ro |
| Push message | — |
| Parameter | Required | Type | Notes |
|---|---|---|---|
id | Yes | string |
| Field | Type | Notes |
|---|---|---|
id | string | The customer’s ID. |
type | string | customer |
name | string | The customer’s name. Returned only if set. |
email | string | The customer’s email. Returned only if set. |
suggested_email | string | The email address suggested for the customer based on tracked activity, such as a form submission. The customer has not confirmed this address. Returned only if set. |
avatar | string | The customer’s avatar. Returned only if set. |
phone_number | string | The 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 | The 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. |
address | object | An object of the customer’s address data. Returned only if set. |
relationship_level | string | The customer’s relationship level. Possible values: vip. Returned only if set. |
segment_memberships | []object | The customer’s segment memberships. Returned only if set. |
Request
{
"action": "get_customer",
"payload": {
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}
}
Response
{
"request_id": "<request_id>",
"action": "get_customer",
"type": "response",
"success": true,
"payload": {
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"type": "customer",
"created_at": "2017-10-11T15:19:21.010200Z",
"name": "Thomas Anderson",
"email": "t.anderson@example.com",
"suggested_email": "t.anderson@example.com",
"avatar": "example.com/avatars/1.jpg",
"session_fields": [
{
"custom_key": "custom_value"
},
{
"another_custom_key": "another_custom_value"
}
],
"visit": {
"started_at": "2017-10-12T15:19:21.010200Z",
"ended_at": "2017-10-12T15:20:22.010200Z",
"referrer": "http://www.google.com/",
"ip": "<customer_ip>",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
"geolocation": {
"latitude": "-14.6973803",
"longitude": "-75.1266898",
"country": "Poland",
"country_code": "PL",
"region": "Dolnoslaskie",
"city": "Wroclaw",
"timezone": "Europe/Warsaw"
},
"last_pages": [
{
"opened_at": "2017-10-12T15:19:21.010200Z",
"url": "https://www.text.com/",
"title": "Text - Homepage"
},
{
"opened_at": "2017-10-12T15:19:21.010200Z",
"url": "https://www.text.com/features/ai-agent/",
"title": "Text - AI Agents"
}
]
},
"statistics": {
"chats_count": 3,
"threads_count": 9,
"visits_count": 5,
"page_views_count": 1337,
"greetings_shown_count": 69,
"greetings_accepted_count": 42,
"tickets_count": 12
},
"agent_last_event_created_at": "2017-10-12T15:19:21.010200Z",
"customer_last_event_created_at": "2017-10-12T15:19:21.010200Z",
"chat_ids": ["PWJ8Y4THAV"],
"relationship_level": "vip",
"segment_memberships": [
{
"segment_id": 0,
"is_member": true,
"membership_last_updated_at": "2026-07-15T09:31:45.075731Z",
"membership_attribution": ["464d206a-ba7d-4ce1-98d6-d03f8f14970e"],
"conditions_provenance": {
"email_set": {
"last_updated_at": "2026-07-15T09:31:45.075731Z",
"agent_account_id": "464d206a-ba7d-4ce1-98d6-d03f8f14970e",
"agent_client_id": "71d32c598862b01b9e2298281339dbc2"
}
}
}
],
"tickets": [
{
"ticket_id": "0c04cb99-817a-4935-9d62-137c89a74388",
"created_at": "2017-10-12T15:19:21.010200Z"
}
]
}
}
Update customer
Updates customer’s properties. Apart fromid, at least one optional parameter must be included.
Specifics
| Action | update_customer |
| Required scopes | customers:rw |
| Push message | customer_updated |
| Parameter | Required | Type | Notes |
|---|---|---|---|
id | Yes | string | UUID v4 format is required. |
name | No | string | |
email | No | string | |
suggested_email | No | string | The email address suggested for the customer based on tracked activity, such as a form submission. The customer has not confirmed this address. This field is independent of email. An empty value clears only the suggestion. |
avatar | No | string | The 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 | No | string | Required when omnichannel.fbmessenger is provided. |
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 | No | string | Required when omnichannel.twilio is provided. |
address | No | object | The customer’s address. |
address.address | No | string | The street address. |
address.city | No | string | The city name. |
address.country | No | string | The country name. |
address.state | No | string | The state name. |
address.postal_code | No | string | The postal code. |
Request
{
"action": "update_customer",
"payload": {
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"name": "Thomas Anderson",
"email": "t.anderson@example.com",
"suggested_email": "t.anderson@example.com",
"avatar": "https://example.com/avatars/1.png",
"session_fields": [
{
"custom_key": "custom_value"
},
{
"another_custom_key": "another_custom_value"
}
]
}
}
Response
{
"request_id": "<request_id>",
"action": "update_customer",
"type": "response",
"success": true,
"payload": {}
}
Ban customer
Bans the customer for a specific period of time. It immediately disconnects all active sessions of this customer and does not accept new ones during the ban lifespan. Specifics| Action | ban_customer |
| Required scopes | customers.ban:rw |
| Push message | customer_banned |
| Parameter | Required | Type | Notes |
|---|---|---|---|
id | Yes | string | |
ban | Yes | object | |
ban.days | Yes | number |
Request
{
"action": "ban_customer",
"payload": {
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"ban": {
"days": 3
}
}
}
Response
{
"request_id": "<request_id>",
"action": "ban_customer",
"type": "response",
"success": true,
"payload": {}
}
Subscribe customers
Creates a subscription for tracking customers based on the group they belong to. The response will contain customers currently matching the criteria. After a successful subscription, the agent will receive pushes about tracked customers on this RTM connection. If the number of tracked customers exceeds the limit, thesubscribed_customers_totals_updated push will be periodically sent to indicate the total number of customers matching the criteria at the given moment.
Specifics
| Action | subscribe_customers |
| Required scopes | customers:ro |
| Push message | — |
| Parameter | Required | Type | Notes |
|---|---|---|---|
group_ids | No | []int | |
limit | No | int |
| Field | Type | Notes |
|---|---|---|
subscription_id | string | |
customers | array | An array of customer objects currently matching the criteria. |
Request
{
"action": "subscribe_customers",
"payload": {
"group_ids": [0, 42],
"limit": 100
}
}
Response
{
"request_id": "<request_id>",
"action": "subscribe_customers",
"type": "response",
"success": true,
"payload": {
"subscription_id": "b7eff798f8df43648059649c35c9ed0c",
"customers": []
}
}
Unsubscribe customers
Removes a customer subscription. Specifics| Action | unsubscribe_customers |
| Required scopes | customers:ro |
| Push message | — |
| Parameter | Required | Type | Notes |
|---|---|---|---|
subscription_id | Yes | string |
Request
{
"action": "unsubscribe_customers",
"payload": {
"subscription_id": "b7eff798f8df43648059649c35c9ed0c"
}
}
Response
{
"request_id": "<request_id>",
"action": "unsubscribe_customers",
"type": "response",
"success": true,
"payload": {}
}