Skip to main content
Telegram lets your flow live inside the world’s most popular messaging app. You create a bot with @BotFather, connect it once, and any DM sent to that bot becomes a conversation in your flow.

​
When to use Telegram

  • Consumer-facing support or assistant bots where your audience already lives in Telegram.
  • International / emerging-market audiences where Telegram has higher reach than Slack or Teams.
  • Lightweight bots that don’t need a website or login — just t.me/your_bot and people can chat.
  • Group-channel companions where the bot answers questions when DM’d.

​
Responder mode only

Telegram is a responder-only channel. The bot can reply to anyone who has messaged it, but it cannot cold-start a conversation with a user it has never met.
This is a Telegram platform restriction, not a CogniAgent one. Telegram’s Bot API does not expose a way to look up users by @username for DM purposes — bots can only send messages to chats they have already received a message in. The standard workaround is a deep link like t.me/your_bot?start=welcome, which a user clicks first; once they tap Start, your bot has their chat_id and can talk.
If you need a bot that proactively reaches out to users (a marketing blast, a scheduled reminder to a new lead), Telegram isn’t the right channel — use SMS, WhatsApp Business, or Email instead.

​
Before you start

You need two things:
  1. A bot token from @BotFather on Telegram.
  2. A builtin Composio Telegram connection in CogniAgent that holds the token.

​
Create the bot with @BotFather

1

Open @BotFather in Telegram

Search for @BotFather and start a chat. It’s the official bot for creating other bots.
2

Send /newbot

BotFather asks for:
  • A display name (what users see, e.g. “Acme Support”).
  • A username ending in bot (e.g. acme_support_bot).
3

Copy the token

BotFather replies with a token of the form 1234567890:ABCdef.... Keep this safe — anyone with the token can impersonate your bot.
4

(Optional) Configure the bot

While you’re in BotFather you can also set:
  • /setdescription — the “About” blurb users see before they start the chat.
  • /setuserpic — a profile photo.
  • /setprivacy — Disable if you want the bot to read all messages in groups it’s added to (not just @mentions). Default is Enable (only sees @mentions).

​
Add the Telegram channel and connect the bot

The Telegram connection is created from inside the channel-add flow — there’s no separate trip to the Integrations page first.
1

Open the flow's Channels configuration

Go to Conversations → open the flow → Configuration → Channels tab.
2

Add Channel → Telegram

Click Add Channel and pick Telegram from the channel picker.
3

Create (or pick) a Telegram connection

The channel form’s Connection field lets you either pick an existing Telegram connection or create a new one inline. When creating new, the form asks for an API Key — paste the BotFather token here. The form’s description text walks through the BotFather flow if you skipped it above.
4

Save and Deploy

Save the channel and deploy the flow. Within ~5 seconds your bot starts polling for new messages, and any DM to @your_bot creates a conversation.
Once created, the connection is reusable — you can pick it from the dropdown in any other flow’s Telegram channel configuration. Manage integration connections →

​
How conversations are scoped

Each conversation is keyed by chat_id : from_user_id — the chat the message arrived in and the user who sent it. This mirrors how Slack scoping works in DM mode.

​
Outbound formatting (MarkdownV2)

The bot sends replies with parse_mode: MarkdownV2. The flow’s actor prompt is auto-augmented to nudge the LLM toward MarkdownV2-safe output, but a few quirks are worth knowing:
  • Single-delimiter bold: *bold* (not **bold**).
  • Single-delimiter italic: _italic_.
  • Reserved characters must be backslash-escaped when used as literal text:
    So a literal 1.5 should be written 1\.5, and https://example.com/path should escape the dot too.
  • Code spans use backticks. Triple backticks for fenced code blocks (with an optional language tag) work the same as GitHub.
If a reply ever fails to render (you see escape characters in the message), it usually means the LLM forgot to escape a reserved character. This is rare with Sonnet, but possible — re-asking (“please re-send escaped properly”) usually fixes it.
Keep messages short and chat-shaped. Telegram DMs are scanned on a phone — a wall of markdown looks worse than a few short paragraphs. The system prompt steers the actor this way already.

​
Rich content

Inline keyboards, photo uploads, and audio replies are on the roadmap but not in the initial release.

​
How polling works

There is no Telegram webhook to host — the platform polls Telegram’s getUpdates API every 5 seconds with an offset bookmark stored in Redis. Updates older than 24 hours that have never been claimed get garbage-collected by Telegram, so the worst-case delivery delay is bounded. If you previously set a webhook on the same bot (via setWebhook), Telegram refuses to serve getUpdates and returns HTTP 409. The poller logs this as a warning. To resolve, call https://api.telegram.org/bot<TOKEN>/deleteWebhook once and the poller resumes.

​
Per-user identity

Inbound messages carry the sender’s:
  • from_id — numeric Telegram user id.
  • from_username — the @handle, if set (optional in Telegram).
  • from_first_name / from_last_name — display name parts.
The flow sees a resolved participantName (e.g. "Sarah Lee" or "@sarah_lee" if no real name is set) which actors can reference in their prompts.

​
Limitations

  • Bots cannot DM users who haven’t started a chat with them. There is no “cold outreach” path on Telegram for bots.
  • Group chats: by default Telegram bots in groups only receive messages that @mention them. To see every message, toggle /setprivacy to Disable in BotFather — but expect higher inbound volume.
  • @username is not a stable destination identifier. Telegram only treats numeric chat_id as routable. The platform stores the numeric id internally.
  • A single bot token serves one bot. If you want a different persona, create a new bot in BotFather and a new connection in CogniAgent.

​
Troubleshooting

​
Next

Messaging channels

Slack and Teams — the closest cousins of Telegram.

Deploy a flow

Schedule the Telegram listener.