Telegram

Set it up

1. Create a bot

   In Telegram, open @BotFather, send /newbot, and choose a name and a user name ending in bot. BotFather answers with a token such as 123456789:AAE4rT9wK2pQx7LmN3vB8sZ1cY6uH0dJ5fG (/token shows it again for an existing bot).

2. Connect it

   Settings › Marketplace › Telegram › Install in this workspace, or Settings › Inboxes › Add inbox › Telegram. Paste the token and press Test connection: Kommio shows the bot's name and user name.

3. Try it

   Name the inbox and choose its agents. The last step, and the inbox's page later, shows the bot's t.me link and a QR code: open it on a phone, send a message, and it arrives in the inbox.

The token is stored encrypted and never returned by the API. If you revoke it in BotFather, paste the new one on the inbox's page (Bot token) and Kommio connects the bot again. When Telegram refuses the stored token, the inbox goes into error: its page opens with a banner that says so and what to do, Settings › Inboxes shows How to fix it linking to this page, and everyone who manages inboxes gets a notification. The workspace's owner also gets an email with Inspect and Acknowledge buttons, with reminders that back off (incident emails).

How messages arrive

On Kommio Cloud, Telegram delivers each message to the inbox's own webhook address, and every delivery must carry two secrets derived for that inbox from the bot token; anything else is refused and stores nothing. Messages customers send while the inbox is paused are kept by Telegram and arrive when it resumes. A self-hosted installation without a public HTTPS address asks Telegram for new messages instead, and confirms them only once they are stored.

Every five minutes Kommio checks the bot with Telegram. The installation under Settings › Marketplace › Installed shows how messages arrive, how many are waiting at Telegram and Telegram's last delivery error; a recent error with messages waiting puts the inbox in error, and a revoked token asks for a reconnect.

What is supported

Private chats only. Messages in groups and channels, and the bot being added to one, are ignored and reported on the inbox and its installation.

Files larger than 20 MB, Telegram's download limit for bots, are not fetched; the conversation says so. Stored files follow Kommio's 25 MB limit and file-type rules.

The customer becomes a contact with the identity telegram:<user id>, their Telegram name, the attributes telegram_username and telegram_language (set only when empty, never overwriting your team's edits), and their profile picture.

A reply shows as sent, or as failed with Telegram's error. When Telegram asks Kommio to slow down, it waits and tries again; a customer who blocked the bot, or a chat that no longer exists, fails for good without retries, so nothing is sent twice. There is no reply window: the bot may answer a customer at any time after they wrote to it, but it cannot start a chat with someone who never did.

Commands and deep links

The bot has a command menu (the "/" button next to Telegram's input box), set whenever the inbox is created, its token replaced or it is resumed: in English for everyone and, when the workspace language (Settings › General) is another of Kommio's sixteen, in that language for customers whose Telegram speaks it. A command is handled as a command: it never becomes a customer message, no bot or rule answers it, and it never reopens anything.

Deep links. https://t.me/<bot>?start=<payload> opens the chat with the payload (up to 64 letters, digits, _ and -, Telegram's limit) as the customer's first /start. The payload is kept on the conversation as the attribute telegram_start whatever its shape, and two shapes act:

• ref_<campaign> tags the conversation with the campaign (t.me/acme_support_bot?start=ref_summer-sale adds the tag summer-sale) and records an activity line, so reports and views can filter by it.
• order_<id> leaves a private note "The customer opened the chat from order <id>".

A deep link opened while a conversation is open applies to that conversation. A link from the website chat that continues the same person's chat in Telegram is not offered yet.

Welcome and buttons

On a customer's first /start the bot sends the inbox's greeting (Settings › Inboxes › the inbox › General; Kommio's own text in the workspace language when it is empty; {{contact.name}} and the other placeholders work) and, when the inbox defines them, up to eight buttons under it, set on the Welcome message and buttons card on the inbox's page. Each button has a label and one action: route to a team, start a chatbot flow (one attached to the inbox and published), set the customer's language (the attribute language on the contact and the conversation), or add a tag.

A tap is answered at once, applied, recorded as an activity line (such as "Chose "Sales": routed to Sales"), and the buttons are removed from the message, so nothing can be tapped twice; the tap is not a customer message, so no bot answers it. A button whose team or flow no longer exists records the choice and the reason. Each welcome keeps the buttons it was sent with, so a tap does what the button said at the time. A customer who opens a conversation with a plain message gets no welcome; one who comes back after a resolution and sends /start gets it again.

Satisfaction surveys

When a conversation on a Telegram inbox is resolved and the inbox's survey is on (its Satisfaction card; off by default), the bot sends the question with the card's rating scale as buttons: five faces, five stars, or thumbs up and down. The tap is the response and lands in the satisfaction reports, rules on csat.submitted and webhooks like a rating from the website chat or the survey email; the buttons are then removed. With comments on, the bot asks for one with a reply box on its message, and the customer's reply to that prompt is the comment and nothing else: it does not reopen the resolved conversation. With a comment required for a low rating, the rating waits for the comment and is recorded with it. A rating can be changed for 24 hours, and a survey closes after 7 days.

The same limits as survey emails apply: a conversation is surveyed at most once a day and three times in all, and a customer at most once a day across their conversations.

The customer's language

Telegram sends the language of the customer's app. Besides the raw tag in telegram_language, Kommio maps it to one of its sixteen languages (Tagalog, tl, maps to Filipino) and stores it as the attribute language on the contact and on the conversation, each only where it is empty: a value an agent or a rule set stays, and agents may edit it. A language outside the sixteen sets nothing, and the workspace language applies. The AI agent answers in it when the conversation has no website visitor language, rules and flows can branch on it, and the flood acknowledgement goes out in it.

Edits, deletions and "seen"

• Edits. When a customer edits a message in Telegram, the stored message changes in place: the thread marks it "edited" and shows what it said before on hover, and updates live. The earlier text of the last ten edits is kept with the message, shown to whoever sees the message, and erased with the contact.
• Deletions. Telegram does not tell a bot when a customer deletes a message in a private chat, so a deleted message stays in Kommio as it was. Kommio has no way to delete a reply it sent today, so nothing is deleted on Telegram either.
• Seen. Telegram has no read marker a bot can set and tells bots nothing about reads, so the agent app never shows "Seen" for Telegram. Instead, an inbox can react to the customer's newest message with 👀 when an agent opens the conversation: quiet, no notification. It is off by default; the Telegram behaviour card on the inbox's page has the switch and a choice among the emoji Telegram lets a bot use. A reaction Telegram refuses (a message too old, a customer who blocked the bot) is not retried.

When a customer blocks the bot

Telegram tells the bot when a customer blocks it. Kommio then lists their Telegram identity as unreachable for that inbox, the thread shows "The customer blocked the bot. Replies to them are not sent until they can be reached again.", and every reply from then on, from an agent, a bot, a rule or the AI agent, fails at once with that reason and the time, without asking Telegram. A send Telegram refuses because the bot was blocked lists the customer the same way. When they unblock the bot, the thread says so and replies go out again; a reply that failed is not resent by itself. A deactivated Telegram account and a customer who never started the bot are explained on the failed reply too. The listing is per inbox, since a customer blocks one bot at a time.

Flood control

• When a chat sends more than 30 messages within 10 minutes (the Telegram behaviour card sets both; 0 turns it off), Kommio replies once "We received your messages; an agent will reply as soon as possible." in the conversation's language, and nothing more until someone on the team replies. The acknowledgement is an automatic reply and counts as one, in the thread and in reports.
• Identical messages in a row (same text, no files, within an hour) show as one message, "sent N times"; the time of each is kept, and the conversation still moves with every one.
• Telegram is never answered with an error or a delay, and every message is stored.

Telegram inboxes imported from Chatwoot

A Telegram inbox imported from Chatwoot arrives as a read-only history inbox that keeps each customer's Telegram user id. On its page, Connect Telegram takes the bot token: the inbox becomes a live Telegram inbox, and a returning customer's next message lands on their imported contact and history.

API

# check a token: who the bot is
curl -X POST "$KOMMIO_URL/channels/telegram/test" -H "Authorization: Bearer $KOMMIO_KEY" -H "Content-Type: application/json" \
  -d '{"config": {"bot_token": "123456789:AAE4rT9wK2pQx7LmN3vB8sZ1cY6uH0dJ5fG"}}'

# create the inbox
curl -X POST "$KOMMIO_URL/inboxes" -H "Authorization: Bearer $KOMMIO_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Telegram", "channel_kind": "telegram", "config": {"bot_token": "123456789:AAE4rT9wK2pQx7LmN3vB8sZ1cY6uH0dJ5fG"}}'

The inbox's config then carries bot_username, bot_name, bot_id and delivery. PUT /inboxes/{id} with config.welcome_keyboard sets the welcome buttons (buttons, at most eight, each with a label and an action of team, flow, language or tag, with its team_id, flow_id, language or tag), and takes the behaviour settings seen_reaction (default false), seen_emoji (default 👀), flood_limit (default 30, 0 for off) and flood_window_minutes (default 10). POST /inboxes/{id}/reconnect connects an imported history inbox, and GET /contacts/{id}/avatar serves the picture Telegram provided.