机器人管理平台

平台说明

业务项目先在管理后台创建应用并配置“机器人 + 会话”发送目标。公共 API 只会向当前应用已配置且启用的目标发送，显式 ID 不能绕过应用目标关系。

接入步骤

1. 在管理后台创建或确认业务项目。
2. 创建应用，安全保存生成的 AppID 与 AppKey。
3. 在“设置机器人”中选择机器人和允许发送的会话。
4. 服务端安装 SDK，或按本文签名规则调用公共 API。
5. 根据 data.status 和 data.results 处理全部成功、部分成功或失败。

AppKey 只能放在业务服务端的环境变量或安全配置中，禁止写入网页、H5、Flutter 安装包、普通日志或 Git。

健康检查

{
  "code": 0,
  "message": "ok",
  "data": { "service": "bot-management-api", "status": "ok" }
}

消息发送

业务 payload

{
  "channel": "feishu",
  "content": "任务审核完成",
  "bot_ids": [100001, 100002],
  "chat_ids": ["oc_xxx", "oc_yyy"],
  "request_id": "task-reviewed-100001"
}

签名请求体

{
  "appid": "<your-appid>",
  "timestamp": 1760000000,
  "nonce": "unique-random-value",
  "payload": "{\"channel\":\"feishu\",\"content\":\"任务审核完成\"}",
  "signature": "base64-hmac-sha256"
}

必须先把业务对象序列化为紧凑 JSON 字符串，再用同一份字符串签名并放入外层 payload 字段。签名后不能重新格式化或改变字段顺序。

目标路由

单值和对应数组不能同时出现；数组必须包含 1 到 100 项。只要有一个指定 ID 未在最终目标中匹配，整次请求就在发送前返回 400。

响应结果

{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "accepted",
    "channel": "feishu",
    "results": [
      {
        "bot_id": 100001,
        "chat_id": "oc_xxx",
        "message_log_id": 100003,
        "status": "accepted",
        "mock": false,
        "result_message": "feishu sent message_id=...",
        "provider_message_id": "..."
      }
    ]
  }
}

• accepted：全部目标成功。
• partial：部分目标成功，应检查每个 results 项。
• 全部失败：接口返回错误响应。

签名规则

appid + "\n" + timestamp + "\n" + nonce + "\n" + payload

使用 AppKey 计算 HMAC-SHA256，再将结果做标准 Base64 编码。时间戳为 Unix 秒；允许误差 5 分钟；同一 nonce 在有效窗口内只能使用一次。

SDK 示例

提供 Rust、Go、TypeScript 和 Dart / Flutter SDK。SDK统一封装业务 payload 序列化、nonce、时间戳、签名和响应解析。

TypeScript（服务端）

const client = new BotManagementClient({
  baseUrl: 'https://bot.yunxuanwl.cn/api/v1',
  appid: process.env.BOT_MANAGEMENT_APPID!,
  appkey: process.env.BOT_MANAGEMENT_APPKEY!,
})

await client.sendMessage({
  channel: 'feishu',
  content: '任务审核完成',
  bot_ids: [100001, 100002],
  chat_ids: ['oc_xxx'],
  request_id: 'task-reviewed-100001',
})

Go

client, err := botmanagement.New(baseURL, appID, appKey)
result, err := client.SendMessage(ctx, botmanagement.SendMessagePayload{
    Channel: "feishu",
    Content: "任务审核完成",
    BotIDs: []int64{100001, 100002},
    ChatIDs: []string{"oc_xxx"},
})

TypeScript SDK 面向 Node.js 服务端和内部可信工具。Dart SDK适合 Dart 服务端或开发测试；公开 Flutter 客户端不得内置生产 AppKey。

SDK 下载

• Rust SDK
• Go SDK
• TypeScript SDK
• Dart / Flutter SDK
• 全部 SDK 打包
• SHA256 校验文件

错误处理

• 400：payload、渠道、目标筛选或应用发送目标不合法。
• 401：应用不存在、签名错误、时间戳过期或 nonce 重复。
• 403：应用停用或访问策略拒绝。
• 500：数据库、缓存或服务内部错误。

request_id 当前用于业务追踪，不是服务端强制幂等键。遇到网络超时且无法确认发送结果时，不要直接自动重试，应结合业务状态和消息日志判断。

安全边界

• AppKey 只保存在服务端安全配置中。
• 不要记录签名、AppKey、完整敏感消息或外部平台凭证。
• 每次请求生成新的随机 nonce。
• 显式机器人和会话仍必须属于当前应用配置。
• SDK默认不执行不确定结果的自动重试。

AI 接入文档

让 AI 或自动化代理接入时，优先提供下面两个入口：

• llms.txt 文档索引
• 完整 Markdown 接口文档
• OpenAPI 规范

商务合作与产品咨询

如果您希望接入企业机器人消息能力，或就飞书、Telegram 消息集成、产品合作与技术支持进行咨询，欢迎联系我们。