概述
为方便您精细化控制 App 的功能形态，即时通信 IM 为您提供了完全免费且强大的回调能力，默认使用长连接方式。所谓回调，即即时通信 IM 后台会在某一事件发生之前或者之后，向 App 的后台服务器发送请求，App 后台可以据此进行必要的数据同步，或者干预事件的后续处理流程。即时通信 IM 目前支持的回调请参见 回调命令列表。
第三方回调将通过 HTTP/HTTPS 请求的方式发送给 App 后台服务器，App 后台服务器需要处理即时通信 IM 的回调请求并尽快进行应答。以 群内发言之前回调 为例，即时通信 IM 后台会在下发该消息之前回调 App 后台服务器，并根据回调结果决定该消息是否应当下发，App 可以基于该回调来实现消息同步。回调业务流程如下图所示：
注意：
消息前回调默认2s超时且不支持调整，使用消息前回调处理内容审核，会增加两次公网传输，消息发送的整体时延会比普通场景增加至少2倍。如果您有内容审核的需求，请直接使用云端审核功能，无需额外开发且无时延增加风险，详见 内容审核场景实践。
回调分类
从功能角度来看，回调可以分为四大类：
在线状态回调
资料关系链回调
单聊消息回调
群组系统回调
从处理角度来看，回调可以分为以下两大类：
事件发生之前回调：回调的主要目的在于让 App 后台可以干预该事件的处理逻辑，即时通信 IM 会根据回调返回码确定后续处理流程（例如发送群消息之前回调）。
事件发生之后通知：回调的主要目的在于让 App 后台实现必要的数据同步，即时通信 IM 忽略回调返回码（例如群组成员退群之后通知）。
回调协议
第三方回调基于 HTTP/HTTPS 协议，App 后台需要向即时通信 IM 提供回调 URL，即时通信 IM 使用 POST 请求的方式来向 App 后台发起回调请求。即时通信 IM 在发起回调时，会在 App 提供的 URL 之后增加如下几个参数：
参数 | 含义 |
SdkAppid | App 在即时通信 IM 分配的应用标识 |
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.1Host: www.example.comContent-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 OKServer: nginx/1.7.10Date: Fri, 09 Oct 2015 02:59:55 GMTContent-Length: 75{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0}
回调超时时间及重试
即时通信 IM 回调 App 后台的超时时间为2秒。
事件发生之前回调没有重试。事件发生之后回调默认没有重试，控制台支持自助配置事件发生之后回调超时后是否进行重试。
为确保回调成功率，第三方 App 应当尽可能加快回调处理速度，例如先发送回调应答，然后再处理具体业务逻辑。
事件发生之前回调超时的处理策略
如果事件发生之前回调超时，默认策略是消息正常下发。
控制台也支持自助配置“事件发生之前回调失败的处理策略”，例如，假设“发送群消息之前回调”超时，后续处理策略是消息正常下发还是不下发。
安全考虑
即时通信 IM 同时支持 HTTP/HTTPS 回调，其中 HTTPS 回调需要在 App 后台的 WebServer 配置 CA 机构签发的证书或即时通信 IM 免费签发的证书。
说明:
安全性问题：
1. HTTP 是明文传输，数据的保密性无法保证，建议使用 HTTPS。
2. 无法验证回调请求是否真正来自于即时通信 IM。
为了解决请求来源的安全性问题，我们为您提供回调应用层签名认证，启用步骤如下：
1. 在控制台中配置回调 URL、开启回调功能。
2. 在回调 URL 配置中，开启鉴权，并配置鉴权 Token，配置完成后，回调请求 URL 参数会增加签名 Sign 以及签名时间戳 RequestTime，签名算法：Sign=sha256(TokenRequestTime)
3. 在 App 后台支持针对回调请求进行鉴权，通过本地鉴权 Token 以及回调 URL 参数中的签名时间戳 RequestTime 计算 sha256，比较签名是否匹配。并对 RequestTime 校验时效性，RequestTime 和当前时间相差超过1分钟即可认为是无效请求，以防止重放攻击。
签名算法示例如下：
Token=xxxxyyyyRequestTime=1669872112Sign=sha256(xxxxyyyy1669872112)=17773bc39a671d7b9aa835458704d2a6db81360a5940292b587d6d760d484061回调 URL=URL&Sign=17773bc39a671d7b9aa835458704d2a6db81360a5940292b587d6d760d484061&RequestTime=1669872112
回调不通的常见原因
如果遇到回调不通的情况，App 先依照如下清单排查一下设置的回调服务是否存在问题。
回调不通的现象 | 可能存在的原因 |
回调 URL 访问超时 | 1. 即时通信 IM 无法完成 DNS 解析，请确认该域名是否在公网生效。（例如，回调 HOST 为 http://notexist.com，该域名不存在，即时通信 IM 无法完成 DNS 解析。） 2. 即时通信 IM 无法访问到回调 URL 中配置的 IP，请确认该 IP 是否公网可达。（例如，回调 HOST 为 http://10.0.0.1，该域名为 App 内网 IP，即时通信 IM 无法访问到该 IP。） 3. App 回调服务防火墙策略限制，请检查防火墙配置。（例如，App 回调服务器拒绝了所有到达 80 端口的请求。） |
回调服务拒绝访问 | 即时通信 IM 可以访问到 HOST，但链接建立失败，请确认 WebServer 已经正确启动。（例如：App 回调服务器的 WebServer 并未启动，或者端口配置错误。） |
回调服务 HTTPS 证书配置错误 | 回调方式为 HTTPS（或 HTTPS 双向认证），即时通信 IM 能够访问到 App 回调服务器，但判定 App WebServer 配置的证书非法。请确认 HTTPS 证书配置正确。 |
回调服务 HTTPS 双向认证配置错误 | 回调方式为 HTTPS 双向认证，即时通信 IM 校验 App 回调服务器的证书合法，但 App 回调服务器校验即时通信 IM 的证书失败。 说明： HTTPS 双向认证方式已下线，建议您采用更方便的回调应用层签名认证。 |
回调服务 HTTP 返回码非200 | 回调请求成功，但应答报文中的 HTTP 返回码非200。 |
回调应答包体解析失败 | 回调请求包体非 JSON 格式。 |
