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

# Status

> Reference of Status methods for the Agent Chat RTM API v3.7.

## Login

Returns the initial state of the current agent.

**Specifics**

|                     |                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**          | `login`                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **Required scopes** | <Tooltip tip="To get pushes about chats from the requester's groups.">`chats--access:ro`</Tooltip> and <Tooltip tip="To get pushes about customers.">`customers:ro`</Tooltip> and <Tooltip tip="To get pushes about multicast.">`multicast:ro`</Tooltip> and <Tooltip tip="To get pushes about agent updates.">`agents--all:ro`</Tooltip> and <Tooltip tip="To get pushes about bot updates.">`agents-bot--all:ro`</Tooltip> |
| **Push message**    | —                                                                                                                                                                                                                                                                                                                                                                                                                            |

**Request**

| Parameter                   | Required | Type       | Notes                                                                                                                                                                                         |
| --------------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`                     | Yes      | `string`   | The OAuth token from the agent's account.                                                                                                                                                     |
| `timezone`                  | No       | `string`   |                                                                                                                                                                                               |
| `reconnect`                 | No       | `bool`     | If set to `true`: reconnecting sets the status to the last known state instead of the default one.                                                                                            |
| `application`               | No       | `object`   |                                                                                                                                                                                               |
| `application.name`          | No       | `string`   | The application name.                                                                                                                                                                         |
| `application.version`       | No       | `string`   | The application version.                                                                                                                                                                      |
| `away`                      | No       | `bool`     | If set to `true`: the connection is set to the `away` state. Default: `false`.                                                                                                                |
| `customer_monitoring_level` | No       | `string`   | Possible values: `my`, `chatting`, `invited`, `online`, `highest_available`. Default: `my` if `login` creates the first session; otherwise preserves the current `customer_monitoring_level`. |
| `pushes`                    | No       | `object`   | Use case: when you want to receive only specific pushes. Default: `all` for the version of your currently established RTM connection.                                                         |
| `pushes.<version>`          | Yes      | `[]string` | A list of push subscriptions for a specific version. `<version>` is a version number without the `v` prefix. Possible values: push names. Required when `pushes` is provided.                 |

`customer_monitoring_level` values:

* `my` — only the customers from chats the agent is assigned to
* `chatting` — all customers that are chatting within the groups the agent is assigned to
* `invited` — all customers that are invited to chat within the groups the agent is assigned to
* `online` — all customers visiting the website assigned to the agent's groups
* `highest_available` — sets customer monitoring level to the highest available level based on license configuration

**Response**

| Field        | Type     | Notes |
| ------------ | -------- | ----- |
| `access`     | `object` |       |
| `properties` | `object` |       |

```json title="Request" theme={null}
{
  "action": "login",
  "payload": {
    "token": "Bearer us-south1:test_1fgTbfXmgthj4cZSA",
    "pushes": {
      "3.6": ["incoming_chat", "incoming_multicast"],
      "3.7": ["all"]
    }
  }
}
```

```json title="Response" theme={null}
{
  "request_id": "<request_id>",
  "action": "login",
  "type": "response",
  "success": true,
  "payload": {
    "license": {
      "id": "104130623",
      "organization_id": "390e44e6-f1e6-0368c-z6ddb-74g14508c2ex",
      "plan": "enterprise",
      "expiration_timestamp": 1483433500,
      "creation_timestamp": 1482433500,
      "in_trial": true
    },
    "my_profile": {},
    "chats_info": [
      {
        "id": "PJ0MRSHTDG",
        "users": [],
        "last_thread_info": {
          "id": "K600PKZON8",
          "user_ids": ["smith@example.com"],
          "properties": {
            "routing": {
              "idle": false,
              "unassigned": false
            }
          },
          "created_at": "2020-05-07T07:11:28.288340Z",
          "last_event_per_type": {
            "message": {
              "event": {}
            },
            "system_message": {
              "event": {}
            }
          }
        },
        "properties": {
          "routing": {
            "idle": false,
            "unassigned": false
          }
        },
        "access": {}
      }
    ]
  }
}
```

***

## Set away status

Sets an agent's connection to the `away` state. The method works per connection — all connections an agent has (desktop, mobile, etc.) must be in the `away` state for the agent's status to be changed to `not_accepting_chats`.

You may want to make use of the auto-away feature and set the agents' statuses to `not_accepting_chats` when they're inactive. Checking if agents are active or inactive should be implemented on your side. If you decide they're inactive, set their connections to `away`. The auto-away feature will recognize the `away` connections and change the agent's status to `not_accepting_chats`.

**Specifics**

|                     |                   |
| ------------------- | ----------------- |
| **Action**          | `set_away_status` |
| **Required scopes** | `agents--my:rw`   |
| **Push message**    | —                 |

**Request**

| Parameter | Required | Type   | Notes                                                        |
| --------- | -------- | ------ | ------------------------------------------------------------ |
| `away`    | Yes      | `bool` | If set to `true`: the connection is set to the `away` state. |

No response payload.

```json title="Request" theme={null}
{
  "action": "set_away_status",
  "payload": {
    "away": true
  }
}
```

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

***

## Set routing status

Changes the status of an agent or a bot agent. It sets the status for the session duration. Once the session ends, the status gets back to what's in the agent's settings. Unlike [set\_away\_status](#set_away_status), which is another mechanism of status manipulation, `set_routing_status` is independent of the number of connections (desktop, mobile, etc.).

**Specifics**

|                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**          | `set_routing_status`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Required scopes** | For agents: <Tooltip tip="To set the requester's routing status.">`agents--my:rw`</Tooltip> or <Tooltip tip="To set the routing status of any agent within a license.">`agents--all:rw`</Tooltip>. For bot agents: <Tooltip tip="To set the routing status of bots that belong to the `client_id` related to the token.">`agents-bot--my:rw`</Tooltip> or <Tooltip tip="To set the routing status of any bots within a license. For bots of type `ai_agent`, you can only change the routing status with tokens issued for the `client_id` that owns them.">`agents-bot--all:rw`</Tooltip>. |
| **Push message**    | `routing_status_set`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

**Request**

| Parameter  | Required | Type     | Notes                                                                                                                                            |
| ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`   | Yes      | `string` | Possible values: for agents: `accepting_chats` or `not_accepting_chats`; for bot agents: `accepting_chats`, `not_accepting_chats`, or `offline`. |
| `agent_id` | No       | `string` | The agent ID. If not specified, the requester's status will be updated.                                                                          |

No response payload.

```json title="Request" theme={null}
{
  "action": "set_routing_status",
  "payload": {
    "status": "accepting_chats",
    "agent_id": "smith@example.com"
  }
}
```

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

***

## Logout

Logs the agent out.

**Specifics**

|                     |          |
| ------------------- | -------- |
| **Action**          | `logout` |
| **Required scopes** | —        |
| **Push message**    | —        |

No request parameters.

No response payload.

```json title="Request" theme={null}
{
  "action": "logout",
  "payload": {}
}
```

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

***

## List routing statuses

Returns the current routing status of each agent selected by the provided filters.

**Specifics**

|                     |                                                                                                                                                   |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**          | `list_routing_statuses`                                                                                                                           |
| **Required scopes** | <Tooltip tip="To list statuses of agents.">`agents--all:ro`</Tooltip> and <Tooltip tip="To list statuses of bots.">`agents-bot--all:ro`</Tooltip> |
| **Push message**    | —                                                                                                                                                 |

**Request**

| Parameter           | Required | Type     | Notes |
| ------------------- | -------- | -------- | ----- |
| `filters`           | No       | `object` |       |
| `filters.group_ids` | No       | `array`  |       |

**Response**

An array of objects, each containing:

| Field      | Type     | Notes |
| ---------- | -------- | ----- |
| `agent_id` | `string` |       |
| `status`   | `string` |       |

```json title="Request" theme={null}
{
  "action": "list_routing_statuses",
  "payload": {
    "filters": {
      "group_ids": [0]
    }
  }
}
```

```json title="Response" theme={null}
{
  "request_id": "<request_id>",
  "action": "list_routing_statuses",
  "type": "response",
  "success": true,
  "payload": [
    {
      "agent_id": "smith@example.com",
      "status": "accepting_chats"
    },
    {
      "agent_id": "agent@example.com",
      "status": "not_accepting_chats"
    }
  ]
}
```

***

## Update session

Replaces the token used in the login request with a new one. This allows the WebSocket connection to remain open after the former token expires, as its lifetime is now tied to the new token.

**Specifics**

|                     |                  |
| ------------------- | ---------------- |
| **Action**          | `update_session` |
| **Required scopes** | —                |
| **Push message**    | —                |

**Request**

| Parameter | Required | Type     | Notes                                     |
| --------- | -------- | -------- | ----------------------------------------- |
| `token`   | Yes      | `string` | The OAuth token from the agent's account. |

No response payload.

```json title="Request" theme={null}
{
  "action": "update_session",
  "payload": {
    "token": "Bearer us-south1:test_1fgTbfXmgthj4cZSA"
  }
}
```

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