Telegram appears in almost every omnichannel bundle post, including our own beyond-SMS OTT channels guide — but a bundle tells you whether to run Telegram, not how to operate it. This post is the operator guide: the channel's anatomy, what the inbound envelope looks like when it arrives on your webhook, where Telegram is worth running as a primary channel, and how conversations move between bot logic and human agents. Everything here describes shipped behavior on Devotel Orbit; the field-by-field reference lives in the Telegram channel docs.
Telegram channel anatomy: Bot API vs Business Bot constraints
Telegram has two business surfaces, and the difference decides what you can automate.
The Bot API is the surface Orbit connects. A bot is a first-class Telegram entity you create with @BotFather, and it owns a real conversational surface: customers message the bot (or tap a /start deep link), and the bot can send free-form replies, media, and interactive keyboards inside that conversation. The Bot API is free, open, and built for exactly the programmatic use cases a CPaaS operator cares about — notification flows, self-service bots, and support intake.
Telegram Business Bots are a different constraint set: a business bot rides on a personal Telegram account and mostly proxies that account's incoming chats. It suits a sole-trader answering from their own number, not an organization running a branded channel at scale. On Orbit you connect a Bot API bot — one bot per organization, token pasted into the dashboard — and every message shape below runs through that single connection.
One constraint that surprises operators coming from WhatsApp: there is no template pre-approval step. Telegram has no business-message template registry — a bot can send any content to any user who has opened a conversation with it. The gate is conversational, not administrative: the customer must have messaged the bot (or tapped a deep link) first, which makes inbound capture — deep links, QR-to-/start, bot mentions — the entire top of funnel.
The message-shape matrix: text, media, interactive
Orbit's Telegram channel sends five shapes through one endpoint (POST /api/v1/messages/telegram), selected by the type value you pass in metadata:
| Shape | How you send it | What the customer sees |
|---|---|---|
| Text (default) | body only; optional parse_mode (HTML / MarkdownV2) | Formatted text message |
| Photo | type: "photo" + mediaUrl | Image with caption |
| Video | type: "video" + mediaUrl | Video with caption |
| Document | type: "document" + mediaUrl | Downloadable file (PDFs, statements, tickets) |
| Location | type: "location" + latitude / longitude | Map pin |
| Interactive | inline_keyboard / reply_keyboard (JSON-stringified button[][]) | Tappable buttons under or instead of the keyboard |
Two operator notes on the interactive row. First, inline keyboard buttons are your primary conversational primitive: an "Order status" button arrives back at you as an inbound message when tapped (next section), so a menu you render today is an intent you route on tomorrow. Second, chat actions (typing, upload_photo) exist and Orbit auto-emits them while a long-running send is in flight — a small thing that makes bot responses feel immediate rather than batch.
The inbound envelope: channel: "telegram", verified at the edge
Every inbound Telegram update — a typed message, an inline-keyboard tap, a /start deep-link hit — normalizes into the same envelope as every other channel on Orbit: channel: "telegram", direction: "inbound", the contact attached, landing on the standard message.received event. A button press arrives with the button's callback_data as the message body, so "tapped Order status" and "typed order status" look identical to your routing rules — which is exactly how menu-driven flows degrade gracefully into free-text.
Two things happen at the edge before that envelope exists. First, webhook registration is automatic: when you paste the bot token in the dashboard, Orbit registers the inbound webhook with Telegram itself and rotates the secret_token header value. Second, signature verification is on the receive path: every inbound update carries Telegram's X-Telegram-Bot-Api-Secret-Token header, which Orbit validates against the per-bot secret stored encrypted in the credential vault before the update is admitted to your event stream. A forged POST to the webhook endpoint without the current secret is rejected at the edge — your consumer sees only updates that passed per-bot verification, and when the secret rotates (on reconnect) the old value stops admitting traffic immediately.
The failure shape worth planning for is the blocked recipient. When a user blocks your bot, Telegram returns a 403, and Orbit marks the message record failed with error_code: TELEGRAM_USER_BLOCKED rather than erroring the send. Treat that status as an opt-out signal in your tenant's consent records — suppress the recipient from future Telegram sends, because the state is permanent until the user re-engages the bot on their own.
Region fit: where Telegram deserves a primary slot
Run Telegram as a primary channel where it is the app your customers actually open, not where it is merely popular. Three regions consistently qualify:
- Eastern Europe and Central Asia — Telegram's deepest habitual usage; in Ukraine, and large parts of Central Asia, a bot channel routinely out-performs SMS for two-way service traffic because the audience lives there.
- South America — especially Brazil, where Telegram is the second messaging app on most handsets and often the first for community and broadcast groups; operators run it alongside WhatsApp rather than instead of it.
- South Asia — India and neighboring markets, where a large, young user base makes Telegram a strong secondary-conversational channel, particularly for broadcast-style notifications to groups.
The selection rule remains market-first, exactly as in the OTT bundle post: Telegram earns a primary slot where its usage is habitual, and SMS stays the fallback underneath everywhere — OTT reach is an app-install condition, SMS reach is not. In Telegram-heartland markets the practical pairing is Telegram for conversational and broadcast traffic, SMS as the universal catch-all, and WhatsApp where the program spans both audiences.
Bot-to-human handback and template idioms
The operating pattern that makes Telegram scale as a support channel is a clean split between what the bot resolves and what a human takes over — and on Orbit both sides of that split land in the same unified inbox, because inbound Telegram normalizes into the same envelope as SMS and WhatsApp.
A workable handback idiom, built from shipped primitives:
- The customer taps a deep link (
/startfrom a QR in a shipment email, or at.me/yourbot?start=order_12345link) — the deep-link payload lands as inbound context on the contact. - The bot flow runs against that context: an inline keyboard offers "Order status / Talk to an agent", and taps return as routable inbound messages.
- When the tap (or a keyword, or an AI-agent confidence threshold in front of the same inbox) says human, the thread sits in the unified inbox in front of a live agent — with the bot's prior messages in the same timeline, so the agent reads the attempt before answering.
Because Telegram has no template registry, "template idioms" here mean the message shapes you standardize on, not approval artifacts. Three worth fixing in your program: a status-card (text with HTML parse mode, one inline keyboard row of next actions), a document drop (document type for statements and tickets, caption naming the file purpose), and a handback menu (one keyboard whose last row is always "Talk to an agent"). Standardizing the last one is the cheapest support-upgrade most programs skip: it makes the bot-to-human boundary a button the customer already knows, on every flow.
Frequently asked questions
Do I need Telegram-approved templates to send outbound messages?
No. Telegram has no template approval step for the Bot API — the constraint is that the customer opened a conversation with your bot first. Design the inbound capture (deep links, QR-to-bot, mentions) as the top of funnel and outbound is free-form after that.
How does an inline-keyboard tap show up on my webhook?
As a normal inbound message on the standard message.received event — the button's callback_data becomes the message body. There is no separate callback event to subscribe to; your routing treats a tap exactly like a typed reply.
What does the secret_token rotation in the dashboard actually protect?
It is Telegram's per-webhook shared secret. Orbit validates the header on every inbound update against the per-bot value it stores encrypted, so a forged POST to the webhook endpoint is rejected before it reaches your event stream — and rotation on reconnect retires the old value.
A customer blocked our bot. Can we retry?
No — a block is permanent until the user re-engages. Orbit marks the send failed with TELEGRAM_USER_BLOCKED; record it as an opt-out in your tenant's opt-out list and stop sending on the channel.
Can one bot be attached to more than one Orbit organization?
No — one bot, one organization. A second connect attempt against a bot already attached elsewhere returns a 409; disconnect it from the first organization, or rotate the token via BotFather, before reattaching.
The takeaway
Telegram is not hard to run — it is hard to run well as one post in a bundle suggests, because the operating detail lives below the decision level. Connect one Bot API bot per organization, standardize three message shapes including a handback menu, route taps and typed replies through the same envelope, point it at the markets where Telegram is genuinely primary, and keep SMS underneath as the fallback. The cross-references: the beyond-SMS OTT bundle post decides whether Telegram belongs in your stack; the Telegram channel docs carry the request fields, onboarding, and error table this guide operationally assumes.
Published 28 September 2026.