服务端
API 参考
圈组

回调说明

更新时间: 2024/05/24 10:32:25

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

技术原理

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

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

开通和配置第三方回调

使用第三方回调前,需开通和配置该服务:

  1. 在控制台首页应用管理中选择应用,然后单击 IM 即时通讯下的功能配置按钮进入功能配置页。

    image.png
  2. 顶部选择基础功能页签,在第三方回调中配置第三方回调地址(通常为您的应用服务器地址),示例:POST https://******.com ,单击保存完成配置。

  3. (可选)如需多环境配置,请跳转至自定义抄送 / 第三方回调配置进行配置。

    1. 自定义抄送/第三方回调配置中单击右侧的添加按钮。

      添加.png

    2. 填写需要映射的环境名称和第三方回调地址。

      映射环境和回调地址.png

  4. 单击子功能配置,配置接口调用失败时的默认策略、第三方回调超时时间及第三方服务的校验范围。

    • 接口调用失败时的默认策略:可设置第三方回调超时或其他原因失败后期望的处理策略,默认放行。

    • 第三方回调超时时间:可设置第三方回调的超时时间,默认 2S。如果请求失败或者超时,云信 IM 服务器会使用网易云信控制台上配置的默认回调结果(放行/不放行)继续处理业务逻辑。

    • 第三方服务的校验范围:勾选需要第三方服务的配置项。群组、超大群以及圈组模块下可单独选择。

    聊天室消息的回调不在此处开通,需要在聊天室模块中单独开通。在 IM 功能配置页顶部选择聊天室页签,开通聊天室消息回调功能。

第三方回调概述

请求相关项
说明
请求协议 HTTP/HTTPS,为保证数据安全,建议您使用 HTTPS
请求方式 POST,后面接您在云信控制台配置的第三方回调地址(通常为您的应用服务器地址),示例:POST https://******.com
消息格式 application/json; charset=utf-8
回调地址 对于部分回调类型(如单聊消息和群消息)来说,您可在发送消息时设置环境变量(env),服务器将根据不同的环境回调到不同的回调地址,环境和回调地址的映射关系需要在控制台配置,具体请参考上述步骤 3
校验方式
云信 IM 服务器请求您的应用服务器时,您的应用服务器从请求头 (request header)中获取 CheckSum 进行安全校验
  • CheckSum = sha1(AppSecret + MD5 + CurTime), 其中AppSecretMD5CurTime 均为 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值计算示例:

    java
        String requestBody = "{}";
        String MD5 = CheckSumBuilder.getMD5(requestBody); //参考 接口概述 -> API checksum校验 部分
    
    
  • CheckSum值计算示例:

    java
        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 格式,示例:

java    {
        "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 格式,示例:

java    {
        "errCode":0,
        "responseCode": 20000,
        "modifyResponse": {},
        "callbackExt": "aa"
    }
字段
说明
errCode
  • 0:表示回调通过,允许执行
  • 1:表示回调不通过,取消执行。如果设置了合法的自定义错误码(responseCode),则发送端会收到自定义错误码,否则发送端会收到 403 错误码。
responseCode
  • errCode1 时有效
  • 取值范围: 20,00020,099
  • 对于消息类型的第三方回调(eventType=1262241727374),支持设置为 200 的错误码,客户端表现为消息发送成功,其实消息发送失败
modifyResponse
  • 对于消息类型的第三方回调有效(eventType=1262241727374),用于修改消息内容
  • JSON 格式,支持 bodyattachextpushContentpushPayloadpushEnableneedPushNickpersistEnableskipHistory(聊天室消息有效)、roamingEnablehistoryEnable等字段(均可选,若不填则不替换),上述字段的长度限制和正常发消息的限制一样。示例:{"body":"xxx","attach":"xxx","ext":"123"}
  • 对登录聊天室的第三方回调有效(eventType=37
  • JSON 格式,支持 tagnotifyTargetTag字段,进入聊天室时会修改目标用户的 tagnotifyTargetTagnotifyTargetTag标签表达式。示例:{"tag":["tag1","tag2","tag3"],"notifyTargetTag":"{\"tag\":\"tag1\"} and {\"tag\":\"tag2\"}"}
  • 圈组相关:
    • 圈组发送消息有效:bodyattachextpushContentpushPayloadpushEnableneedPushNickhistoryEnable
    • 圈组发送系统消息有效:bodyattachextpushContentpushPayloadpushEnableneedPushNick
    • 圈组更新消息有效:bodyextmsgoperatorExtpushContentpushPayload
    • 圈组更新系统通知消息有效:bodyextmsgoperatorExtpushContentpushPayload
  • 效果:消息接收方收到的消息的上述几个字段将会被替换,消息发送方无感知,但是消息发送方的多端设备收到的消息是修改后的,此外,离线消息、漫游消息、云端历史消息,存储的均是修改后的消息内容,因此不管是消息发送方还是接收方,从云信服务器获取到的消息均是修改后的消息
该 JSON 体中的字段如果超过其长度限制,则该字段的修改无效。
callbackExt
  • 对于消息类型的第三方回调有效(eventType=12622),用于传递第三方回调的扩展信息,最大 1,024 个字符
  • 消息发送者和消息接收者均能获取该扩展字段(需要 SDK 版本大于等于 v7.7.0)
  • errCode=1,则只有消息发送者能获取到该字段
回调服务请求客户的接口调用成功时(即 HTTP 请求的 code 码返回 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