---
title: "Pause or resume the bot in a conversation"
method: POST
path: "/bot-control"
tags: ["Chatbot Operations"]
---

# Pause or resume the bot in a conversation

`POST /bot-control`

## Request

- Base URL: `https://api.chat-data.com/api/v2`
- URL: `https://api.chat-data.com/api/v2/bot-control`
- Auth: HTTP bearer

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

- object
  - `chatbotId` string, required: The unique identifier of the chatbot.
  - `conversationId` string, required: The unique identifier of the conversation.
  - `botControl` 1 | -1: 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: 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.

## Response `200`

Successful response.

- object
  - `status` 'success', required
  - `payload` object: The conversation's updated bot control state.
    - `botControl` 1 | -1, required: The updated bot control state for the conversation. 1 means the bot is active and responding; -1 means the bot is inactive and not responding.
    - `botOffMins` integer, required: Minutes the bot will remain off. 0 means the bot remains off until the next bot control call.
    - `botOffTime` string, date-time, required: When the bot was turned off. `null` unless the bot was turned off with `botOffMins`.

## Other responses

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

---

[API](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide.md) · [All operations](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/llms.txt) · [OpenAPI document](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/revisions/72871007f7f0?raw)