回调说明 - IM 即时通讯

更新时间： 2024/10/31 10:30:19

第三方回调是网易云信一项基于客户需求开放的事件回调功能。即，由客户应用服务器干预事件处理的结果。例如在企业办公场景、接入第三方内容反垃圾服务场景下，需要在发送方发送消息后，不直接投递给接收方，而是先由网易云信服务器向应用服务器发出 POST 请求到应用服务器，根据应用服务器返回的回调结果，决定是否放行。

技术原理

开通第三方回调服务后，网易云信 IM 服务器会在客户端发送消息时，通过向您的应用服务器发送请求，将消息内容和用户信息发往应用服务器。您的应用服务器判断消息是否可以发送，并返回结果，网易云信 IM 服务器再选择是否投递消息。

第三方回调服务仅针对通过 SDK 发送的消息。通过服务端 API 发送的消息，不会触发第三方回调。
如果已开通第三方回调并配置消息相关回调，用户被拉黑后，给对方发消息，也会先进行第三方回调。

开通和配置第三方回调

使用第三方回调前，您需要在网易云信控制台上开通和配置 第三方回调。步骤详情请参考开通和配置第三方回调。

第三方回调概述

请求相关项	说明
请求协议	HTTP/HTTPS，为保证数据安全，建议您使用 HTTPS
请求方式	POST，后面接您在网易云信控制台配置的第三方回调地址（通常为您的应用服务器地址），示例：`POST https://******.com`
消息格式	`application/json; charset=utf-8`
回调地址	对于部分回调类型（如单聊消息和群消息）来说，您可在发送消息时设置环境变量（env），服务器将根据不同的环境回调到不同的回调地址，环境和回调地址的映射关系需要在网易云信控制台配置，具体请参考上述步骤 3
校验方式	网易云信 IM 服务器请求您的应用服务器时，您的应用服务器从请求头（request header）中获取 `CheckSum` 进行安全校验 `CheckSum` = sha1(`AppSecret` + `MD5` + `CurTime`)，其中 `AppSecret`、`MD5` 和 `CurTime` 均为 String 类型在验证数据是否在传输过程中被篡改时，需要计算验证 `MD5` 值是否被修改，以及计算验证 `CheckSum` `AppSecret` 值为您的 AppSecret(与 AppKey 对应)，`MD5` 值为根据请求体（request body）计算出来的值
请求次数	网易云信 IM 服务器只会请求 1 次
请求超时时间	超时时间为 2 秒如果请求失败或者超时，网易云信 IM 服务器会使用网易云信控制台上配置的默认回调结果继续处理业务逻辑您可前往产品功能 > IM 即时通讯 > 基础功能 > 第三方回调 > 子功能配置修改调用失败时的默认策略
消息放行结果	如果不放行，SDK 返回 `403`。如果放行，SDK 返回 `7101`

请求格式

请求头说明

Header 参数	类型	说明
`AppKey`	String	您的应用的 App Key，具体获取方式请参考获取 App Key
`CurTime`	Long	当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数(Long)
`MD5`	String	根据请求中的 request body 计算出来的 MD5 值
`CheckSum`	String	校验值
`Content-Type`	String	请求消息体类型，一般为：`application/json`

MD5 值计算示例：

JavaString requestBody = "{}";
String MD5 = CheckSumBuilder.getMD5(requestBody); //参考 接口概述 -> API checksum 校验 部分

CheckSum 值计算示例：

JavaString AppSecret = "90ud57s6****";
String MD5 = "9894907e4ad9de467809127750******";
String CurTime = "1440570500855"; ////当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数(String)
String CheckSum = CheckSumBuilder.getCheckSum(AppSecret, MD5, CurTime); //参考 接口概述 -> API checksum 校验 部分

请求的 HTTP Body 说明

消息体统一为 JSON 格式，示例：

JSON{
    "body": "Hello",
    "eventType": 1,
    "fromAccount": "000266",
    "fromClientType": "WEB",
    "fromDeviceId": "617715aa8579db03f0cf054c199c****",
    "fromNick": "yj000266",
    "msgTimestamp": "1541560157286",
    "msgType": "TEXT",
    "msgidClient": "",
    "to": "005877",
    "fromClientIp":"115.211.**.**",
    "fromClientPort":"568**"
}

//Json 中的属性请参考具体的回调类型

响应格式说明

第三方回调响应的 Content-Type Header 需要设置为 application/json; charset=utf-8

响应消息体为 JSON 格式，示例：

JSON{
    "errCode":0,
    "responseCode": 20000,
    "modifyResponse": {},
    "callbackExt": "aa"
}

字段	说明
`errCode`	`0`：表示回调通过，允许执行 `1`：表示回调不通过，取消执行。如果设置了合法的自定义错误码（`responseCode`），则发送端会收到自定义错误码，否则发送端会收到 `403` 错误码。
`responseCode`	当 `errCode` 为 `1` 时有效取值范围：`20,000` 至 `20,099` 对于消息类型的第三方回调（`eventType`=`1`、`2`、`6`、`22`、`41`、`72`、`73`、`74`），支持设置为 `200` 的错误码，客户端表现为消息发送成功，其实消息发送失败
`modifyResponse`	对于消息类型的第三方回调有效（`eventType`=`1`、`2`、`6`、`22`、`41`、`72`、`73`、`74`），用于修改消息内容 JSON 格式，支持 `body`、`attach`、`ext`、`pushContent`、`pushPayload`、`pushEnable`、`needPushNick`、`persistEnable`、`skipHistory`（聊天室消息有效）、`roamingEnable`、`historyEnable` 等字段（均可选，若不填则不替换），上述字段的长度限制和正常发消息的限制一样。示例：`{"body":"xxx","attach":"xxx","ext":"123"}` 对登录聊天室的第三方回调有效（`eventType`=`37`） JSON 格式，支持 `tag`、`notifyTargetTag` 字段，进入聊天室时会修改目标用户的 `tag` 和 `notifyTargetTag`，`notifyTargetTag` 是标签表达式。示例：`{"tag":["tag1","tag2","tag3"],"notifyTargetTag":"{\"tag\":\"tag1\"} and {\"tag\":\"tag2\"}"}` 圈组相关：圈组发送消息有效：`body`、`attach`、`ext`、`pushContent`、`pushPayload`、`pushEnable`、`needPushNick`、`historyEnable` 圈组发送系统消息有效：`body`、`attach`、`ext`、`pushContent`、`pushPayload`、`pushEnable`、`needPushNick` 圈组更新消息有效：`body`、`ext`、`msg`、`operatorExt`、`pushContent`、`pushPayload` 圈组更新系统通知消息有效：`body`、`ext`、`msg`、`operatorExt`、`pushContent`、`pushPayload` 效果：消息接收方收到的消息的上述几个字段将会被替换，消息发送方无感知，但是消息发送方的多端设备收到的消息是修改后的，此外，离线消息、漫游消息、云端历史消息，存储的均是修改后的消息内容，因此不管是消息发送方还是接收方，从网易云信服务器获取到的消息均是修改后的消息该 JSON 体中的字段如果超过其长度限制，则该字段的修改无效。
callbackExt	对于消息类型的第三方回调有效（`eventType`=`1`、`2`、`6`、`22`），用于传递第三方回调的扩展信息，最大 1,024 个字符消息发送者和消息接收者均能获取该扩展字段（需要 SDK 版本大于等于 v7.7.0）若 `errCode=1`，则只有消息发送者能获取到该字段只有服务端的 responseCode 返回 200 时，客户端才能读取 callbackExt 的内容。

第三方回调事件类型

IM 登录

eventType	功能	说明
36	登录回调	通过 SDK 登录时，参数检查通过后先回调开发者服务器，回调通过后才允许登录，否则登录失败，不同于其他第三方回调，登录回调失败时返回 302 错误码。

单聊

eventType	功能	说明
1	单聊消息回调	通过 SDK 发送单聊（P2P）消息时，参数检查通过后先回调开发者服务器，回调通过后才发送消息，否则消息发送失败。
35	消息撤回回调	进行点对点消息撤回或者群消息撤回时，参数检查通过后先回调开发者服务器，回调通过后才允许撤回，否则撤回失败。

群聊

eventType	功能	说明
2	群组消息回调	通过 SDK 发送群组消息时，参数检查通过后先回调开发者服务器，回调通过后才发送消息，否则消息发送失败。
7	创建群回调	通过 SDK 创建群组时，参数检查通过后先回调开发者服务器，回调通过后才允许创建，否则创建失败。
8	解散群回调	通过 SDK 解散群组时，参数检查通过后先回调开发者服务器，回调通过后才允许解散，否则解散失败。
9	群邀请回调	通过 SDK 群邀请时，参数检查通过后先回调开发者服务器，回调通过后才允许邀请，否则邀请失败。
10	退群回调	通过 SDK 退群时，参数检查通过后先回调开发者服务器，回调通过后才允许退群，否则退群失败。
11	增加群管理员回调	通过 SDK 增加管理员时，参数检查通过后先回调开发者服务器，回调通过后才允许增加管理员，否则操作失败。
12	取消群管理员回调	通过 SDK 取消管理员时，参数检查通过后先回调开发者服务器，回调通过后才允许取消管理员，否则操作失败。
13	转让群回调	通过 SDK 转让群时，参数检查通过后先回调开发者服务器，回调通过后才允许转让群，否则转让失败。
14	踢人出群回调	通过 SDK 踢人出群时，参数检查通过后先回调开发者服务器，回调通过后才允许踢人出群，否则踢人失败。
15	更新群信息回调	通过 SDK 更新群信息时，参数检查通过后先回调开发者服务器，回调通过后才允许更新群信息，否则更新失败。
16	更新群成员信息回调	通过 SDK 更新群成员信息时，参数检查通过后先回调开发者服务器，回调通过后才允许更新群成员信息，否则更新失败。
17	更新其他人的群成员信息回调	通过 SDK 更新其他人的群成员信息时，参数检查通过后先回调开发者服务器，回调通过后才允许更新其他人的群成员信息，否则更新失败。
18	禁言群成员回调	通过 SDK 禁言群成员时，参数检查通过后先回调开发者服务器，回调通过后才允许禁言群成员，否则操作失败。
19	申请入群回调	通过 SDK 申请入群时，参数检查通过后先回调开发者服务器，回调通过后才允许申请入群，否则申请失败。
22	超大群消息回调	通过 SDK 发送超大群消息时，参数检查通过后先回调开发者服务器，回调通过后才发送消息，否则消息发送失败。
23	超大群群邀请回调	通过 SDK 超大群的群邀请时，参数检查通过后先回调开发者服务器，回调通过后才允许邀请，否则邀请失败。
24	超大群踢人出群回调	通过 SDK 踢人出超大群时，参数检查通过后先回调开发者服务器，回调通过后才允许踢人出群，否则踢人失败。
25	超大群退群回调	通过 SDK 超大群的退群时，参数检查通过后先回调开发者服务器，回调通过后才允许退群，否则退群失败。
26	更新超大群群信息回调	通过 SDK 更新超大群的群信息时，参数检查通过后先回调开发者服务器，回调通过后才允许更新群信息，否则更新失败。
27	更新超大群群成员信息回调	通过 SDK 更新超大群的群成员信息时，参数检查通过后先回调开发者服务器，回调通过后才允许更新群成员信息，否则更新失败。
28	超大群申请入群回调	通过 SDK 申请超大群入群时，参数检查通过后先回调开发者服务器，回调通过后才允许申请入群，否则申请失败。
29	增加超大群管理员回调	通过 SDK 增加管理员时，参数检查通过后先回调开发者服务器，回调通过后才允许增加管理员，否则操作失败。
30	取消超大群管理员回调	通过 SDK 取消管理员时，参数检查通过后先回调开发者服务器，回调通过后才允许取消管理员，否则操作失败。
31	禁言超大群回调	通过 SDK 禁言超大群时，参数检查通过后先回调开发者服务器，回调通过后才允许禁言超大群，否则操作失败。
32	禁言超大群群成员回调	通过 SDK 禁言超大群群成员时，参数检查通过后先回调开发者服务器，回调通过后才允许禁言群成员，否则操作失败。
33	更新超大群里其他人的群成员信息回调	通过 SDK 更新其他人的群成员信息时，参数检查通过后先回调开发者服务器，回调通过后才允许更新其他人的群成员信息，否则更新失败。
34	转让超大群回调	通过 SDK 转让超大群时，参数检查通过后先回调开发者服务器，回调通过后才允许转让群，否则转让失败。

聊天室

eventType	功能	说明
37	聊天室登录回调	通过 SDK 进入聊天室时，参数检查通过后先回调开发者服务器，回调通过后才允许进入聊天室，否则登录失败。若回调通过且传入的参数包含 tag 和 notifyTargetTag 字段，则会使用该值替换该成员的标签信息。
6	聊天室消息回调	通过 SDK 发送聊天室消息时，参数检查通过后先回调开发者服务器，回调通过后才发送消息，否则消息发送失败。

圈组

eventType	功能	说明
40	登录圈组	通过 SDK 登录时，参数检查通过后先回调开发者服务器，回调通过后才允许登录，否则登录失败。
41	发消息	通过 SDK 发送消息时，参数检查通过后先回调开发者服务器，回调通过后才允许发送，否则发送失败。
42	创建服务器	通过 SDK 创建服务器时，参数检查通过后先回调开发者服务器，回调通过后才允许创建，否则创建失败。
43	更新服务器	通过 SDK 更新服务器时，参数检查通过后先回调开发者服务器，回调通过后才允许更新，否则更新失败。
44	删除服务器	通过 SDK 删除服务器时，参数检查通过后先回调开发者服务器，回调通过后才允许删除，否则删除失败。
45	邀请服务器成员	通过 SDK 邀请服务器成员时，参数检查通过后先回调开发者服务器，回调通过后才允许邀请，否则操作失败。
46	接受服务器成员邀请	通过 SDK 接受服务器成员邀请时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
47	拒绝服务器成员邀请	通过 SDK 拒绝服务器成员邀请时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
48	服务器申请	通过 SDK 申请服务器时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
49	接受服务器申请	通过 SDK 接受服务器申请时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
50	拒绝服务器申请	通过 SDK 拒绝服务器申请时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
51	离开服务器	通过 SDK 离开服务器时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
52	踢除服务器成员	通过 SDK 踢除服务器成员时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
53	修改服务器成员信息	通过 SDK 修改服务器成员信息时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
54	修改他人服务器成员信息	通过 SDK 修改他人服务器成员信息时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
55	创建频道	通过 SDK 创建频道时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
56	删除频道	通过 SDK 删除频道时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
57	修改频道信息	通过 SDK 修改频道信息时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
58	修改频道黑白名单身份组	通过 SDK 修改频道黑白名单身份组时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
59	修改频道黑白名单成员	通过 SDK 修改频道黑白名单成员时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
60	创建服务器身份组	通过 SDK 创建服务器身份组时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
61	更新服务器身份组	通过 SDK 更新服务器身份组时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
62	删除服务器身份组	通过 SDK 删除服务器身份组时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
63	创建频道身份组	通过 SDK 创建频道身份组时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
64	修改频道身份组	通过 SDK 修改频道身份组时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
65	删除频道身份组	通过 SDK 删除频道身份组时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
66	在频道下为某个人定制权限	通过 SDK 在频道下为某个人定制权限时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
67	删除频道下某人的定制权限	通过 SDK 删除频道下某人的定制权限时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
68	更新频道下用户定制权限	通过 SDK 更新频道下用户定制权限时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
69	把某些人拉进某服务器身份组	通过 SDK 把某些人拉进某服务器身份组时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
70	将某些人移除某个服务器身份组	通过 SDK 将某些人移除某个服务器身份组时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
71	批量更新服务器身份组	通过 SDK 批量更新服务器身份组时，参数检查通过后先回调开发者服务器，回调通过后才允许操作，否则操作失败。
72	发送自定义系统消息	通过 SDK 发送自定义系统消息时，参数检查通过后先回调开发者服务器，回调通过后才允许发送，否则发送失败。
73	更新消息	通过 SDK 更新消息时，参数检查通过后先回调开发者服务器，回调通过后才允许更新，否则更新失败。
74	更新系统通知	通过 SDK 更新系统通知时，参数检查通过后先回调开发者服务器，回调通过后才允许更新，否则更新失败。

好友关系

eventType	功能	说明
3	用户资料变更回调	通过 SDK 变更用户资料时，参数检查通过后先回调开发者服务器，回调通过后才允许变更，否则变更失败。
4	添加好友回调	通过 SDK 添加好友时，参数检查通过后先回调开发者服务器，回调通过后才允许添加，否则添加失败。
5	删除好友回调	通过 SDK 删除好友时，参数检查通过后先回调开发者服务器，回调通过后才允许删除，否则删除失败。

音视频通话 1.0

eventType	功能	说明
20	音视频呼叫回调	通过 SDK 发起点对点音视频呼叫，参数检查通过后先回调开发者服务器，回调通过后才允许发起呼叫，否则呼叫失败。
21	音视频会议创建回调	通过 SDK 创建音视频多人房间，参数检查通过后先回调开发者服务器，回调通过后才允许创建，否则创建失败。

此文档是否对你有帮助？

有帮助

去反馈

技术原理
开通和配置第三方回调
第三方回调概述
请求格式
请求头说明
请求的 HTTP Body 说明
响应格式说明
第三方回调事件类型
IM 登录
单聊
群聊
聊天室
圈组
好友关系
音视频通话 1.0