Telegram
Connect a Telegram bot when you want an agent available from Telegram direct messages, groups, or topics.
Prerequisites
- An existing Cloud Agents agent.
- A Telegram bot token from
@BotFather - Permission to add the bot to the target group, if you want group access.
Create a bot
- Open Telegram and start a chat with
@BotFather. - Send
/newbot. - Choose a display name and a globally unique username ending in
bot. - Copy the bot token.
- For group use, open BotFather’s bot settings and turn off Group Privacy if the bot needs to receive normal group messages.
Connect it to Cloud Agents
- Open Settings -> Channels.
- Create a new channel and choose Telegram.
- Select the agent that should receive messages.
- Enter a label and paste the bot token.
- Create the channel.
- Run the channel test.
Cloud Agents registers the Telegram delivery URL automatically after the channel is created.
Recommended settings
| Setting | Recommendation |
|---|---|
| Mention only | Keep on for groups so the agent replies only when mentioned. |
| Shared session | Keep off unless everyone in the group should share one conversation. |
| Thread isolation | Keep on for topic or reply-based conversations. |
| Progress mode | Use preview if you want a progress message while the agent works. |
Verify
Open the channel detail page and run Test. A healthy channel shows the bot identity and confirms Telegram delivery is registered.
Troubleshooting
- Token test fails: create a new token in BotFather and update the channel.
- Direct messages work but group messages do not arrive: disable Group Privacy in BotFather or mention the bot.
- Group messages arrive but are ignored: mention the bot username or turn off mention-only mode.
- The bot replies in the wrong context: turn thread isolation on for topic or reply-heavy groups.