Customers

Get customer

Returns the info about the customer with a given id. Specifics


Action	`get_customer`
Required scopes	`customers:ro`
Push message	—

Request

Parameter	Required	Type	Notes
`id`	Yes	`string`

Response

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.
`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.

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",
    "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"],
    "tickets": [
      {
        "ticket_id": "0c04cb99-817a-4935-9d62-137c89a74388",
        "created_at": "2017-10-12T15:19:21.010200Z"
      }
    ]
  }
}

Update customer

Updates customer’s properties. Apart from id, at least one optional parameter must be included. Specifics


Action	`update_customer`
Required scopes	`customers:rw`
Push message	`customer_updated`

Request

Parameter	Required	Type	Notes
`id`	Yes	`string`	UUID v4 format is required.
`name`	No	`string`
`email`	No	`string`
`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.

No response payload.

Request

{
  "action": "update_customer",
  "payload": {
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "name": "Thomas Anderson",
    "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`

Request

Parameter	Required	Type
`id`	Yes	`string`
`ban`	Yes	`object`
`ban.days`	Yes	`number`

No response payload.

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": {}
}

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, the subscribed_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	—

Request

Parameter	Required	Type	Notes
`group_ids`	No	`[]int`
`limit`	No	`int`

Response

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	—

Request

Parameter	Required	Type	Notes
`subscription_id`	Yes	`string`

No response payload.

Request

{
  "action": "unsubscribe_customers",
  "payload": {
    "subscription_id": "b7eff798f8df43648059649c35c9ed0c"
  }
}

Response

{
  "request_id": "<request_id>",
  "action": "unsubscribe_customers",
  "type": "response",
  "success": true,
  "payload": {}
}

Overview

Methods

Get customer

Update customer

Ban customer

Unsubscribe customers

​Get customer

​Update customer

​Ban customer

​Subscribe customers

​Unsubscribe customers

Get customer

Update customer

Ban customer

Subscribe customers

Unsubscribe customers