跳到主要内容

使用 Webhook 接收通知

机器人支持通过 Webhook 的方式将接收到的用户消息或事件回调至应用服务器（App Server）。
该机制便于业务方基于回调内容进行处理，如自动回复、数据分析、消息转发等。

本文档将介绍回调的数据结构、触发条件、签名校验机制以及接入示例，帮助你快速完成机器人 webhook 的接入与处理。

回调方法​

请求方法： POST

数据格式： application/json

即时通讯服务端会在 POST 请求 URL 中添加签名参数，您可通过签名验证调用者身份和数据有效性，详细参见 服务端回调签名。

回调事件类型说明​

回调事件类型及其触发条件请参考文档 回调事件类型列表。

⚠️ 不同事件类型对应的 data 字段结构可能不同，请根据具体类型进行解析和处理。

回调参数说明​

通用字段（适用于所有事件）​

参数路径类型说明
typeString回调事件类型。
timestampNumber触发时间（Unix 毫秒）。
botObject机器人信息对象，包含机器人 ID、昵称、头像、类型及元数据等字段。
bot.userIdString机器人的唯一 ID。
bot.nameString机器人的昵称。
bot.profileUrlString机器人头像的 URL。
bot.typeString机器人的类型。
bot.metadataMap<String, String>自定义元信息，例如创建者、版本等。

message:private 类型​

参数路径类型说明
dataObject消息数据对象，包含发送人、消息内容、时间戳等字段。
data.fromUserIdString发送消息的用户 ID。
data.toUserIdString接收方 ID，通常为机器人自身 ID。
data.objectNameString消息类型，例如文本消息 RC:TxtMsg、图片消息 RC:ImgMsg。
data.contentString发送的消息内容。消息内容结构参考用户内容类消息格式或其他内置消息类型的消息内容格式。
data.channelTypeString会话类型。PERSON（二人会话）、PERSONS（讨论组会话）、GROUP（群组会话）、TEMPGROUP（聊天室会话）、CUSTOMERSERVICE（客服会话）、NOTIFY（系统通知）、MC（应用公众服务）、MP（公众服务）、 ULTRAGROUP（超级群服务）。
data.extraContentString附加内容字段。
data.msgUIDString消息唯一标识。
data.msgTimestampNumber消息发送时间，Unix 毫秒时间戳。

message:group_mentioned 类型​

参数路径类型说明
dataObject消息数据对象，包含发送人、消息内容、时间戳等字段。
data.fromUserIdString发送消息的用户 ID。
data.toUserIdString群聊 ID
data.objectNameString消息类型，例如文本消息 RC:TxtMsg、图片消息 RC:ImgMsg。
data.contentString发送的消息内容。消息内容结构参考用户内容类消息格式或其他内置消息类型的消息内容格式。
data.channelTypeString会话类型。PERSON（二人会话）、PERSONS（讨论组会话）、GROUP（群组会话）、TEMPGROUP（聊天室会话）、CUSTOMERSERVICE（客服会话）、NOTIFY（系统通知）、MC（应用公众服务）、MP（公众服务）、 ULTRAGROUP（超级群服务）。
data.extraContentString附加内容字段。
data.msgUIDString消息唯一标识。
data.msgTimestampNumber消息发送时间，Unix 毫秒时间戳。

回调请求示例​

以下为回调类型为 message:private 的请求示例：

HTTP
POST /webhook?appKey=someappKey&timestamp=1408710653491&nonce=14314&signature=45beb7cc7307889a8e711219a47b7cf6a5b000e8 HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "type": "message:private",
    "timestamp": 1000,
    "bot": {
        "userId": "bo-001",
        "name": "我是AI助手",
        "profileUrl": "https://example.com/profile.png",
        "type": "AI",
        "metadata": {
            "creator": "运营团队",
            "version": "v1.2"
        },
    },
    "data": {
        "fromUserId": "user123",
        "toUserId": "user123",
        "objectName": "RC:TxtMsg",
        "content": "",
        "channelType": "text",
        "extraContent": "",
        "msgUID": "msg001",
        "msgTimestamp": 10000
    }
}

应答说明​

  • 服务端需返回 HTTP 200 状态码表示处理成功。
  • 如在 5 秒内未收到响应，服务端将最多 重试 2 次；连续失败将终止本次推送。
  • 若短时间内出现大规模推送失败，系统将暂停推送 1 分钟后自动恢复尝试。
最后于 更新