Connect Telegram and test end-to-end
If you just need the essentials, follow this quick path:
- Understand what a Telegram channel is (Bot + URN behavior)
- Know Telegram’s key limits (bots can’t message new contacts first)
- Create a bot via BotFather and copy the token
- Add the Telegram channel in RapidPro.app and paste the token
- Test inbound + outbound (Messages + a simple flow)
Telegram is ideal for early testing and can also work well in production when your audience has reliable internet access.
Step-by-Step Process
A Telegram channel connects your RapidPro.app workspace to Telegram so your flows can send and receive messages.
In RapidPro.app, the Telegram integration is represented by a Telegram Bot, which acts as the interface between Telegram’s API and your flows.
[CAPTURE: Channels list showing a Telegram channel labeled as a Bot integration.]
Telegram bots usually cannot initiate conversations with brand-new contacts.
By default, a contact must first:
- message your bot, or
- add the bot to a group.
After the first interaction, the contact appears in RapidPro.app and you can send messages at scale (flows, broadcasts, campaigns).
[CAPTURE: Telegram chat showing a user sending the first message to a bot.]
- Open Telegram and start a chat with BotFather.
- Create a new bot and choose a bot username (usernames typically end in bot).
- Copy the bot token provided by BotFather.
[CAPTURE: BotFather chat showing the bot token (blurred).]
- Open Workspace Settings (gear icon).
- Go to Channels and click + New Channel.
- Select Telegram.
- Paste your bot token and save.
- Confirm the channel appears as Enabled in your Channels list.
[CAPTURE: Add Channel page showing Telegram selected and a Token field (blurred).]
- From a personal Telegram account, send a message to your bot.
- Confirm the message appears in RapidPro.app under Messages (and/or the contact history).
- Run a simple flow that replies to the contact and confirm the reply is delivered in Telegram.
- If you plan to broadcast, test a small broadcast to a few contacts who have already messaged the bot.
[CAPTURE: RapidPro.app Messages view showing an inbound Telegram message and a reply sent.]
Common Issues & Quick Fixes
My bot can’t message new people first
Cause: This is expected behavior for Telegram bots.
Fix: New contacts must message the bot first (or add it to a group). After that first interaction, you can message them through flows and broadcasts.
Broadcasts don’t reach anyone on Telegram
Cause: Your audience may not have interacted with the bot yet, so they are not reachable via Telegram.
Fix:
- Confirm contacts have already messaged the bot at least once.
- Verify those contacts exist in RapidPro.app and have a Telegram address/URN.
Messages send too slowly or get rate-limited
Cause: High burst sending can hit practical bot throughput limits.
Fix:
- Reduce burst sending (send in smaller batches).
- Stagger broadcasts and avoid unnecessary retries.
I connected the bot, but inbound messages don’t appear
Fix:
- Confirm the bot token is correct.
- Verify the channel is enabled in Workspace Settings → Channels.
- Re-test by sending a fresh message to the bot and checking message logs.