机器人服务

Bot Service 用于把 Telegram 等消息工作流接入 Open4X。它支持 bot webhook、聊天和消息查看、widget 聊天、交互事件、文件转发和回复流程。

核心路由

/v1/apps/bot
/v1/apps/bot/webhook
/v1/apps/bot/widget
/v1/apps/bot/ws

控制台也提供 Bot 服务配置和 webhook 状态检查。

服务配置

示例：

{
  "service_id": "bot",
  "alias": "alerts",
  "config": {
    "platform": "telegram",
    "webhook_url": "https://example.com/internal/bot-events",
    "bot_token": "123456:ABC..."
  },
  "status": "active"
}

配置 Telegram Bot Token 后，Open4X 可以把 Telegram webhook 绑定到网关，并把事件转发给你的业务接口。

常用能力

能力	路由
聊天列表和消息历史	/v1/apps/bot/chats
交互事件	/v1/apps/bot/interactions
回复消息	/v1/apps/bot/messages/reply
发送文件	/v1/apps/bot/messages/send-file
Widget 聊天	/v1/apps/bot/widget/*

可嵌入 Widget SDK

Widget SDK 对外提供 canonical 浏览器 API window.Open4XWidget：

window.Open4XWidget.init(sessionToken)
window.Open4XWidget.open()

品牌迁移期间，window.OpenEdgeWidget 仍作为兼容别名保留。Widget session token 是短期令牌，不能在浏览器代码中改用平台 API Key。

完整的短期会话、WebSocket、增量事件游标、HMAC 签名和 staging 接入示例见 Widget Service 协议。

鉴权

大多数 Bot API 需要登录态或 API Key。

API Key 建议 scope：

bot:send

当前 Bot 路由统一要求 bot:send；不会因为只有 bot:read 就允许读取。

运维建议

• 通过控制台配置 bot token，不要写入代码。
• 日志中避免保存包含私人信息的完整消息正文。
• 使用控制台 webhook status 检查 Telegram 是否绑定到正确网关 URL。