PushizoDocs
Channels

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

ProviderRequirementsNotes
telegram_botBot token from @BotFatherValidation reads the bot username (telegram_bot_username)
viber_botAuthentication token from the Viber Admin Panel, sender name (≤28), optional https avatarValidation 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/register

This 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 like viber://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

FieldDescription
contentsPlain text (Telegram ≤4096, Viber ≤7000 characters); personalized with Liquid
messenger_image_urlImage (https); the text becomes its caption (Telegram ≤1024, Viber ≤768)
messenger_buttonsUp 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 delivered once Telegram accepts the message. If the bot is blocked or the chat is not found, the subscription is marked invalid.
  • Viber: the delivered and seen callbacks are recorded as delivery and open (read); failed marks 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-Token header, Viber requests with X-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.

On this page