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；它等同于密码。
1. 创建 Bot
- 打开 @BotFather，发送
/newbot。 - 设置显示名称和一个以
bot结尾的用户名。 - 复制 HTTP API token。
- 默认保持 Group Privacy 开启，这是可见范围最小的配置：Telegram 只会把命令、明确的 @ 和对 Bot 消息的回复投递给 Bot。关闭它是可选项，能让 Bot 把群里周围的讨论作为上下文，代价是 Bot 会收到群里的每一条消息，详见群聊与 forum topic。
不要把 token 发到任务、聊天、日志或代码仓库。若已泄露，请在 @BotFather 中撤销，再用替换后的 token 重新连接。
2. 连接到智能体
- 在 Multica 打开 智能体，选择目标智能体并进入 集成。
- 点击 连接 Telegram。
- 粘贴 Bot token，然后点击 连接。
Multica 会实时请求 Telegram 验证 Bot，检查是否存在与长轮询冲突的 webhook，加密保存 token，并启动一条受监督的 getUpdates 连接。一个 Bot 若已连接到其他智能体或工作区，必须先在原处断开。
首次使用与账号绑定
成员第一次向 Bot 发消息时，会收到一次性 Multica 账号绑定链接。打开链接，登录同一工作区的 Multica 账号，再回到 Telegram 重新发送消息。链接 15 分钟后过期；再私聊 Bot 即可获取新链接。
在群里，Bot 不会公开发送带凭据性质的绑定链接，只会让发送者先私聊 Bot。
只有当前工作区成员能使用 Bot；每条消息都会重新校验成员身份。
使用 Bot
私聊
直接打开 Bot 发送文字，不需要 @。
群聊与 forum topic
把 Bot 加入群后，@它，或直接回复它发过的消息。被接受的消息会保留在持续的 Multica 对话中。未明确发给 Bot 的群消息本身不会开启对话，也不会单独形成一轮，但会被暂存在一个很小的内存缓冲里：每个群（或每个 forum topic）保留 Bot 收到的最近 10 条，服务器重启即清空。之后当有成员通过 @ 或回复 Bot 的消息向它发出指令时，这些暂存消息会作为只读上下文附在该轮指令之前，并随这一轮一起保存进对话记录。缓冲里的图片或文件在上下文中只显示为 [Image] 之类的标记和 caption，文件本身不会被获取。/new 开启的新对话不带这段上下文。缓冲里有什么取决于 Telegram 投递了什么：Group Privacy 开启时只有命令、明确的 @ 和对 Bot 的回复，所以上下文里只有之前明确发给它的消息。想让它看到普通群聊，请在 @BotFather 里关闭 Group Privacy，再把 Bot 移出群重新加入，此后 Bot 会收到群里的每一条消息。被设为群管理员的 Bot 无论隐私设置如何都会收到全部消息，因此不改 @BotFather 也会把普通群聊纳入上下文。回复其他成员的消息时必须同时 @ Bot，只有这种情况下，被引用消息的发送者及文字（或 caption）才会随新指令进入上下文；发给 Bot 的回复所引用的消息若带图片或文件，该文件也会一并附上，无论发送者是谁；只回复成员而不 @ 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 长度限制自动分段。最终回复在进程内异步投递。正常情况下，某个聊天的退避等待不会占用 worker；缓存达到容量上限并压缩退避状态时，同一 Bot installation 下的其他聊天可能被保守延迟。终态队列有固定容量，超限运行会被明确拒绝并记录错误；队列不会跨服务重启恢复。
图片、文件、视频、语音和音频消息会作为同一对话的附件交给智能体，caption 作为消息正文。回复一条带有这类内容的消息（私聊，或在群里向 Bot 发出指令时，无论发送者是谁）会把该消息作为引用附在你的指令前，并把它的文件一并交给智能体，这样你可以指定之前的某张图片或某段视频。Telegram 只允许 Bot 下载 20 MB 以内的文件；文件无法获取时（太大或下载失败），Bot 会告诉你，智能体只会看到一个占位符。智能体生成的文件会在回复之后作为单独的消息发回聊天：10 MB 以内的图片内联显示，其余 50 MB 以内的文件以文件形式到达；无法确认送达时 Bot 会说明，文件仍保留在 Multica 的回复附件里。这两个方向都需要服务端配置对象存储（见下文自托管部分）；未配置时，Bot 对媒体消息回复不支持提示，智能体也会被告知无法发送文件。贴纸、位置、投票等非文件消息在私聊中以及群里明确 @ Bot 时会收到同样的提示，群里未 @ 的此类消息保持静默。
管理与断开
在 设置 → 消息渠道 → Telegram 查看所有已连接 Bot。owner 和 admin 可以断开。断开会停止长轮询和后续回复，但保留 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 不执行：检查智能体是否已归档，以及它使用的运行时是否在线。