HTTP 回调事件

更新时间 2023/05/04 06:53:54

即时通讯 IM 支持 HTTP 回调（Webhook）。对你的即时通讯应用设置 HTTP 回调后，当指定事件发生时，即时通讯 IM 服务器会在事件发生时通过 HTTP POST 请求向你的应用服务器发送请求，请求体为 JSON 格式的字符串，字符集为 UTF-8。

本文介绍即时通讯 IM 支持的发送后回调事件。

用户登录登出事件

当即时通讯 app 中有用户登录登出时，即时通讯 IM 服务端会向你的应用服务器发送回调事件，通知你当前的操作。

用户登录

当本地有用户登录时，即时通讯 IM 服务会向你的应用服务器发送回调事件，示例如下：

{
    "callId":"XXXX#XXXXe393c568-5ae5-4a0e-8a2c-008b52b49eed",
    "reason":"login",
    "security":"XXXXae2eXXXXced298883a0cf06d41b9",
    "os":"ios",
    "ip":"************",
    "host":"*******",
    "appkey":"XXXX#XXXX",
    "user":"XXXX#XXXXtstXXXX/ios_XXXX01fd-b5a4-84d5-ebeb-bf10XXXX0442",
    "version":"3.8.9.1",
    "timestamp":1642585154644,
    "status":"online"
}

字段	数据类型	描述
`callId`	String	回调 ID，即每条 HTTP 回调的唯一标识。该字段值的格式为 `{appKey}_{uuid}`，其中 `uuid` 为随机生成。
`reason`	Object	触发回调的原因。`login` 表示用户登录。
`security`	String	消息回调请求中的签名，用于确认该回调是否来自即时通讯 IM 服务器。该签名使用 MD5 算法对 `{callId}+{secret}+{timestamp}` 进行加密，其中 `secret` 详见声网控制台的发送后回调规则。
`os`	String	设备类型，指设备的操作系统，包含 `ios`、`android`、`linux`、`win` 及 `other`。
`ip`	String	用户登录的 IP 地址。
`host`	String	即时通讯 IM 服务分配的 RESTful API 请求地址域名。
`appkey`	String	即时通讯 IM 服务分配给每个 app 的唯一标识。
`user`	String	登录用户的识别号，格式为 `{appKey}/{OS}_{deviceId}`。
`version`	String	SDK 版本号。
`timestamp`	Number	即时通讯 IM 服务器收到登录请求的 Unix 时间戳，单位为毫秒。
`status`	String	用户当前状态： `online`：用户在线。 `offline`：用户离线。

用户登出

当本地有用户登出时，即时通讯 IM 服务会向你的应用服务器发送回调事件，示例如下：

{
    "callId":"XXXX#XXXX25b54a81-1376-4669-bb3d-178339a8f11b",
    "reason":"logout",
    "security":"XXXXd77eXXXXf26801627fdaadca987e",
    "os":"ios",
    "ip":"223.71.97.198:4XXXX",
    "host":"********",
    "appkey":"XXXX#XXXX",
    "user":"XXXX#XXXXtstXXXX/ios_XXXX0737-db3a-d2b5-da18-b604XXXX195b",
    "version":"3.8.9.1",
    "timestamp":1642648914742,
    "status":"offline"
}

字段	数据类型	描述
`callId`	String	回调 ID，即每条 HTTP 回调的唯一标识。该字段值的格式为 `{appKey}_{uuid}`，其中 `uuid` 为随机生成。
`reason`	Object	触发回调的原因。`logout` 表示用户登出。
`security`	String	消息回调请求中的签名，用于确认该回调是否来自即时通讯 IM 服务器。该签名使用 MD5 算法对 `{callId}+{secret}+{timestamp}` 进行加密，其中 `secret` 详见声网控制台的发送后回调规则。
`os`	String	设备类型，指设备的操作系统，包含 `ios`、`android`、`linux`、`win` 及 `other`。
`ip`	String	用户登出的 IP 地址。
`host`	String	即时通讯 IM 服务分配的 RESTful API 请求地址域名。
`appkey`	String	即时通讯 IM 服务分配给每个 app 的唯一标识。
`user`	String	登出用户的识别号，格式为 `{appKey}/{OS}_{deviceId}`。
`version`	String	SDK 版本号。
`timestamp`	Number	即时通讯 IM 服务器收到登出请求的 Unix 时间戳，单位为毫秒。
`status`	String	用户当前状态： `online`：用户在线。 `offline`：用户离线。

用户因被其他设备踢掉而登出

当本地有用户因被其他设备踢掉而登出时，即时通讯 IM 服务会向你的应用服务器发送回调事件，示例如下：

{
    "callId":"XXXX#XXXX260ae3eb-ba31-4f01-9a62-8b3b05f3a16c",
    "reason":"replaced",
    "security":"XXXX00b1XXXX4fe76dbfdc664cbaa76b",
    "os":"ios","ip":"223.71.97.198:52709",
    "host":"msync@ebs-ali-beijing-msync40",
    "appkey":"XXXX#XXXX",
    "user":"XXXX#XXXXtst01XXXX/ios_XXXX01fd-b5a4-84d5-ebeb-bf10XXXX0442",
    "version":"3.8.9.1",
    "timestamp":1642648955563,
    "status":"offline"
}

字段	数据类型	描述
`callId`	String	回调 ID，即每条 HTTP 回调的唯一标识。该字段的值为 `{appKey}_{uuid}`，其中 `uuid` 为随机生成。
`reason`	Object	触发回调的原因。`replaced` 表示用户被其他设备踢掉而登出。
`security`	String	消息回调请求中的签名，用于确认该回调是否来自即时通讯 IM 服务器。该签名使用 MD5 算法对 `{callId}+{secret}+{timestamp}` 进行加密，其中 `secret` 详见声网控制台的发送后回调规则。
`os`	String	设备类型，指设备的操作系统，包含 `ios`、`android`、`linux`、`win` 及 `other`。
`ip`	String	用户登出的 IP 地址。
`host`	String	即时通讯 IM 服务分配的 RESTful API 请求地址域名。
`appkey`	String	即时通讯 IM 服务分配给每个 app 的唯一标识。
`user`	String	登出用户的识别号，格式为 `{appKey}/{OS}_{deviceId}`。
`version`	String	SDK 版本号。
`timestamp`	Number	即时通讯 IM 服务器收到登出请求的 Unix 时间戳，单位为毫秒。
`status`	String	用户当前状态： `online`：用户在线。 `offline`：用户离线。

发送消息事件

当即时通讯 app 中有用户发送消息时，无论是单聊、群聊或聊天室，即时通讯 IM 服务均会向你的应用服务端发送回调事件。示例如下：

{
    "callId":"{appkey}_{uuid}",
    "eventType":"chat_offline",
    "timestamp":1600060847294,
    "chat_type":"groupchat", 
    "group_id":"1693XXXX238921545",
    "from":"user1",
    "to":"user2",
    "msg_id":"8924XXXX42322",
    "payload":{
    // 具体的回调消息内容
    },
    "securityVersion":"1.0.0",
    "security":"XXXX2c39XXXX9e7abc83958bcc3156d3"
}

参数	类型	描述
`callId`	String	回调 ID，即每条 HTTP 回调的唯一标识。该字段值的格式为 `{appKey}_{uuid}`，其中 `uuid` 为随机生成。
`eventType`	String	消息类型： `chat`: 上行消息，即消息服务器要下发给终端设备的消息。 `chat_offline`: 离线消息，即因用户离线消息服务器未下发的消息。
`timestamp`	Number	即时通讯 IM 服务器接收到此消息的 Unix 时间戳，单位为毫秒。
`chat_type`	String	会话类型： `chat`: 单聊 `groupchat`: 群组和聊天室 `notify`：通知回调包含了子区（Thread）和 Reaction 的回调，需要结合 payload 中的 `type` 字段确定具体类型。
`group_id`	String	消息回调所发生的群组或聊天室的 ID。当 `chat_type` 为 `groupchat` 时，才会有该参数。
`from`	String	消息的发送方。
`to`	String	消息的接收方。
`msg_id`	String	该回调事件的消息 ID，与用户发送消息时的 `msg_id` 一致。
`payload`	Object	消息回调事件的详细内容。根据用户在单聊、群聊和聊天室中发送的消息类型，回调事件中的 `payload` 包含的字段不同，具体示例及参数解释详见下文，也可参见历史消息记录。
`securityVersion`	String	预留参数。
`security`	String	消息回调请求中的签名，用于确认该回调是否来自即时通讯 IM 服务器。该签名使用 MD5 算法对 `{callId}+{secret}+{timestamp}` 进行加密，其中 `secret` 详见声网控制台的发送后回调规则。
`appkey`	String	即时通讯 IM 服务分配给每个 app 的唯一标识。
`host`	String	即时通讯 IM 分配的 RESTful API 请求地址域名。