Telegram Integration

This document explains how to create a Bot in Telegram, then connect and verify the Telegram integration in Flocks.

Use Cases

• Trigger Rex through Telegram direct messages or group chats.
• Push Task Center, Workflow, or conversation results to Telegram.
• The deployment environment can access the Telegram Bot API, or a working proxy is available.

Prerequisites

• The Telegram client is installed and logged in.
• The current network can access api.telegram.org, or an HTTP / HTTPS / SOCKS5 proxy is available.
• If you plan to use Webhook mode, prepare a publicly accessible HTTPS address.

Procedure

1. Create a Bot Through BotFather

Telegram Bots must be created through the official @BotFather, which provides the Bot Token.

1. Search for @BotFather in Telegram, or open https://t.me/BotFather.
2. Send /newbot to BotFather.
3. Follow the prompts and enter the bot display name, for example Flocks Assistant.
4. Enter the bot username. The username must be globally unique and must end with bot, for example flocks_assistant_bot.
5. BotFather returns a Bot Token, usually in a format similar to:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Store the Bot Token securely. Anyone with this Token can control the Bot. If the Token leaks, use /revoke in BotFather immediately to regenerate it.

2. Optional: Configure Bot Information

To help team members identify the bot, you can continue configuring it in BotFather:

Command	Purpose
/setdescription	Set the description users see when they first open the bot
/setabouttext	Set the short introduction on the bot profile page
/setuserpic	Upload the bot avatar
/setcommands	Set the / command menu in the chat box
/setprivacy	Set group chat privacy mode

If you want to configure the command menu, you can start with these basic commands:

help - View help
new - Start a new conversation
status - View current conversation status

3. Configure the Telegram Channel in Flocks

1. Go to "Messaging Integrations -> Telegram" in the Flocks WebUI.
2. Enter the Bot Token returned by BotFather in the account credentials area.
3. Fill in or adjust the following configuration items as needed:

Configuration Item	Description
Default Agent	Which Agent handles Telegram messages by default
Allowed users	Only specified Telegram users can trigger the bot; recommended for production
Allowed groups	Only specified Telegram groups or channels can trigger the bot
Group trigger mode	Can be configured to respond only when the bot is @ mentioned, replied to, or triggered by commands
Streaming output	Controls whether Telegram replies are sent progressively in streaming mode

4. Click Enable, then click Save.
5. After the channel status changes to running, send a test direct message to the Bot in Telegram.

If Flocks replies normally, the Telegram channel is connected successfully.

4. Get a Telegram User ID or Group ID

For production environments, configure user or group allowlists to prevent anyone from triggering Flocks through the Bot.

Common ways to get a user ID:

• Send any message to @userinfobot and check the returned numeric ID.
• Or send a message to @get_id_bot and check the result.

Common ways to get a group chat ID:

1. Add the Bot to the target group chat.
2. Send a test message in the group, then check the received Telegram chat_id in Flocks logs or channel status.
3. Telegram group chat IDs are usually negative numbers. Supergroup IDs typically follow the format -1001234567890.

Group Chat Configuration Notes

Telegram Bots enable privacy mode by default. When privacy mode is enabled, a Bot in a group chat usually receives only:

• Commands starting with /.
• Direct replies to bot messages.
• Service messages, such as member joins, member leaves, and pinned messages.
• Messages in channels where the bot is an administrator.

If you want Flocks to receive regular messages in group chats, choose either of these options:

1. Run /mybots in BotFather, select the target Bot, go to Bot Settings -> Group Privacy, and disable privacy mode.
2. Promote the Bot to group administrator.

After changing privacy mode, remove the Bot from the group and add it again. Telegram caches privacy mode status when the Bot joins a group, so existing membership may not take effect immediately.

To avoid having every regular group message trigger Rex, also configure Flocks to respond only when the bot is @ mentioned, replied to, or triggered by command messages.

Webhook Mode

The Telegram channel can usually run in Polling mode. Polling means Flocks actively pulls updates from Telegram. It does not require a public callback URL and is suitable for local deployments or long-running servers.

If Flocks is deployed on a cloud platform and you want Telegram to push messages proactively, use Webhook mode. This requires:

• A publicly accessible HTTPS Webhook URL.
• A Webhook Secret for verifying Telegram callback requests.
• External requests must be able to reach the Flocks Webhook listener port.

Enter the Webhook URL and Webhook Secret in the Telegram channel in the Flocks WebUI, then save and restart the channel. If Webhook URL is not filled in, the channel usually runs in Polling mode.

Proxy Configuration

If the deployment environment cannot directly access the Telegram Bot API, configure a proxy for the Telegram channel. Common proxy formats:

socks5://127.0.0.1:1080
http://127.0.0.1:7890
https://127.0.0.1:7890

Prefer entering the proxy address in the Telegram channel's dedicated proxy configuration. If no channel-specific proxy is configured, the deployment environment can also use system-level HTTPS_PROXY, HTTP_PROXY, or ALL_PROXY variables to specify an egress proxy.

Result Delivery and Session ID

To proactively send results to Telegram from a Flocks page, Task Center, or Workflow, first establish a conversation binding and obtain the target Session ID.

To obtain the Session ID:

1. Ask Rex in the target Telegram direct message or group chat: What is your session_id?
2. Or send /status to view the currently bound Session, Agent, model, and Telegram conversation information.
3. Use this Session ID in the WebUI, another conversation, Task Center, or Workflow:

Send to session_id: <session_id>: Today's inspection is complete. Two high-risk alerts were found.

Flocks automatically finds the bound Telegram conversation based on the Session ID and sends the message. If /new has been executed in the target Telegram conversation, a new Session is rebound, and subsequent pushes should use the new Session ID.

FAQ

Direct Messages Work, but Group Chats Do Not Respond

Verify the following:

• Whether the Bot has joined the target group chat.
• Whether the group message @ mentioned the bot or replied to a bot message.
• Whether BotFather privacy mode blocked regular group messages.
• Whether the Bot needs to be removed from and re-added to the group to apply the new privacy mode.
• Whether allowed users, allowed groups, or group trigger mode in Flocks restricts the current message.

The Channel Cannot Connect to Telegram

Verify the following:

• Whether Bot Token is correct.
• Whether the deployment environment can access api.telegram.org.
• Whether the proxy address format is correct and the proxy service is available.
• If using Webhook, whether the public HTTPS URL, Webhook Secret, and port forwarding are correct.

How to Distinguish Multiple Bots or Multiple Group Chats

Each Telegram Bot should use a separate Bot Token. If results need to be pushed reliably to a specific Telegram direct message or group chat, use the Session ID returned by Flocks instead of only writing "send to Telegram" in the task description.

References

• Telegram BotFather
• Telegram Bot API

---

Related Resources: Messaging and alerting integrations overview | DingTalk integration | Feishu integration | WeCom integration | Slack integration | WeChat integration | WhatsApp integration | Email integration configuration