Bots
Hosted Telegram bots: registration, flows, webhooks, and rate limits
The platform lets you host Telegram bots directly. Each bot runs on the platform's infrastructure and can be configured with message flows, webhook handlers, and broadcast capabilities.
Bot registration
- Create your bot on Telegram by talking to @BotFather. You will receive an API token.
- In the platform, go to Bots > Register new bot.
- Enter the bot username, the API token from BotFather, and an optional display name.
- The platform verifies the token against the Telegram Bot API and, on success, registers the bot to your workspace.
| Field | Required | Description |
|---|---|---|
| Username | Yes | The bot's @username on Telegram |
| API token | Yes | The token issued by BotFather |
| Display name | No | A friendly label for your workspace (defaults to the bot's Telegram name) |
| Webhook URL | No | HTTPS endpoint for incoming updates |
| Flows | No | JSONB array of flow definitions |
Flow definitions
Bot behavior is defined as a JSONB array of flows. Each flow is an object with a trigger condition and an action.
| Trigger type | Description |
|---|---|
command | Fires when a user sends a specific command (e.g., /start, /help) |
message | Fires on any incoming message matching optional text filter |
new_chat_member | Fires when a new user joins a group where the bot is a member |
callback_query | Fires on inline keyboard button presses |
| Action type | Description |
|---|---|
send_message | Sends a text message to the chat |
send_photo | Sends a photo from a URL |
send_document | Sends a document from a URL |
answer_callback | Responds to a callback query with a toast notification |
leave_chat | Makes the bot leave the current group chat |
Webhook URL and signature verification
If you provide a webhook URL, the platform forwards all bot updates to that URL as HTTPS POST requests with a JSON body. Each request includes a signature header for verification.
| Header | Value |
|---|---|
X-TelegramOS-Signature | HMAC-SHA256 of the request body, keyed with your bot's API token |
X-TelegramOS-Timestamp | Unix timestamp of when the request was sent |
Content-Type | application/json |
To verify a webhook request:
Webhook requests that do not respond with HTTP 200 within 5 seconds are retried up to 3 times with exponential backoff (2s, 4s, 8s). After 3 failures, the webhook is temporarily disabled for 5 minutes.
Rate limits
| Limit | Scope | Value |
|---|---|---|
| Messages per second | Global per bot | 30 |
| Messages per second | Per chat | 1 |
| Messages per minute | Per chat | 20 |
| Broadcast recipients | Per broadcast | 10 |
| Broadcast message length | Per message | 1000 characters |
State management
Bot flows are single-shot: each trigger-action pair executes independently with no persistent session memory between invocations.
State management between invocations is your responsibility. You can use the webhook endpoint to store state in your own system. The platform does not provide a built-in key-value store for bot session data.
Roadmap
The following bot features are on the roadmap but not yet available:
- Persistent session memory (key-value store per user)
- Scheduled broadcasts (one-time and recurring)
- Inline mode support
- Payment integration via Telegram Stars
- Bot analytics dashboard (message volume, user growth, response times)
Broadcast safety
Broadcasts from bots are subject to additional safety limits to prevent spam:
- Max 10 recipients per broadcast call
- Max 1000 characters per message
- Spam guard: If more than 10% of broadcast recipients in a 24-hour window block or report the bot, broadcast capability is suspended for 72 hours
- Cooldown: 60 seconds minimum between successive broadcast calls