> ## Documentation Index > Fetch the complete documentation index at: https://www.text.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Customers > Reference of Customers methods for the Agent Chat RTM API v3.5. ## 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. | ```json title="Request" theme={null} { "action": "get_customer", "payload": { "id": "b7eff798-f8df-4364-8059-649c35c9ed0c" } } ``` ```json title="Response" theme={null} { "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": "", "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.`1 | No | `object` | See 1 below. | | `filters.email.`1 | No | `object` | See 1 below. | | `filters.name.`1 | No | `object` | See 1 below. | | `filters.customer_id.`1 | No | `object` | See 1 below. | | `filters.chats_count.`3 | No | `object` | See 3 below. | | `filters.threads_count.`3 | No | `object` | See 3 below. | | `filters.visits_count.`3 | No | `object` | See 3 below. | | `filters.created_at.`4 | No | `object` | See 4 below. | | `filters.agent_last_event_created_at.`4 | No | `object` | See 4 below. | | `filters.customer_last_event_created_at.`4 | No | `object` | See 4 below. | | `filters.chat_group_ids.`2 | No | `object` | See 2 below. Maximum 40 group IDs at once. | | `filters.include_customers_without_chats` | No | `bool` | | \| Value | Type | Notes | | --- | --- | --- | | `values` | `string[]` | An array of strings. | | `exclude_values` | `string[]` | An array of strings. | \| Value | Type | Notes | | --- | --- | --- | | `values` | `int[]` | An array of integers. | | `exclude_values` | `int[]` | An array of integers. | \| 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. | | 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. | ```json title="Request" theme={null} { "action": "list_customers", "payload": {} } ``` ```json title="Response" theme={null} { "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` | | ```json title="Request" theme={null} { "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" } ] } } ``` ```json title="Response" theme={null} { "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. ```json title="Request" theme={null} { "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" } ] } } ``` ```json title="Response" theme={null} { "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 | Notes | | ---------- | -------- | -------- | ----- | | `id` | Yes | `string` | | | `ban` | Yes | `object` | | | `ban.days` | Yes | `number` | | No response payload. ```json title="Request" theme={null} { "action": "ban_customer", "payload": { "id": "b7eff798-f8df-4364-8059-649c35c9ed0c", "ban": { "days": 3 } } } ``` ```json title="Response" theme={null} { "request_id": "", "action": "ban_customer", "type": "response", "success": true, "payload": {} } ```