第三方回调简介

最近更新时间:2019-08-02 18:41:12

概述

为方便您精细化控制 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、Unkown(使用未知类型的设备发送请求)

具体的回调内容则会包含在 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 支持三种回调类型:

  1. HTTP 回调。
  2. HTTPS 回调,App 后台的 WebServer 配置的是 CA 机构签发的证书或者是即时通信 IM 免费签发的证书。
  3. HTTPS 双向认证回调,App 后台的 WebServer 配置的是 CA 机构签发的证书或者是即时通信 IM 免费签发的证书,且启用双向认证能力。

三种方案的安全性逐步递增:

  1. HTTP 回调存在两个缺陷:一是明文传输的数据容易被窃听,二是第三方 App 无法判断回调请求是否真正来自于即时通信 IM。
  2. 对于 HTTPS 回调,如果不启用双向认证,可以解决数据的加密问题,但依然无法确保回调的请求来源是即时通信 IM。
  3. 只有 HTTPS 与双向认证结合,才能确保第三方回调的安全性。

我们强烈建议 App 使用第三种方式实现回调,且即时通信 IM 签发证书完全免费。

回调配置

目前即时通信 IM 控制台支持自助配置回调,包括配置回调 URL 以及启用哪些回调。配置方法参见 第三方回调配置 文档。

注意:

控制台自助配置的回调仅支持 HTTP/HTTPS 回调。如果您需要启用安全级别最强的 HTTPS 双向认证:

  1. 在控制台中配置回调 URL(必须为 HTTPS 域名)、回调开启。
  2. 给即时通信 IM 提需求工单,由即时通信 IM 给 App 签发双向认证所需的证书,所需要的资料包括:
    1. SDKAppID
    2. App 名称
    3. 回调 URL(必须与控制台中自助配置的回调URL一致)
  3. 拿到证书之后,依照如下两篇指引配置 HTTPS 双向认证:
    1. Apache 配置 HTTPS 双向认证指南
    2. 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 格式。