# Pause or resume the bot in a conversation

`POST https://api.chat-data.com/api/v2/bot-control`

Canonical: https://www.chat-data.com/api-reference/toggle-bot-control

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

Toggle or set the bot control state for a conversation. When bot control is -1, the bot does not respond to user messages. When bot control is 1, the bot responds to user messages. This endpoint only works for conversations originating from WhatsApp, Instagram, Messenger, WhatsApp Web API, Telegram or LINE.

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| chatbotId | string | yes | The unique identifier of the chatbot. |
| conversationId | string | yes | The unique identifier of the conversation. |
| botControl | integer | no | If provided, sets the bot control state to this value (1 for on, -1 for off). If omitted, the current state is toggled. |
| botOffMins | integer | no | How many minutes the bot should remain off; 0 keeps it off until the next bot control call. Only applies when `botControl` is set to -1; in every other case the stored value is reset to 0. |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/bot-control' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",
  "conversationId": "3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c"
}'
```

## Example response (200)

```json
{
  "status": "success",
  "payload": {
    "botControl": -1,
    "botOffMins": 30,
    "botOffTime": "2026-10-14T09:30:00.000Z"
  }
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | The state could not be changed. For example: `botControl` is not 1 or -1, `botOffMins` is not a non-negative integer, `chatbotId` or `conversationId` is missing, the conversation does not exist, or it did not come from WhatsApp, Instagram, Messenger, WhatsApp Web, Telegram or LINE. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |