第三方回调概述

IM 即时通讯

API 参考

群组

高级群

聊天室

圈组

更新时间： 2023/01/06 17:00:20

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

技术原理

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

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

请求相关项	说明
请求协议	HTTP/HTTPS，为保证数据安全，建议您使用 HTTPS
请求方式	POST，后面接您在云信控制台应用界面的功能配置中配置的第三方回调地址（通常为您的应用服务器地址），示例：`POST https://******.com`
消息格式	`application/json; charset=utf-8`
回调地址	对于部分回调类型（如单聊消息和群消息）来说，您可在发送消息时设置环境变量，服务器将根据不同的环境回调到不同的回调地址，环境和回调地址的映射关系配置请联系商务经理
校验方式	云信 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值计算示例：


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

CheckSum值计算示例：


    String 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 格式，示例：

    {
        "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 格式，示例：

    {
        "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` 效果：消息接收方收到的消息的上述几个字段将会被替换，消息发送方无感知，但是消息发送方的多端设备收到的消息是修改后的，此外，离线消息、漫游消息、云端历史消息，存储的均是修改后的消息内容，因此不管是消息发送方还是接收方，从云信服务器获取到的消息均是修改后的消息
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