tencent cloud

概述

为方便您精细化控制 App 的功能形态，即时通信 IM 为您提供了完全免费且强大的回调能力，默认使用长连接方式。所谓回调，即即时通信 IM 后台会在某一事件发生之前或者之后，向 App 的后台服务器发送请求，App 后台可以据此进行必要的数据同步，或者干预事件的后续处理流程。即时通信 IM 目前支持的回调请参见 回调命令列表。

第三方回调将通过 HTTP/HTTPS 请求的方式发送给 App 后台服务器，App 后台服务器需要处理即时通信 IM 的回调请求并尽快进行应答。以 群内发言之前回调 为例，即时通信 IM 后台会在下发该消息之前回调 App 后台服务器，并根据回调结果决定该消息是否应当下发，App 可以基于该回调来实现消息同步。回调业务流程如下图所示：

回调分类

从功能角度来看，回调可以分为四大类：

• 在线状态回调
• 资料关系链回调
• 单聊消息回调
• 群组系统回调

从处理角度来看，回调可以分为以下两大类：

• 事件发生之前回调：回调的主要目的在于让 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.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
}

回调超时时间及重试

即时通信 IM 回调 App 后台的超时时间为2秒。

事件发生之前回调没有重试。事件发生之后回调默认没有重试，控制台支持自助配置事件发生之后回调超时后是否进行重试。

为确保回调成功率，第三方 App 应当尽可能加快回调处理速度，例如先发送回调应答，然后再处理具体业务逻辑。

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

如果事件发生之前回调超时，默认策略是消息正常下发。

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

安全考虑

即时通信 IM 同时支持 HTTP/HTTPS 回调，其中 HTTPS 回调需要在App 后台的 WebServer 配置 CA 机构签发的证书或即时通信 IM 免费签发的证书。

说明：

获取即时通信 IM 免费签发的证书，需先登录控制台配置回调 URL 并下载证书，详细操作步骤请参见 回调配置。

安全性问题：

1. HTTP 是明文传输，数据的保密性无法保证，建议使用HTTPS。
2. 无法验证回调请求是否真正来自于即时通信 IM。

为了解决请求来源的安全性问题，我们提供了两种方案：

1. 支持回调鉴权（推荐）。

   配置指引

   1. 在控制台中配置回调 URL、回调开启。
   2. 在回调URL配置中，开启鉴权，并配置鉴权Token，配置完成后，回调请求URL参数会增加签名Sign以及签名时间戳RequestTime，签名算法：Sign=sha256(TokenRequestTime)
   3. 在App 后台支持针对回调请求进行鉴权，通过本地鉴权Token以及回调URL参数中的签名时间戳RequestTime计算sha256，比较签名是否匹配。

   签名算法示例：
   
   

Token=xxxyyy
RequestTime=1669872112
Sign=sha256(xxxyyy1669872112)=17773bc39a671d7b9aa835458704d2a6db81360a5940292b587d6d760d484061

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


2. 支持 HTTPS 双向认证。

   配置指引

   1. 在控制台中配置回调 URL（必须为 HTTPS 域名）、回调开启。
   2. 单击右侧的HTTPS 双向认证证书下载获取证书，依照如下两篇指引配置 HTTPS 双向认证：
   3. Apache 配置 HTTPS 双向认证指南
   4. Nginx 配置 HTTPS 双向认证指南

回调不通的常见原因

如果遇到回调不通的情况，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 的证书失败。
回调服务 HTTP 返回码非200	回调请求成功，但应答报文中的 HTTP 返回码非200。
回调应答包体解析失败	回调请求包体非 JSON 格式。