---
title: Bot REST API
updatedAt: 2026-04-03T10:55:58.000Z
---

Fetch the complete documentation index at: https://docs.watchers.io/llms.txt

# Bot REST API

HTTP API for bot integration: send messages, set up webhooks, and poll for updates.

## Overview

The Bot REST API provides an HTTP-based interface for bot integration with Watchers chat rooms. It follows a Telegram Bot API-style design with support for sending messages, webhooks, and long-polling.

For real-time WebSocket-based integration, see [Bot WebSocket API](https://docs.watchers.io/docs/ai-bots-post-message-api).

> ⚠️ **Regional endpoints:** Replace `bot.watchers.io` with the endpoint matching your project region. See [Supported Regions](https://docs.watchers.io/docs/supported-regions) for details.
> | Region | Endpoint |
> | :--- | :--- |
> | Europe (default) | `bot.watchers.io` |
> | North America | `bot.us.watchers.io` |
> | South America | `bot.sa.watchers.io` |
> | Asia | `bot.hk.watchers.io` |
> | Africa | `bot.za.watchers.io` |

## Authentication

All REST API endpoints require three headers:

| Header | Required | Description |
| :----- | :------- | :---------- |
| `X-Api-Key` | Yes | API key of your project (from admin panel) |
| `Authorization` | Yes | `Bearer <token>` — bot bearer token (from admin panel) |
| `X-Bot-Id` | Yes | External ID of the bot |

```bash
curl -X GET 'https://bot.watchers.io/api/bot/getMe' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Authorization: Bearer YOUR_BOT_TOKEN' \
  -H 'X-Bot-Id: YOUR_BOT_EXTERNAL_ID'
```

---

## Endpoints

### GET /api/bot/getMe

Returns information about the bot.

**Response:**

```json
{
  "id": 1,
  "name": "MyBot",
  "externalId": "bot_001",
  "project": "my-project",
  "isActive": true
}
```

---

### POST /api/bot/sendMessage

Sends a message to a chat room on behalf of the bot.

**Request body:**

| Field | Type | Required | Description |
| :---- | :--- | :------- | :---------- |
| `roomId` | string | Yes | Target room ID |
| `text` | string | Yes (if no `stickerId`) | Message text |
| `stickerId` | string | Yes (if no `text`) | Sticker ID to send |
| `mentionMessageId` | string | No | Message ID to reply to (creates a thread) |
| `eventDate` | string | No | Event date associated with the message |
| `eventTitle` | string | No | Event title associated with the message |

**Example:**

```bash
curl -X POST 'https://bot.watchers.io/api/bot/sendMessage' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Authorization: Bearer YOUR_BOT_TOKEN' \
  -H 'X-Bot-Id: YOUR_BOT_EXTERNAL_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "roomId": "sports-room-001",
    "text": "Hello from the bot!"
  }'
```

**Success response:**

```json
{
  "ok": true,
  "result": {
    "sent": true
  }
}
```

**Error responses:**

```json
{ "ok": false, "error": "roomId is required" }
{ "ok": false, "error": "text or stickerId is required" }
{ "ok": false, "error": "Room not found" }
```

---

### POST /api/bot/setWebhook

Registers a webhook URL to receive updates via HTTP POST instead of polling or WebSocket.

> When a webhook is active, `getUpdates` cannot be used.

**Request body:**

| Field | Type | Required | Description |
| :---- | :--- | :------- | :---------- |
| `url` | string | Yes | HTTPS URL to receive webhook payloads |
| `secret` | string | No | Secret string sent as `X-Webhook-Secret` header for verification |
| `events` | string[] | No | Event types to subscribe to. Default: `["message", "bot_mention"]` |

**Example:**

```bash
curl -X POST 'https://bot.watchers.io/api/bot/setWebhook' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Authorization: Bearer YOUR_BOT_TOKEN' \
  -H 'X-Bot-Id: YOUR_BOT_EXTERNAL_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://my-server.com/watchers-webhook",
    "secret": "my-secret-key",
    "events": ["message", "bot_mention"]
  }'
```

**Webhook payload delivered to your URL:**

```json
{
  "event": "bot_mention",
  "project": "my-project",
  "roomId": "sports-room-001",
  "messageId": 12345,
  "text": "@MyBot what is the score?",
  "userId": "user_789",
  "botName": "MyBot",
  "replyTo": {
    "id": 12340,
    "text": "Previous message"
  },
  "eventDate": null,
  "eventTitle": null,
  "timestamp": "2026-04-03T10:00:00.000Z"
}
```

> Webhook delivery retries up to 3 times with backoff on failure.

---

### POST /api/bot/deleteWebhook

Removes the bot's webhook. After deletion, you can use `getUpdates` for long-polling.

**Example:**

```bash
curl -X POST 'https://bot.watchers.io/api/bot/deleteWebhook' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Authorization: Bearer YOUR_BOT_TOKEN' \
  -H 'X-Bot-Id: YOUR_BOT_EXTERNAL_ID'
```

---

### GET /api/bot/getWebhookInfo

Returns the current webhook configuration.

**Response (webhook set):**

```json
{
  "url": "https://my-server.com/watchers-webhook",
  "hasSecret": true,
  "events": ["message", "bot_mention"]
}
```

**Response (no webhook):**

```json
null
```

---

### GET /api/bot/getUpdates

Long-polling endpoint to receive updates. Use this as an alternative to WebSocket or webhooks.

> Cannot be used while a webhook is active. Call `deleteWebhook` first.

**Query parameters:**

| Parameter | Type | Required | Description |
| :-------- | :--- | :------- | :---------- |
| `timeout` | number | No | Long-poll timeout in seconds (1–30, default: 10) |
| `offset` | number | No | Skip updates with ID ≤ offset. Use `last_update_id + 1` to confirm previous updates. |

**Example:**

```bash
curl -X GET 'https://bot.watchers.io/api/bot/getUpdates?timeout=15&offset=100' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Authorization: Bearer YOUR_BOT_TOKEN' \
  -H 'X-Bot-Id: YOUR_BOT_EXTERNAL_ID'
```

**Response:**

```json
[
  {
    "id": 101,
    "event": "bot_mention",
    "project": "my-project",
    "roomId": "sports-room-001",
    "messageId": 12345,
    "text": "@MyBot hello!",
    "userId": "user_789",
    "botName": "MyBot",
    "replyTo": null,
    "eventDate": null,
    "eventTitle": null,
    "timestamp": "2026-04-03T10:00:00.000Z"
  }
]
```

**Notes:**
- Maximum queue size: 1000 updates
- Updates older than 24 hours are automatically discarded
- Pass `offset` to confirm you've processed updates up to that ID

---

## Integration Patterns

### Pattern 1: Webhook (recommended for production)

Best for always-on servers. Set a webhook and receive updates as HTTP POST requests.

```
1. POST /api/bot/setWebhook  →  register your endpoint
2. Receive POST requests     →  process messages
3. POST /api/bot/sendMessage  →  reply to users
```

### Pattern 2: Long-Polling

Best for development, testing, or serverless environments.

```
1. GET /api/bot/getUpdates  →  fetch new messages (blocks until timeout)
2. Process messages
3. POST /api/bot/sendMessage  →  reply
4. Repeat with offset = last_id + 1
```

### Pattern 3: WebSocket (real-time)

Best for lowest latency. See [Bot WebSocket API](https://docs.watchers.io/docs/ai-bots-post-message-api).

---

## Error Handling

All endpoints return standard HTTP status codes:

| Code | Meaning |
| :--- | :------ |
| 200 | Success |
| 400 | Bad request (missing or invalid parameters) |
| 401 | Unauthorized (invalid bearer token) |
| 403 | Forbidden (bot not found or inactive) |
| 404 | Not found (invalid API key / project) |