Bot REST API

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.

⚠️

Regional endpoints: Replace bot.watchers.io with the endpoint matching your project region. See 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:

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:

{
  "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:

Example:

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:

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

Error responses:

{ "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:

Example:

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:

{
  "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:

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):

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

Response (no webhook):

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:

Example:

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:

[
  {
    "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.

Error Handling

All endpoints return standard HTTP status codes: