Back to Details

telegram-automation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Telegram Automation via Rube MCP

通过Rube MCP实现Telegram自动化

Automate Telegram operations through Composio's Telegram toolkit via Rube MCP.
Toolkit docs: composio.dev/toolkits/telegram
通过Composio的Telegram工具包，借助Rube MCP实现Telegram操作自动化。
工具包文档：composio.dev/toolkits/telegram

Prerequisites

前置条件

  • Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
  • Active Telegram connection via 
    RUBE_MANAGE_CONNECTIONS
    with toolkit 
    telegram
  • Always call 
    RUBE_SEARCH_TOOLS
    first to get current tool schemas
  • Telegram Bot Token required (created via @BotFather)
  • 必须已连接Rube MCP（需具备RUBE_SEARCH_TOOLS权限）
  • 通过
    RUBE_MANAGE_CONNECTIONS
    激活Telegram连接，工具包为
    telegram
  • 请始终先调用
    RUBE_SEARCH_TOOLS
    获取最新的工具架构
  • 需要Telegram Bot Token（通过@BotFather创建）

Setup

设置步骤

Get Rube MCP: Add 
https://rube.app/mcp
as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
  1. Verify Rube MCP is available by confirming 
    RUBE_SEARCH_TOOLS
    responds
  2. Call 
    RUBE_MANAGE_CONNECTIONS
    with toolkit 
    telegram
  3. If connection is not ACTIVE, follow the returned auth link to configure the Telegram bot
  4. Confirm connection status shows ACTIVE before running any workflows
获取Rube MCP：在客户端配置中添加
https://rube.app/mcp
作为MCP服务器。无需API密钥 —— 只需添加端点即可使用。
  1. 确认
    RUBE_SEARCH_TOOLS
    可响应，以此验证Rube MCP是否可用
  2. 调用
    RUBE_MANAGE_CONNECTIONS
    ，指定工具包为
    telegram
  3. 如果连接状态未显示为ACTIVE，请按照返回的授权链接配置Telegram机器人
  4. 在运行任何工作流之前，确认连接状态为ACTIVE

Core Workflows

核心工作流

1. Send Messages

1. 发送消息

When to use: User wants to send text messages to a Telegram chat
Tool sequence:
  1. TELEGRAM_GET_ME
    - Verify bot identity and connection [Prerequisite]
  2. TELEGRAM_GET_CHAT
    - Get chat details and verify access [Optional]
  3. TELEGRAM_SEND_MESSAGE
    - Send a text message [Required]
Key parameters:
  • chat_id
    : Numeric chat ID or channel username (e.g., '@channelname')
  • text
    : Message text content
  • parse_mode
    : 'HTML' or 'MarkdownV2' for formatting
  • disable_notification
    : Send silently without notification sound
  • reply_to_message_id
    : Message ID to reply to
Pitfalls:
  • Bot must be a member of the chat/group to send messages
  • MarkdownV2 requires escaping special characters: 
    _*[]()~>#+-=|{}.!
  • HTML mode supports limited tags: 
    <b>
    , 
    <i>
    , 
    <code>
    , 
    <pre>
    , 
    <a>
  • Messages have a 4096 character limit; split longer content
适用场景：用户需要向Telegram聊天发送文本消息
工具调用流程:
  1. TELEGRAM_GET_ME
    - 验证机器人身份与连接状态 [前置步骤]
  2. TELEGRAM_GET_CHAT
    - 获取聊天详情并验证访问权限 [可选]
  3. TELEGRAM_SEND_MESSAGE
    - 发送文本消息 [必填]
关键参数:
  • chat_id
    : 数字格式的聊天ID或频道用户名（例如：'@channelname'）
  • text
    : 消息文本内容
  • parse_mode
    : 格式类型，可选'HTML'或'MarkdownV2'
  • disable_notification
    : 静默发送，不触发通知音效
  • reply_to_message_id
    : 需回复的消息ID
注意事项:
  • 机器人必须是聊天/群组成员才能发送消息
  • 使用MarkdownV2时需转义特殊字符：
    _*[]()~>#+-=|{}.!
  • HTML模式仅支持有限标签：
    <b>
    , 
    <i>
    , 
    <code>
    , 
    <pre>
    , 
    <a>
  • 单条消息最大字符数为4096，超长内容需拆分发送

2. Send Photos and Documents

2. 发送图片与文档

When to use: User wants to share images or files in a Telegram chat
Tool sequence:
  1. TELEGRAM_SEND_PHOTO
    - Send an image [Optional]
  2. TELEGRAM_SEND_DOCUMENT
    - Send a file/document [Optional]
Key parameters:
  • chat_id
    : Target chat ID
  • photo
    : Photo URL or file_id (for SEND_PHOTO)
  • document
    : Document URL or file_id (for SEND_DOCUMENT)
  • caption
    : Optional caption for the media
Pitfalls:
  • Photo captions have a 1024 character limit
  • Document captions also have a 1024 character limit
  • Files up to 50MB can be sent via bot API
  • Photos are compressed by Telegram; use SEND_DOCUMENT for uncompressed images
适用场景：用户需要在Telegram聊天中分享图片或文件
工具调用流程:
  1. TELEGRAM_SEND_PHOTO
    - 发送图片 [可选]
  2. TELEGRAM_SEND_DOCUMENT
    - 发送文件/文档 [可选]
关键参数:
  • chat_id
    : 目标聊天ID
  • photo
    : 图片URL或file_id（适用于SEND_PHOTO）
  • document
    : 文档URL或file_id（适用于SEND_DOCUMENT）
  • caption
    : 媒体内容的可选说明文字
注意事项:
  • 图片说明文字最大字符数为1024
  • 文档说明文字最大字符数为1024
  • 通过机器人API发送的文件最大为50MB
  • Telegram会压缩图片，如需无损图片请使用SEND_DOCUMENT

3. Manage Chats

3. 管理聊天

When to use: User wants to get chat information or manage chat settings
Tool sequence:
  1. TELEGRAM_GET_CHAT
    - Get detailed chat information [Required]
  2. TELEGRAM_GET_CHAT_ADMINISTRATORS
    - List chat admins [Optional]
  3. TELEGRAM_GET_CHAT_MEMBERS_COUNT
    - Get member count [Optional]
  4. TELEGRAM_EXPORT_CHAT_INVITE_LINK
    - Generate invite link [Optional]
Key parameters:
  • chat_id
    : Target chat ID or username
Pitfalls:
  • Bot must be an administrator to export invite links
  • GET_CHAT returns different fields for private chats vs groups vs channels
  • Member count may be approximate for very large groups
  • Admin list does not include regular members
适用场景：用户需要获取聊天信息或管理聊天设置
工具调用流程:
  1. TELEGRAM_GET_CHAT
    - 获取聊天详细信息 [必填]
  2. TELEGRAM_GET_CHAT_ADMINISTRATORS
    - 列出聊天管理员 [可选]
  3. TELEGRAM_GET_CHAT_MEMBERS_COUNT
    - 获取成员数量 [可选]
  4. TELEGRAM_EXPORT_CHAT_INVITE_LINK
    - 生成邀请链接 [可选]
关键参数:
  • chat_id
    : 目标聊天ID或用户名
注意事项:
  • 机器人必须是管理员才能生成邀请链接
  • GET_CHAT针对私人聊天、群组、频道返回的字段不同
  • 超大群组的成员数量可能为近似值
  • 管理员列表不包含普通成员

4. Edit and Delete Messages

4. 编辑与删除消息

When to use: User wants to modify or remove previously sent messages
Tool sequence:
  1. TELEGRAM_EDIT_MESSAGE
    - Edit a sent message [Optional]
  2. TELEGRAM_DELETE_MESSAGE
    - Delete a message [Optional]
Key parameters:
  • chat_id
    : Chat where the message is located
  • message_id
    : ID of the message to edit or delete
  • text
    : New text content (for edit)
Pitfalls:
  • Bots can only edit their own messages
  • Messages can only be deleted within 48 hours of sending
  • In groups, bots with delete permissions can delete any message
  • Editing a message removes its 'edited' timestamp history
适用场景：用户需要修改或删除已发送的消息
工具调用流程:
  1. TELEGRAM_EDIT_MESSAGE
    - 编辑已发送消息 [可选]
  2. TELEGRAM_DELETE_MESSAGE
    - 删除消息 [可选]
关键参数:
  • chat_id
    : 消息所在的聊天ID
  • message_id
    : 需编辑或删除的消息ID
  • text
    : 编辑后的新文本内容（仅编辑操作）
注意事项:
  • 机器人仅能编辑自己发送的消息
  • 消息仅能在发送后48小时内删除
  • 在群组中，拥有删除权限的机器人可删除任意消息
  • 编辑消息会清除其“已编辑”的时间戳历史

5. Forward Messages and Get Updates

5. 转发消息与获取更新

When to use: User wants to forward messages or retrieve recent updates
Tool sequence:
  1. TELEGRAM_FORWARD_MESSAGE
    - Forward a message to another chat [Optional]
  2. TELEGRAM_GET_UPDATES
    - Get recent bot updates/messages [Optional]
  3. TELEGRAM_GET_CHAT_HISTORY
    - Get chat message history [Optional]
Key parameters:
  • from_chat_id
    : Source chat for forwarding
  • chat_id
    : Destination chat for forwarding
  • message_id
    : Message to forward
  • offset
    : Update offset for GET_UPDATES
  • limit
    : Number of updates to retrieve
Pitfalls:
  • Forwarded messages show the original sender attribution
  • GET_UPDATES returns a limited window of recent updates
  • Chat history access may be limited by bot permissions and chat type
  • Use offset to avoid processing the same update twice
适用场景：用户需要转发消息或获取最新更新
工具调用流程:
  1. TELEGRAM_FORWARD_MESSAGE
    - 将消息转发至其他聊天 [可选]
  2. TELEGRAM_GET_UPDATES
    - 获取机器人的最新更新/消息 [可选]
  3. TELEGRAM_GET_CHAT_HISTORY
    - 获取聊天消息历史 [可选]
关键参数:
  • from_chat_id
    : 转发来源的聊天ID
  • chat_id
    : 转发目标的聊天ID
  • message_id
    : 需转发的消息ID
  • offset
    : GET_UPDATES的更新偏移量
  • limit
    : 需获取的更新数量
注意事项:
  • 转发的消息会显示原发送者信息
  • GET_UPDATES仅返回最近一段时间内的有限更新
  • 聊天历史的访问权限受机器人权限与聊天类型限制
  • 使用offset避免重复处理同一更新

6. Manage Bot Commands

6. 管理机器人命令

When to use: User wants to set or update bot command menu
Tool sequence:
  1. TELEGRAM_SET_MY_COMMANDS
    - Set the bot's command list [Required]
  2. TELEGRAM_ANSWER_CALLBACK_QUERY
    - Respond to inline button presses [Optional]
Key parameters:
  • commands
    : Array of command objects with 
    command
    and 
    description
  • callback_query_id
    : ID of the callback query to answer
Pitfalls:
  • Commands must start with '/' and be lowercase
  • Command descriptions have a 256 character limit
  • Callback queries must be answered within 10 seconds or they expire
  • Setting commands replaces the entire command list
适用场景：用户需要设置或更新机器人的命令菜单
工具调用流程:
  1. TELEGRAM_SET_MY_COMMANDS
    - 设置机器人的命令列表 [必填]
  2. TELEGRAM_ANSWER_CALLBACK_QUERY
    - 响应内联按钮点击事件 [可选]
关键参数:
  • commands
    : 包含
    command
    与
    description
    的命令对象数组
  • callback_query_id
    : 需响应的回调查询ID
注意事项:
  • 命令必须以'/'开头且为小写
  • 命令描述的最大字符数为256
  • 回调查询需在10秒内响应，否则会过期
  • 设置命令会覆盖原有的整个命令列表

Common Patterns

通用模式

Chat ID Resolution

聊天ID获取方式

From username:
1. Use '@username' format as chat_id (for public channels/groups)
2. For private chats, numeric chat_id is required
3. Call GET_CHAT with username to retrieve numeric ID
From GET_UPDATES:
1. Call TELEGRAM_GET_UPDATES
2. Extract chat.id from message objects
3. Use numeric chat_id in subsequent calls
从用户名获取:
1. Use '@username' format as chat_id (for public channels/groups)
2. For private chats, numeric chat_id is required
3. Call GET_CHAT with username to retrieve numeric ID
从GET_UPDATES获取:
1. Call TELEGRAM_GET_UPDATES
2. Extract chat.id from message objects
3. Use numeric chat_id in subsequent calls

Message Formatting

消息格式设置

  • Use 
    parse_mode: 'HTML'
    for 
    <b>bold</b>
    , 
    <i>italic</i>
    , 
    <code>code</code>
  • Use 
    parse_mode: 'MarkdownV2'
    for 
    *bold*
    , 
    _italic_
    , 
    `code`
  • Escape special chars in MarkdownV2: 
    _ * [ ] ( ) ~ > # + - = | { } . !
  • Omit parse_mode for plain text without formatting
  • 使用
    parse_mode: 'HTML'
    实现
    <b>粗体</b>
    、
    <i>斜体</i>
    、
    <code>代码</code>
    格式
  • 使用
    parse_mode: 'MarkdownV2'
    实现
    *粗体*
    、
    _斜体_
    、
    `代码`
    格式
  • MarkdownV2需转义特殊字符：
    _ * [ ] ( ) ~ > # + - = | { } . !
  • 无格式的纯文本可省略parse_mode参数

Known Pitfalls

常见问题

Bot Permissions:
  • Bots must be added to groups/channels to interact
  • Admin permissions needed for: deleting messages, exporting invite links, managing members
  • Bots cannot initiate conversations; users must start them first
Rate Limits:
  • 30 messages per second to the same group
  • 20 messages per minute to the same user in groups
  • Bulk operations should implement delays between calls
  • API returns 429 Too Many Requests when limits are hit
Chat Types:
  • Private chat: One-on-one with the bot
  • Group: Multi-user chat (bot must be added)
  • Supergroup: Enhanced group with admin features
  • Channel: Broadcast-only (bot must be admin to post)
Message Limits:
  • Text messages: 4096 characters max
  • Captions: 1024 characters max
  • File uploads: 50MB max via bot API
  • Inline keyboard buttons: 8 per row
机器人权限:
  • 机器人必须被添加至群组/频道才能进行交互
  • 以下操作需要管理员权限：删除消息、生成邀请链接、管理成员
  • 机器人无法主动发起对话，需用户先发起
速率限制:
  • 向同一群组发送消息的速率限制为30条/秒
  • 向同一用户在群组中发送消息的速率限制为20条/分钟
  • 批量操作需在调用之间添加延迟
  • 超出限制时API会返回429 Too Many Requests错误
聊天类型:
  • 私人聊天：与机器人一对一对话
  • 群组：多用户聊天（需添加机器人）
  • 超级群组：具备管理员功能的增强型群组
  • 频道：仅广播模式（机器人需为管理员才能发布内容）
消息限制:
  • 文本消息：最大4096字符
  • 说明文字：最大1024字符
  • 文件上传：机器人API支持最大50MB
  • 内联键盘按钮：每行最多8个

Quick Reference

快速参考

TaskTool SlugKey Params
Verify botTELEGRAM_GET_ME(none)
Send messageTELEGRAM_SEND_MESSAGEchat_id, text, parse_mode
Send photoTELEGRAM_SEND_PHOTOchat_id, photo, caption
Send documentTELEGRAM_SEND_DOCUMENTchat_id, document, caption
Edit messageTELEGRAM_EDIT_MESSAGEchat_id, message_id, text
Delete messageTELEGRAM_DELETE_MESSAGEchat_id, message_id
Forward messageTELEGRAM_FORWARD_MESSAGEchat_id, from_chat_id, message_id
Get chat infoTELEGRAM_GET_CHATchat_id
Get chat adminsTELEGRAM_GET_CHAT_ADMINISTRATORSchat_id
Get member countTELEGRAM_GET_CHAT_MEMBERS_COUNTchat_id
Export invite linkTELEGRAM_EXPORT_CHAT_INVITE_LINKchat_id
Get updatesTELEGRAM_GET_UPDATESoffset, limit
Get chat historyTELEGRAM_GET_CHAT_HISTORYchat_id
Set bot commandsTELEGRAM_SET_MY_COMMANDScommands
Answer callbackTELEGRAM_ANSWER_CALLBACK_QUERYcallback_query_id
Powered by Composio
任务工具标识关键参数
验证机器人TELEGRAM_GET_ME(none)
发送消息TELEGRAM_SEND_MESSAGEchat_id, text, parse_mode
发送图片TELEGRAM_SEND_PHOTOchat_id, photo, caption
发送文档TELEGRAM_SEND_DOCUMENTchat_id, document, caption
编辑消息TELEGRAM_EDIT_MESSAGEchat_id, message_id, text
删除消息TELEGRAM_DELETE_MESSAGEchat_id, message_id
转发消息TELEGRAM_FORWARD_MESSAGEchat_id, from_chat_id, message_id
获取聊天信息TELEGRAM_GET_CHATchat_id
获取聊天管理员TELEGRAM_GET_CHAT_ADMINISTRATORSchat_id
获取成员数量TELEGRAM_GET_CHAT_MEMBERS_COUNTchat_id
生成邀请链接TELEGRAM_EXPORT_CHAT_INVITE_LINKchat_id
获取更新TELEGRAM_GET_UPDATESoffset, limit
获取聊天历史TELEGRAM_GET_CHAT_HISTORYchat_id
设置机器人命令TELEGRAM_SET_MY_COMMANDScommands
响应回调查询TELEGRAM_ANSWER_CALLBACK_QUERYcallback_query_id
由 Composio 提供支持