Telegram and Viber: bot messaging, deep-link subscriptions and the inbox
The Telegram and Viber channels send text, image and button messages through your business bot; replies land in the Inbox (ADR-0086). Both channels work with a bot identity rather than a phone number: you cannot message someone who…
The Telegram and Viber channels send text, image and button messages through your business bot; replies land in the
Inbox (docs/adr/0086-telegram-viber.md). Both channels work with a bot identity rather than a phone number:
you cannot message someone who has not started your bot. That is why a subscription is linked to your user through a
personal deep link. The channels require the messengers plan feature (Starter and above).
1. Setup
| Provider | Requirements | Notes |
|---|---|---|
telegram_bot | Bot token from @BotFather | Validation reads the bot username (telegram_bot_username) |
viber_bot | Authentication token from the Viber Admin Panel, sender name (≤28), optional https avatar | Validation reads the bot URI (viber_uri) |
mock | — | No real sending; the outcome depends on the last four digits of the chat/user ID (0001 invalid, 0002 permanent error, 0003 transient, 0004 rate limit) |
PUT /internal/v1/apps/{appId}/channels/telegram
{ "provider": "telegram_bot", "bot_token": "123456789:AA…" }
PUT /internal/v1/apps/{appId}/channels/viber
{ "provider": "viber_bot", "auth_token": "4453b6ac…", "sender_name": "Markam", "sender_avatar": "https://cdn.markam.com/logo.png" }Tokens are stored with envelope encryption and never appear in responses or logs. The channel is validated automatically after saving. Then register the webhook with the provider in one call (the Register webhook button on the channel card in the dashboard):
POST /internal/v1/apps/{appId}/channels/telegram/hook/registerThis calls Telegram setWebhook (with a secret secret_token) or Viber set_webhook. The webhook URL is based on
API_URL and must use https. For a manual setup, get the URL and the Telegram secret token from
GET …/channels/telegram/hook (viewing it is recorded in the audit log).
2. Linking a subscriber (deep link)
Your server creates a single-use link for the user and shows it in your app or in an email:
POST /v1/apps/{appId}/messenger-links
Authorization: Bearer <users:write key>
{ "channel": "telegram", "external_id": "customer-42", "ttl_seconds": 86400 }
201 { "url": "https://t.me/markam_bot?start=Qm9…", "token": "Qm9…", "user_id": "usr_…", "expires_at": "…" }- A Telegram link looks like
https://t.me/<bot>?start=<token>, a Viber link likeviber://pa?chatURI=<uri>&context=<token>. - When the person opens the link and starts the bot, the chat ID is linked to this user as a subscription
(
opt_in_source = deep_link). The token works once, expires (7 days by default, at most 30 days) and only its hash is stored in the database. - Someone who starts the bot with an invalid or used token still gets a subscription, but it is not linked to a user.
- On Viber, the person may not be subscribed yet when they open the chat: the link is recorded, the subscription stays pending and becomes active once they subscribe or message the bot.
- If the person blocks the bot (Telegram) or unsubscribes (Viber), the subscription is closed; the STOP/START keywords work as well. The SDK cannot register subscriptions on these channels; a chat ID is linked only through the bot.
3. Content
| Field | Description |
|---|---|
contents | Plain text (Telegram ≤4096, Viber ≤7000 characters); personalized with Liquid |
messenger_image_url | Image (https); the text becomes its caption (Telegram ≤1024, Viber ≤768) |
messenger_buttons | Up to 6 buttons: { "type": "url", "text", "url" } or { "type": "reply", "text", "payload" } |
{
"app_id": "app_…",
"contents": { "en": "Hi {{ user.properties.first_name }}, your order is on its way." },
"messenger_image_url": "https://cdn.markam.com/shipping.png",
"messenger_buttons": [
{ "type": "url", "text": "Track order", "url": "https://markam.com/order" },
{ "type": "reply", "text": "Support", "payload": "support" }
],
"target": { "include_aliases": { "external_id": ["customer-42"] }, "channels": ["telegram", "viber"] }
}On Telegram the text is sent without formatting. Link buttons are turned into tracked short links; clicks are written to the delivery report. When someone taps a reply button, their choice appears in the inbox as their message. In the dashboard the Telegram/Viber tab of the content editor is shared by both channels.
4. Delivery and read
- Telegram: the Bot API has no separate delivery receipt; the delivery becomes
deliveredonce Telegram accepts the message. If the bot is blocked or the chat is not found, the subscription is marked invalid. - Viber: the
deliveredandseencallbacks are recorded as delivery and open (read);failedmarks the delivery as failed. If the person is not registered or not subscribed, the subscription is marked invalid.
5. Inbox and AI agent
Text messages, button choices and media (by provider ID) appear in the inbox as Telegram or Viber conversations.
Replies from the inbox are sent as text. You can add telegram and viber to keyword channels; the conversational
AI agent (AI agent) can handle these channels too.
6. Security
- Telegram webhook requests are verified with the
X-Telegram-Bot-Api-Secret-Tokenheader, Viber requests withX-Viber-Content-Signature(HMAC-SHA256 with the authentication token); a request that does not match gets 401. - The token in the webhook URL is bound to the channel and provider; the wrong channel path returns 404.
- A deep-link token belongs to one app: it cannot be used with another app's bot.
RCS: Google RBM and Twilio RCS, rich cards and SMS fallback
The RCS (Rich Communication Services) channel sends rich cards, images and suggestion chips to the Android messaging app. Devices that do not support RCS receive the text equivalent of the same message through the app's SMS channel (ADR-0029 §3).…
In-app messages
In-app messages — block-based modal/banner/fullscreen layouts, triggers, audience, frequency, actions, A/B variants, SDK contract and public API.