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

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"
      }
    ],
    "last_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
    },
    "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"]
  }
}

List customers

Returns a list of customers. Specifics


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

Request All parameters are optional.

Parameter	Required	Type	Notes
`page_id`	No	`string`
`limit`	No	`number`	Maximum number of records returned per page. Default: `10`, maximum: `100`.
`sort_order`	No	`string`	Possible values: `asc`, `desc`. Default: `desc`.
`sort_by`	No	`string`	Possible values: `created_at`, `threads_count`, `visits_count`, `agent_last_event`, `customer_last_event`. Default: `created_at`. When sorting by fields other than `created_at`, entries with identical values are additionally sorted by creation time.
`filters`	No	`object`
`filters.country.<string_filter_type>`¹	No	`object`	See ¹ below.
`filters.email.<string_filter_type>`¹	No	`object`	See ¹ below.
`filters.name.<string_filter_type>`¹	No	`object`	See ¹ below.
`filters.customer_id.<string_filter_type>`¹	No	`object`	See ¹ below.
`filters.chats_count.<range_filter_type>`³	No	`object`	See ³ below.
`filters.threads_count.<range_filter_type>`³	No	`object`	See ³ below.
`filters.visits_count.<range_filter_type>`³	No	`object`	See ³ below.
`filters.created_at.<date_range_filter_type>`⁴	No	`object`	See ⁴ below.
`filters.agent_last_event_created_at.<date_range_filter_type>`⁴	No	`object`	See ⁴ below.
`filters.customer_last_event_created_at.<date_range_filter_type>`⁴	No	`object`	See ⁴ below.
`filters.chat_group_ids.<integer_filter_type>`²	No	`object`	See ² below. Maximum 40 group IDs at once.
`filters.include_customers_without_chats`	No	`bool`

<string_filter_type> values

| Value | Type | Notes | | --- | --- | --- | | values | string[] | An array of strings. | | exclude_values | string[] | An array of strings. |

<integer_filter_type> values

| Value | Type | Notes | | --- | --- | --- | | values | int[] | An array of integers. | | exclude_values | int[] | An array of integers. |

<range_filter_type> values

| Value | Type | Notes | | --- | --- | --- | | lte | int | Less than or equal to the given value. | | lt | int | Less than the given value. | | gte | int | Greater than or equal to the given value. | | gt | int | Greater than the given value. | | eq | int | Equal to the given value. |

<date_range_filter_type> values

Value	Type	Notes
`lte`	`string`
`lt`	`string`
`gte`	`string`
`gt`	`string`
`eq`	`string`

Dates are in ISO 8601 format with microsecond resolution, e.g. 2017-10-12T15:19:21.010200+01:00.

Response

Field	Type	Notes
`next_page_id`	`string`	Present when there is a next page.
`previous_page_id`	`string`	Present when there is a previous page.

Request

{
  "action": "list_customers",
  "payload": {}
}

Response

{
  "request_id": "<request_id>",
  "action": "list_customers",
  "type": "response",
  "success": true,
  "payload": {
    "customers": [],
    "total_customers": 2340,
    "next_page_id": "MTUxNzM5ODEzMTQ5Ng==",
    "previous_page_id": "MTUxNzM5ODEzMTQ5Ng=="
  }
}

Create customer

Creates a new Customer user type. Specifics


Action	`create_customer`
Required scopes	`customers:rw`
Push message	`incoming_customer`

Request

Parameter	Required	Type	Notes
`name`	No	`string`
`email`	No	`string`
`avatar`	No	`string`	The URL of the customer’s avatar.
`session_fields`	No	`[]object`	An array of custom object-enclosed key-value pairs. Respects the order of items.

Response

Field	Type	Notes
`customer_id`	`string`

Request

{
  "action": "create_customer",
  "payload": {
    "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": "create_customer",
  "type": "response",
  "success": true,
  "payload": {
    "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}

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.
`session_fields`	No	`[]object`	An array of custom object-enclosed key-value pairs. Respects the order of items.

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

Overview

Methods

Get customer

List customers

Create customer

Update customer

Ban customer

​Get customer

​List customers

​Create customer

​Update customer

​Ban customer

Get customer

List customers

Create customer

Update customer

Ban customer