即时通信 IM 第三方回调简介 - 服务端 API

概述

为方便您精细化控制 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 之后增加如下几个参数：

具体的回调内容则会包含在 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 免费签发的证书，且启用双向认证能力。

说明：

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

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

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

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

回调配置

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

注意：

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

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

回调不通的常见原因

如果遇到回调不通的情况，App 先依照如下清单排查一下设置的回调服务是否存在问题。