• UIKit
  • SDK
  • 服务端 API
Chat/
服务端 API/
服务端回调/
服务端 API
  • UserSig(Token) 鉴权
  • RESTful API
    • RESTful API 概述
    • RESTful API 列表
    • 消息相关
      • 发送消息
        • 向单个用户发送单聊消息
        • 向多个用户发送单聊消息
        • 群内发送普通消息
        • 群内发送系统消息
        • 直播群广播消息
        • 导入单聊消息
        • 导入群消息
      • 历史消息
        • 修改单聊历史消息
        • 修改群聊历史消息
        • 拉取单聊历史消息
        • 拉取群聊历史消息
      • 删除消息
        • 删除指定用户发送的消息
      • 撤回消息
        • 撤回单聊消息
        • 撤回群消息
      • 已读回执
        • 设置单聊消息已读
        • 拉取群消息已读回执详情
        • 拉取群消息已读回执
      • 消息扩展
        • 拉取单聊消息扩展
        • 设置单聊消息扩展
        • 拉取群消息扩展
        • 设置群消息扩展
      • 推送给所有用户
        • 全员推送接口
        • 推送给所有用户
        • 设置应用属性名称
        • 获取应用属性名称
        • 获取用户属性
        • 设置用户属性
        • 删除用户属性
        • 获取用户标签
        • 添加用户标签
        • 删除用户标签
        • 删除用户所有标签
    • 会话相关
      • 会话列表
        • 拉取会话列表
      • 未读会话数
        • 设置成员的未读消息数
        • 查询未读单聊消息数
      • 删除会话
        • 删除会话
      • 会话组标签
        • 创建会话组数据
        • 更新会话组数据
        • 删除会话组数据
        • 创建或更新会话标记数据
        • 查找会话组标记
        • 拉取会话组标记数据
    • 群相关
      • 群组管理
        • 获取应用内所有群组
        • 创建群组
        • 解散群组
        • 获取用户已加入的群
      • 群资料
        • 获取群资料
        • 修改群资料
        • 导入群资料
      • 群成员管理
        • 添加群成员
        • 删除群成员
        • 封禁群成员
        • 解禁群成员
        • 批量禁言和取消禁言
        • 获取被禁言群成员列表
        • 变更群主
        • 查询用户在群组中的身份
        • 导入群成员
      • 群成员信息
        • 获取群成员资料
        • 修改群成员资料
        • Getting Specified Group Member Profiles
      • 群自定义属性
        • 获取群自定义属性
        • 修改群自定义属性
        • 清空群自定义属性
        • 重置群自定义属性
        • 删除群自定义属性
      • 直播群管理
        • 获取直播群在线人数
        • 获取直播群在线成员列表
        • 设置直播群成员标记
        • 获取封禁群成员列表
      • 社群管理
        • 创建话题
        • 删除话题
        • 获取话题资料
        • 修改话题资料
        • 导入话题资料
      • 群计数器
        • 获取群计数器
        • 更新群计数器
        • 删除群计数器
    • 用户管理
      • 账号管理
        • 导入单个账号
        • 导入多账号
        • 删除账号
        • 查询账号
      • 用户信息
        • 设置资料
        • 拉取资料
      • 用户状态
        • 账号登录状态失效
        • 查询账号在线状态
      • 好友管理
        • 添加好友
        • 导入好友
        • 更新好友
        • 删除好友
        • 删除所有好友
        • 验证好友
        • 拉取好友
        • 拉取指定好友
      • 好友列表
        • 添加列表
        • 删除列表
        • 拉取列表
      • 黑名单
        • 拉黑用户
        • 将用户移出黑名单
        • 拉取黑名单
        • 验证黑名单中的用户
    • 全员禁言管理
      • 设置全员禁言
      • 查询全员禁言
    • 运维管理
      • 拉取运维数据
      • 下载最新消息
      • 获取服务器 IP 地址
    • 智能机器人
      • 拉取智能机器人账号
      • 创建智能机器人账号
      • 删除智能机器人账号
    • 全员/标签推送
      • 发起全员/标签推送
      • 获取应用属性名称
      • 设置应用属性名称
      • 获取用户属性
      • 设置用户属性
      • 删除用户属性
      • 获取用户标签
      • 添加用户标签
      • 删除用户标签
      • 清空用户标签
      • 推送撤回
  • 服务端回调
    • 回调概述
    • 回调命令列表
    • 运维管理回调
      • 接口超频告警回调
    • 在线状态回调
      • 状态变更回调
    • 关系链回调
      • 更新资料之后
      • 添加好友之前
      • 添加好友回应之前
      • 添加好友之后
      • 删除好友之后
      • 将用户加入黑名单后
      • 将用户移出黑名单后
    • 单聊消息回调
      • 发送单聊消息之前
      • 发送单聊消息之后
      • 设置单聊消息已读之后
      • 撤回单聊消息之后
    • 群回调
      • 创建群组之前
      • 创建群组之后
      • 申请入群之前
      • 拉人入群之前
      • 用户入群之后
      • 成员退群之后
      • 发送群消息之前
      • 发送群消息后
      • 群组满员之后
      • 群组解散之后
      • 群组资料变动之后
      • 撤回群消息之后回调
      • 直播群成员在线和离线状态回调
      • 发送群消息异常回调
      • 创建话题之前
      • 创建话题之后
      • 删除话题后
      • 话题信息变更回调
      • 群成员资料变更后回调
      • 群属性变更后回调
      • 已读回执后回调
      • 群主变更后回调
      • Group Creation Daily Net Increase Threshold Alarm Callback
    • 机器人相关回调
      • 单聊机器人消息回调
      • 群内@机器人之后回调

回调概述

概述

为方便您精细化控制 App 的功能形态,即时通信 Chat 为您提供了完全免费且强大的回调能力,默认使用长连接方式。所谓回调,即即时通信 Chat 后台会在某一事件发生之前或者之后,向 App 的后台服务器发送请求,App 后台可以据此进行必要的数据同步,或者干预事件的后续处理流程。即时通信 Chat 目前支持的回调请参见 回调命令列表
第三方回调将通过 HTTP/HTTPS 请求的方式发送给 App 后台服务器,App 后台服务器需要处理即时通信 Chat 的回调请求并尽快进行应答。以 群内发言之前回调 为例,即时通信 Chat 后台会在下发该消息之前回调 App 后台服务器,并根据回调结果决定该消息是否应当下发,App 可以基于该回调来实现消息同步。回调业务流程如下图所示:


回调分类

从功能角度来看,回调可以分为四大类:
在线状态回调
资料关系链回调
单聊消息回调
群组系统回调
从处理角度来看,回调可以分为以下两大类:
事件发生之前回调:回调的主要目的在于让 App 后台可以干预该事件的处理逻辑,即时通信 Chat 会根据回调返回码确定后续处理流程(例如发送群消息之前回调)。
事件发生之后通知:回调的主要目的在于让 App 后台实现必要的数据同步,即时通信 Chat 忽略回调返回码(例如群组成员退群之后通知)。

回调协议

第三方回调基于 HTTP/HTTPS 协议,App 后台需要向即时通信 Chat 提供回调 URL,即时通信 Chat 使用 POST 请求的方式来向 App 后台发起回调请求。即时通信 Chat 在发起回调时,会在 App 提供的 URL 之后增加如下几个参数:
参数
含义
SdkAppid
App 在即时通信 Chat 分配的应用标识
CallbackCommand
回调命令字
contenttype
可选,通常值为 JSON
ClientIP
客户端 IP 地址
OptPlatform
客户端平台,对应不同的平台类型,可能的取值有:RESTAPI(使用 REST API 发送请求)、Web(使用 Web SDK 发送请求)、Android、iOS、Windows、Mac、iPad、Unknown(使用未知类型的设备发送请求)
说明:
State.StateChange 回调是大写的 IOS,其余回调是小写的 iOS,使用时请自行兼容。
具体的回调内容则会包含在 HTTP 请求包体中,参见下文回调示例。

回调示例

回调请求示例:
POST /?SdkAppid=888888&CallbackCommand=Group.CallbackAfterNewMemberJoin&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform HTTP/1.1
Host: www.example.com
Content-Length: 337
{
"CallbackCommand": "Group.CallbackAfterNewMemberJoin",
"GroupId": "@TGS#2J4SZEAEL",
"Type": "Public",
"JoinType": "Apply",
"Operator_Account": "leckie",
"NewMemberList": [
{
"Member_Account": "jared"
},
{
"Member_Account": "tommy"
}
]
}
回调应答示例:
HTTP/1.1 200 OK
Server: nginx/1.7.10
Date: Fri, 09 Oct 2015 02:59:55 GMT
Content-Length: 75
{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0
}

回调超时时间及重试

即时通信 Chat 回调 App 后台的超时时间为2秒。
事件发生之前回调没有重试。事件发生之后回调默认没有重试,控制台支持自助配置事件发生之后回调超时后是否进行重试。
为确保回调成功率,第三方 App 应当尽可能加快回调处理速度,例如先发送回调应答,然后再处理具体业务逻辑。

事件发生之前回调超时的处理策略

如果事件发生之前回调超时,默认策略是消息正常下发。
控制台也支持自助配置“事件发生之前回调失败的处理策略”,例如,假设“发送群消息之前回调”超时,后续处理策略是消息正常下发还是不下发。

安全考虑

即时通信 Chat 同时支持 HTTP/HTTPS 回调,其中 HTTPS 回调需要在App 后台的 WebServer 配置 CA 机构签发的证书或即时通信 Chat 免费签发的证书。
说明:
获取即时通信 Chat 免费签发的证书,需先登录控制台配置回调 URL 并下载证书,详细操作步骤请参见 回调配置
安全性问题:
1. HTTP 是明文传输,数据的保密性无法保证,建议使用HTTPS。
2. 无法验证回调请求是否真正来自于即时通信 Chat。
为了解决请求来源的安全性问题,我们为您提供回调应用层签名认证,启用步骤如下:
1. 在控制台中配置回调 URL、回调开启。
2. 在回调URL配置中,开启鉴权,并配置鉴权Token,配置完成后,回调请求URL参数会增加签名Sign以及签名时间戳RequestTime,签名算法:Sign=sha256(TokenRequestTime)
3. 在App 后台支持针对回调请求进行鉴权,通过本地鉴权Token以及回调URL参数中的签名时间戳RequestTime计算sha256,比较签名是否匹配。
签名算法示例:

Token=xxxxyyyy
RequestTime=1669872112
Sign=sha256(xxxxyyyy1669872112)=17773bc39a671d7b9aa835458704d2a6db81360a5940292b587d6d760d484061

回调 URL=URL&Sign=17773bc39a671d7b9aa835458704d2a6db81360a5940292b587d6d760d484061&RequestTime=1669872112

回调不通的常见原因

如果遇到回调不通的情况,App 先依照如下清单排查一下设置的回调服务是否存在问题。
回调不通的现象
可能存在的原因
回调 URL 访问超时
1. 即时通信 Chat 无法完成 DNS 解析,请确认该域名是否在公网生效。(例如,回调 HOST 为 http://notexist.com,该域名不存在,即时通信 Chat 无法完成 DNS 解析。)
2. 即时通信 Chat 无法访问到回调 URL 中配置的 IP,请确认该 IP 是否公网可达。(例如,回调 HOST 为 http://10.0.0.1,该域名为 App 内网 IP,即时通信 Chat 无法访问到该 IP。)
3. App 回调服务防火墙策略限制,请检查防火墙配置。(例如,App 回调服务器拒绝了所有到达 80 端口的请求。)
回调服务拒绝访问
即时通信 Chat 可以访问到 HOST,但链接建立失败,请确认 WebServer 已经正确启动。(例如:App 回调服务器的 WebServer 并未启动,或者端口配置错误。)
回调服务 HTTPS 证书配置错误
回调方式为 HTTPS(或 HTTPS 双向认证),即时通信 Chat 能够访问到 App 回调服务器,但判定 App WebServer 配置的证书非法。请确认 HTTPS 证书配置正确。
回调服务 HTTPS 双向认证配置错误
回调方式为 HTTPS 双向认证,即时通信 Chat 校验 App 回调服务器的证书合法,但 App 回调服务器校验即时通信 Chat 的证书失败。
说明:
HTTPS 双向认证方式已下线,建议您采用更方便的回调应用层签名认证
回调服务 HTTP 返回码非200
回调请求成功,但应答报文中的 HTTP 返回码非200。
回调应答包体解析失败
回调请求包体非 JSON 格式。

在技术社区提问