Telegram Bot 详细配置

1. 前置准备

在 Telegram 中搜索 @BotFather，发送 /newbot 创建新 Bot。按提示设置 Bot 名称和用户名。创建完成后 BotFather 会返回 Bot Token（格式：123456:ABC-DEF...）。妥善保存此 Token。

2. 在 Semibot 创建 Bot 实例

进入 Semibot 配置中心 > Bots > 新建，选择 Telegram 类型。填写 Bot Token，选择默认 Agent，配置 allowedChatIds（允许接入的群聊 ID 列表），保存实例。

3. 设置 Webhook

Webhook URL 格式：https://<your-domain>/v1/integrations/telegram/webhook。要求：必须为 HTTPS、公网可访问。可通过 Semibot CLI 设置：semibot gateway webhook-set --provider telegram --url https://<your-domain>/v1/integrations/telegram/webhook。或直接调用 Telegram API：curl -X POST https://api.telegram.org/bot<TOKEN>/setWebhook -d url=https://<your-domain>/v1/integrations/telegram/webhook

4. 隐私模式与 chatId

Telegram Bot 默认开启 Privacy Mode，在群聊中只能收到 @bot 的消息和 /command。如需接收所有群消息，在 BotFather 中发送 /setprivacy 选择 Disable。获取 chat_id：将 Bot 加入群聊后发送一条消息，通过 https://api.telegram.org/bot<TOKEN>/getUpdates 查看 chat.id 字段。将 chat_id 添加到 Bot 实例的 allowedChatIds 配置中。

5. 联调与验证

1. 在 Semibot 中点击「测试」确认出站链路可达。2. 在 Telegram 群中发送消息（或 @bot）。3. 在 Semibot 事件中心确认收到 chat.message.received 事件。4. 在会话详情查看执行记录和回传结果。常见错误：Webhook 未生效（检查 URL 和 HTTPS）、群消息无响应（检查 Privacy Mode 和 allowedChatIds）、Token 无效（重新从 BotFather 获取）。