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.

⚠️
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

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

Shell

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:

Shell

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:

Shell

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:

Shell

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:

Shell

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.

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)

Updated 5 months ago