xiantong 文档
消息

Telegram

将 Telegram bot 连接到 xiantong，支持 bot token 配对、附件和内联按钮

将 Telegram bot 连接到 xiantong，支持 bot token 配对、附件和内联按钮。

Telegram 集成使用标准 Bot API。您需要通过 @BotFather 创建 bot 并获取 token。无需账号链接；您与自己的 bot 对话，bot 会驱动一个 xiantong 会话。

创建 Bot#

  1. 在 Telegram 中打开 @BotFather 并开始聊天。
  2. 发送 /newbot，按提示输入显示名称和用户名（用户名必须以 bot 结尾，例如 my_xiantong_bot）。
  3. 复制 BotFather 返回的 token，例如：
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-0123456789

请像密码一样保护它，任何持有 token 的人都可以冒充您的 bot。 4. 如需群组支持，可在 BotFather 中关闭 privacy mode。但推荐且默认支持的模式是 1 对 1 私聊。

仅私聊。 网关会在适配器边界拒绝 Telegram 群组和频道消息。即使 bot 被加入群组，也只有与 bot 的私聊能驱动会话。

在应用中连接#

  1. 打开 设置 → 消息。
  2. 点击 Telegram 卡片上的 连接。
  3. 粘贴 bot token 并点击 测试。xiantong 会调用 Telegram getMe 接口；成功后显示 bot 名称和用户名，失败时显示 Telegram 返回的错误。
  4. 点击 保存。token 会保存到工作区密钥链中，Telegram 适配器开始监听。

第一次对话#

  1. 在 Telegram 中打开您的 bot。
  2. 发送 /new。
  3. xiantong 会在当前工作区创建新会话并绑定此聊天。
  4. 继续输入任意内容，消息会转发给 Agent，回复会根据响应模式返回聊天。

附件#

发送照片、文档、语音、视频或音频时，网关会下载文件，将其包装为 FileAttachment，并连同说明文字一起转发到会话。

类型转发形式
Photo图片附件（原始分辨率）
Document带原始 MIME 类型的文件附件
Voice音频附件（ogg/opus）
Video视频附件
Audio音频附件

单个附件硬上限为 20 MB。超出限制或下载失败时，聊天中会收到可见提示。

内联按钮#

Telegram 支持 inline keyboard，因此 /bind 等流程可以渲染为可点击的近期会话列表：

Recent sessions:
[ Morning standup ]
[ Release v0.8.10 ]
[ Debug session ]

点击按钮即可绑定。网关会在处理后清理旧按钮，避免过期按钮堆积。

访问控制#

Telegram bot 可被知道用户名的人访问，因此工作区默认采用 owner-only 策略。只有允许用户列表中的发送者可以运行 /new、/bind、/unbind、/status、/stop 等命令，或把消息路由到已绑定会话。

  • 首次配对规则：在新工作区中首次兑换配对码的 Telegram user_id 会自动成为第一个 owner。
  • 添加更多用户：其他人向 bot 发消息时，会收到“Bot is private”提示，并出现在 设置 → 消息 → 待处理请求 中，可一键允许。
  • 按绑定覆盖：每个会话通道绑定可继承工作区规则、使用自定义允许列表，或对已接受聊天开放。

Webhook 与长轮询#

  • 桌面应用中：适配器使用长轮询，不需要公网 URL。
  • 远程服务器中：适配器使用 webhook。您需要配置公网 URL，例如 https://your-server.tld/telegram/webhook，并在 Telegram 中注册 webhook。

远程部署请参考 远程服务器。

故障排除#

Bot 回复 “No session bound to this chat”#

这是新 bot 的正常情况。发送 /new 创建并绑定会话，或使用 /pair <code> 兑换应用中的配对码。

测试失败并显示 “401 Unauthorized”#

bot token 错误或已被撤销。请在 BotFather 中重新获取 token。

Bot 收到消息但没有响应#

检查配置 bot 的工作区是否是应用当前活动工作区。每个工作区都有自己的消息配置。

群组消息不工作#

这是设计行为。默认只有与 bot 的私聊能驱动会话。

附件过大#

Telegram Bot API 对文件下载有大小限制。请通过应用附件选择器上传，或拆分文件。

上一页消息集成