📘 数字员工开放接口文档

数字员工提供标准化的开放接口，支持企业自有系统与数字员工进行消息交互，包括消息接收与发送。

---

一、消息接收（Webhook 回调）

1. 功能说明

当数字员工收到用户消息后，会自动将消息推送到管理后台配置的 Webhook 接口，由企业自有系统进行处理。

2. 请求方式

• 请求方法：POST
• 请求头：Content-Type: application/json
• 回调地址：管理后台配置的 Webhook URL

3. 消息格式

{
  "from": "user_id_123",
  "to": "staff_id_456",
  "type": "text",
  "secret": "your_secret_key",
  "text": {
    "content": "你好，请帮我查一下订单。"
  },
  "timestamp": 1724400000000
}

参数说明

字段	类型	必填	说明
from	string	是	发送方 ID（如用户ID）
to	string	是	接收方 ID（如数字员工/客服ID）
room	string	否	仅群聊消息有值，表示群聊 ID
type	string	是	消息类型，目前支持 text、后续可扩展 image、file 等
text.content	string	是	消息文本内容
timestamp	number	是	消息时间戳（毫秒）
secret	string	是	消息密钥，用于验证消息来源和防止篡改

---

二、消息发送接口

1. 功能说明

企业系统可以调用此接口，向指定用户或数字员工发送消息。

2. 请求方式

• 请求方法：POST
• 请求路径：/api/v1/send
• 请求头：Content-Type: application/json

3. 请求参数

{
  "from": "staff_id_456",
  "to": "user_id_123",
  "type": "text",
  "text": {
    "content": "您好，订单已经处理完成。"
  },
  "secret": "your_api_secret"
}

参数说明

字段	类型	必填	说明
from	string	是	发送方 ID（数字员工/系统ID）
to	string	是	接收方 ID（用户ID）
type	string	是	消息类型，目前支持 text
text.content	string	是	消息文本内容
timestamp	number	是	消息时间戳（毫秒）
secret	string	是	接口鉴权秘钥（在后台配置）

---

三、签名与安全

1. Webhook 回调：

   • 建议通过 IP 白名单 或 secret 校验。

2. 发送接口：

   • 每个租户配置独立的 secret，调用 /api/v1/send 时需携带。
   • 发送接口中的机器人ID必须与发送方ID一致。

---

四、错误码

状态码	说明
200	成功
400	请求参数错误
401	鉴权失败（secret 无效）
500	服务器内部错误

---

五、交互流程示例

1. 用户发送消息 → 数字员工接收 → 调用 Webhook 转发至企业系统。
2. 企业系统处理业务逻辑后，调用 /api/v1/send → 数字员工将回复推送给用户。