Docs

Telegram Bot 接入

把 Multica 智能体接入你自己的 Telegram Bot,支持私聊、群聊 @、forum topic 和 /issue。

Multica 使用你通过 Telegram 官方 @BotFather 创建的 Bot。一个 Bot 对应一个 Multica 智能体;需要多个独立 Bot 身份时,为每个智能体分别创建。

Telegram 集成由社区维护:随每个版本发布,但没有官方支持 SLA。遇到问题请提交 GitHub 任务。

开始前

  • 连接操作需要工作区 owner 或 admin 权限。
  • API 服务器必须能够访问 https://api.telegram.org。
  • 你需要 @BotFather 签发的 Bot token;它等同于密码。

连接 Bot

创建 Bot

  1. 打开 @BotFather,发送 /newbot。
  2. 设置显示名称和一个以 bot 结尾的用户名。
  3. 复制 HTTP API token。
  4. 默认保持 Group Privacy 开启,这是可见范围最小的配置:Telegram 只会把命令、明确的 @ 和对 Bot 消息的回复投递给 Bot。也可以关闭它,让 Bot 把群里周围的讨论作为上下文,代价是 Bot 会收到群里的每一条消息,详见Group Privacy 决定 Bot 能看到哪些消息。

不要把 token 发到任务、聊天、日志或代码仓库。若已泄露,请在 @BotFather 中撤销,再用替换后的 token 重新连接。

连接到智能体

  1. 在 Multica 打开 智能体,选择目标智能体并进入 消息渠道。
  2. 点击 添加消息渠道,再选择 Telegram。
  3. 粘贴 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 不执行:检查智能体是否已归档,以及它使用的运行时是否在线。

接下来

本页目录