翻译与机器人

翻译与机器人页包含两块：翻译 provider（none|http，源/目标语言、端点）与机器人（bot 账号 + HMAC 回调）。翻译配置是存储 + 校验，运行时仍以 IM_TRANSLATE_ENDPOINT 为准；机器人回调是真实投递（HMAC-SHA256 签名，可重试）。

概念​

能力真实行为边界
翻译配置保存 provider/sourceLang/targetLangs/endpoint；provider=mock 已弃用并拒绝运行时读环境变量；未配置时 message.translate 返回 1021
机器人创建创建 bot 账号 + 可选回调配置重复 botId 返回 4xx
机器人回调4 类 bot 事件，HMAC-SHA256（X-IM-* 头），1+2 重试机器人无“直接发送”通道，回复需以同名用户走 Open API publish
Secret 管理只回 ****tail；长度 8–128不返回明文
  • 机器人事件枚举由服务端返回（supportedEvents），控制台不硬编码。
  • 翻译目标语言是数组；保存前校验 provider 与端点，避免无效配置。
  • 机器人回调失败会回写 lastDelivery，可在列表看到最近投递结果。
运行时口径

翻译配置当前不热加载：保存后需以 IM_TRANSLATE_ENDPOINT 环境变量为准并重启；控制台会显示 configured=false 与 runtimeSource=env，不要据此认为已生效。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#ai（tab #ai：翻译与机器人）。
  • 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
  • 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。

步骤​

  1. 配置翻译（可选）

    选择 http provider，填写端点与目标语言；确认环境变量已设置。

  2. 创建机器人

    填写 botId/name，按需配置回调 URL、事件与 secret。

  3. 验证回调

    用机器人会话触发事件，检查投递签名与 lastDelivery。

  4. 上线与轮换

    Secret 轮换时提交新值；停用机器人用 enabled=false，删除用 DELETE。

参数表​

操作方法与路径请求体
翻译读取GET /api/admin/apps/{appkey}/translation—
翻译保存POST /api/admin/apps/{appkey}/translation{enabled,provider,sourceLang?,targetLangs?,endpoint?}
机器人列表GET /api/admin/apps/{appkey}/botsoffset、limit
创建机器人POST /api/admin/apps/{appkey}/bots{botId,name,avatarUrl?,description?,callbackUrl?,events?,secret?,enabled?}
更新机器人POST /api/admin/apps/{appkey}/bots/{botId}{name?,callbackUrl?,events?,secret?,enabled?}
删除机器人DELETE /api/admin/apps/{appkey}/bots/{botId}—

示例​

保存翻译配置并读取运行时口径​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/translation" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"enabled":true,"provider":"http","sourceLang":"zh-CN","targetLangs":["en-US","ja-JP"],"endpoint":"https://translate.example.com/v1"}'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/translation" \
  -H 'X-Admin-Secret: dev-admin'

创建带回调的机器人​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/bots" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"botId":"helper_bot","name":"助手","callbackUrl":"https://bot.example.com/im/callback","events":["bot.message.private","bot.message.group"],"secret":"demo-bot-secret","enabled":true}'

常见问题​

翻译配置保存后为什么不生效？​

运行时仍读 IM_TRANSLATE_ENDPOINT；保存只落配置并校验。设置环境变量并重启后生效。

机器人能主动发消息吗？​

服务端没有 bot 直接发送通道；机器人回调里以 botId 同名用户身份调用 Open API publish。

secret 泄露怎么办？​

提交新的 8–128 字符 secret，旧值立即被替换；同步更新机器人服务。

为什么 provider=mock 被拒？​

mock 已弃用；请使用 http 并配置真实端点，或保持未启用。

相关链接​