Telegram Bot 接入
把 Multica 智能体接入你自己的 Telegram Bot,支持私聊、群聊 @、forum topic 和 /issue。
Multica 使用你通过 Telegram 官方 @BotFather 创建的 Bot。一个 Bot 对应一个 Multica 智能体;需要多个独立 Bot 身份时,为每个智能体分别创建。
开始前
- 连接操作需要工作区 owner 或 admin 权限。
- API 服务器必须能够访问
https://api.telegram.org。 - 你需要 @BotFather 签发的 Bot token;它等同于密码。
连接 Bot
创建 Bot
- 打开 @BotFather,发送
/newbot。 - 设置显示名称和一个以
bot结尾的用户名。 - 复制 HTTP API token。
- 默认保持 Group Privacy 开启,这是可见范围最小的配置:Telegram 只会把命令、明确的 @ 和对 Bot 消息的回复投递给 Bot。也可以关闭它,让 Bot 把群里周围的讨论作为上下文,代价是 Bot 会收到群里的每一条消息,详见Group Privacy 决定 Bot 能看到哪些消息。
不要把 token 发到任务、聊天、日志或代码仓库。若已泄露,请在 @BotFather 中撤销,再用替换后的 token 重新连接。
连接到智能体
- 在 Multica 打开 智能体,选择目标智能体并进入 消息渠道。
- 点击 添加消息渠道,再选择 Telegram。
- 粘贴 Bot token,然后点击 连接。
Multica 会实时请求 Telegram 验证 Bot,检查是否存在与长轮询冲突的 webhook,加密保存 token,并启动一条受监督的 getUpdates 连接。一个 Bot 若已连接到其他智能体或工作区,必须先在原处断开。
第一次使用
成员第一次向 Bot 发消息时,会收到一次性 Multica 账号绑定链接。打开链接,登录同一工作区的 Multica 账号,再回到 Telegram 重新发送消息。链接 15 分钟后过期;再私聊 Bot 即可获取新链接。
在群里,Bot 不会公开发送带凭据性质的绑定链接,只会让发送者先私聊 Bot。
只有当前工作区成员能使用 Bot;每条消息都会重新校验成员身份。
在 Telegram 中交代工作
私聊
直接打开 Bot 发送文字,不需要 @。
群聊与 forum topic
把 Bot 加入群后,@ 它,或直接回复它发过的消息。被接受的消息会保留在持续的 Multica 对话中:普通群聊各自延续一段对话,forum 的每个 topic 分别隔离。
命令
/new创建一个新的空 Multica Chat,并把该 Telegram 对话的后续消息路由到新 Chat;/new <消息>会把消息作为新 Chat 的第一轮。回复其他成员并明确 @ Bot 时,被选中的引用内容仍会附在第一轮中。/clear保留当前 Multica Chat,把新的智能体可见上下文应用到下一条非空消息;/clear <消息>会把消息作为上下文边界后的第一轮,明确选择的回复引用仍会保留。/issue <标题>创建 Multica 任务,后续行作为可选描述;不带标题时返回用法提示。- 群聊支持
/issue@your_bot这种 Telegram 命令后缀。
回复与内容范围
Bot 通过发送并编辑 Telegram 消息来流式展示文字回复,引用触发消息、保留 forum topic,并按 Telegram 长度限制自动分段。智能体工作时,同一条消息下方会列出它当前的步骤(如执行命令、读取文件)和已用时间:私聊显示每一步的具体对象,群聊只显示工作类型。可用 MULTICA_TELEGRAM_TOOL_PROGRESS(off、summary、detail)调整。
图片、文件、视频、语音和音频消息会作为同一对话的附件交给智能体,caption 作为消息正文;智能体生成的文件会在回复之后发回聊天。这两个方向都需要服务端配置对象存储(见下文自托管部分)。
管理连接
打开 设置 → 消息渠道,按平台查看已连接的智能体。点击智能体,进入其详情页的 消息渠道。工作区 owner/admin 可以在这里打开 Bot 的管理菜单,断开连接。断开会停止长轮询和后续回复,但保留 Multica 对话与审计记录。
自托管配置
启动 API 服务器前配置一个长期稳定的 32 字节加密密钥:
MULTICA_TELEGRAM_SECRET_KEY=<base64 编码的 32 字节密钥>可用 openssl rand -base64 32 生成。丢失或轮换此密钥后,已有 Bot token 无法解密,需要逐个重新连接。
绑定链接使用 MULTICA_APP_URL,未设置时回退到 FRONTEND_ORIGIN;生成的地址必须能被成员访问。服务器网络或代理还必须允许 HTTPS 访问 api.telegram.org;Go 会读取标准的 HTTPS_PROXY 和 NO_PROXY 环境变量。
常见问题
- 无法验证 Bot:先检查服务器网络和代理。只有 Telegram 明确拒绝 token 时才需要重新生成。
- webhook 冲突:连接前移除这个 Bot 已有的 webhook;Telegram 不允许 webhook 与
getUpdates同时使用。 - 409 轮询冲突:另一个 Multica 实例或进程正在轮询同一个 Bot。停止另一个消费者,或为不同环境使用不同 Bot。
- 群里不回复:确认 Bot 已入群,并且消息 @ 了它或回复了它的消息。
- 绑定链接过期:重新私聊 Bot,并使用最新链接。
- Bot 不执行:检查智能体是否已归档,以及它使用的运行时是否在线。