Bots
Host Telegram bots on TelegramOS: registration, visual flows, webhooks, broadcasts and rate limits explained.
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) |
| Delivery mode | No | polling (default) or webhook — see below |
| Flows | No | JSONB array of flow definitions |
Flow definitions
Bot behavior is built as flows in the visual flow editor. A flow starts at a trigger and runs a chain of nodes: actions, logic, and flow control.
| Trigger | Fires when |
|---|---|
command | A user sends a command (e.g., /start, /help) |
message | A message arrives in a chat with the bot |
callback | A user presses an inline keyboard button |
member_join | A new member joins a group the bot is in |
schedule | On a schedule |
webhook | An incoming webhook call |
| Node group | Nodes |
|---|---|
| Actions (14) | send_message, send_media, edit_message, delete_message, typing, ask, buttons, http, db, ai, poll, dice, location, contact |
| Logic (6) | condition, switch, set_variable, delay, random, loop |
| Flow (3) | end, goto, call |
Delivery mode: polling or webhook
A bot receives Telegram updates in one of two ways:
- Polling — the platform pulls updates with
getUpdates. No public URL is needed. This is the default and works behind NAT. - Webhook — the platform registers its own endpoint for your bot with
setWebhook, so Telegram pushes updates straight to it. You do not supply a URL, and you do not need a server of your own.
Webhook deliveries are authenticated with a random 32-byte secret the platform generates per bot and passes to Telegram as secret_token. Telegram echoes it back on every update in the X-Telegram-Bot-Api-Secret-Token header, and requests without a matching secret are rejected. Switching to webhook mints a new secret; switching back to polling clears it.
If the platform has no public webhook URL configured, bots are kept on polling.
Requests made by a flow's HTTP-request node are plain: they carry only the headers you configure and are not signed, so protect such endpoints with a secret path or an IP allowlist. Event webhooks registered under Settings → API keys → Webhooks are different — every delivery is signed with X-TGP-Signature (HMAC-SHA256); see API › Webhooks.
Rate limits
| Limit | Scope | Value |
|---|---|---|
| Broadcast recipients | Per broadcast | 100 |
| Broadcast message length | Per broadcast | 1000 characters |
| Send pacing | Within a broadcast | ~0.05 s between messages |
| Bot registration | Per user | 10 per minute |
Flow sessions
Flows are not single-shot. Each bot keeps a flow session per chat, and the variables a flow sets live in that session.
askpauses the flow; the user's reply in that chat resumes it.- A session expires after 6 hours.
For state that must outlive a session, keep it in your own system, for example through the http node.
Roadmap
The following bot features are on the roadmap but not yet available:
- 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 these limits:
- Max 100 recipients per broadcast
- Max 1000 characters per message
- Pacing: sends go out about 0.05 s apart
- Spam-word filter: texts containing words such as "airdrop", "casino" or "buy now" are rejected