> ## 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.6.

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

```json title="Request" theme={null}
{
  "action": "get_customer",
  "payload": {
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}
```

```json title="Response" theme={null}
{
  "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.

```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": "<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": "<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, 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](/api/agent-chat/v3.6/rtm/data-structures#customer) currently matching the criteria. |

```json title="Request" theme={null}
{
  "action": "subscribe_customers",
  "payload": {
    "group_ids": [0, 42],
    "limit": 100
  }
}
```

```json title="Response" theme={null}
{
  "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.

```json title="Request" theme={null}
{
  "action": "unsubscribe_customers",
  "payload": {
    "subscription_id": "b7eff798f8df43648059649c35c9ed0c"
  }
}
```

```json title="Response" theme={null}
{
  "request_id": "<request_id>",
  "action": "unsubscribe_customers",
  "type": "response",
  "success": true,
  "payload": {}
}
```