消息回调

本文档已不再维护,新版文档见:回调功能


消息回调,即IM服务器会在事件发生之前或之后,向客户的应用服务器发送请求,应用服务器可以据此进行必要的数据同步(发送后回调),或者根据业务需求干预事件的后续处理流程(发送前回调)。

回调分类

从处理角度看,回调分为以下两类:

  • 发送前回调:回调的主要目的在于让 App 后台可以干预该事件的处理逻辑,IM服务器会根据回调返回码和返回值确定后续处理流程。
  • 发送后回调:回调的主要目的在于让 App 后台实现必要的数据同步,IM服务器忽略回调返回码。

1、发送前回调

应用服务器可以通过发送前回调实时监控用户的聊天消息,包括:

  • 对聊天消息进行实时同步;
  • 拦截用户的消息请求。可拦截所有类型的消息,包含文本、图片、自定义消息等;

IM 服务器收到用户发送的单聊消息之后、将该消息下发给目标用户之前。

以下是发送前回调功能说明,在高并发可用性的基础上的使用限制说明,请按照此限制正确使用回调。

  • 要启用消息回调,必须在管理后台开通消息回调服务,并配置回调规则和URL。
  • 回调的方向是环信 IM 服务器向应用服务器发起 HTTPS POST 请求。
  • 若同时设置了消息发送前和发送后两种回调,且消息发送前回调返回拒绝,则消息发送后回调将不会被触发。
  • 发送前回调只对客户端发送的消息有效,不包含REST发送的消息。对同一个 APP 可以针对不同类型的消息(“TEXT”,“IMAGE”, “VIDEO”,“LOCATION”,“VOICE”和“FILE”)做配置;规则支持选择两种以上消息类型同时回调至一个指定服务器地址,在接收到消息后,可以区分消息的类型(详情查看API文档)。
  • 当环信服务器执行发送前回调后,没有返回valid状态或者返回其他错误码时,当条消息会根据默认设置处理,不会再重试;后续消息依然正常执行回调。
  • 消息发送到应用服务器后,应用服务器需要返回 HTTP 应答码 200,同时返回 valid 属性,根据 valid 状态决定是否进行下发。
配置说明 是否必填 内容
规则名称 必填 填写文字,支持中英文,长度限制为 32 字符。
会话类型 必填 * 单聊;
* 群组;
* 聊天室。
消息类型 必填 多选:
文本;图片;视频;位置;语音;文件;自定义消息。
等待响应时间 必填 后台判断超时时间,默认 200,单位为毫秒。
调用失败时默认策略 必填 当您的服务器返回结果异常或等待时间内未返回结果时,消息放行或不放行。
消息拦截报错时显示 必填 当消息被拦截时,是否通知发送者 SDK 消息发送失败:
* 报错:通知发送者 SDK 消息发送失败,发送者会感知到消息发送失败;
* 不报错:不通知发送者 SDK 消息发送失败,发送者无感知。
启用状态 必填 回调规则是否马上生效:
* 启用:马上生效;
* 不启用:暂不生效。
(建议首次创建配置为“不启用”,等您的服务器配置好验证信息后再修改为“启用”)
回调地址 必填 回调 URL,环信 IM 对 HTTP 和 HTTPS 的回调地址均支持。

规则说明:

  • 规则可以有多条,每个规则的名称必须是唯一的。
  • 环信 IM 服务器发送前回调应用服务器的超时时间默认为 200 ms,支持自定义“超时时间”。如果回调超时无应答,消息默认会正常下发,支持修改消息处理逻辑。
  • 目前支持发送前回调的消息类型包括:文本,图片,视频,位置,语音,文件,自定义消息。

采用 POST 方式,正文部分为 JSON 格式的字符串,字符集为 UTF-8。

Request Body

名称类型
callId每个回调的ID都不一样
timestamp环信接收到此消息的时间戳
chat_type“chat”单聊回调、“groupchat”群聊回调包含了群组和聊天室的消息回调,默认全选
group_id群聊时才有此参数,回调消息所在的群组
from消息的发送方
to消息的接收方
msg_id消息的 ID
payload消息内容,与通过REST API发送过来的一致,查看消息格式文档
security签名。格式如下: MD5(callId+密钥+timestamp)。

请求示例

{
    "callId":"",
    "eventType":"chat_offline",
    "timestamp":0,
    "chat_type":"groupchat", 
    "group_id":'',
    "from":"",
    "to":"",
    "msg_id":"",
    "payload":{
    // 具体的消息内容
    },
    "securityVersion":"",
    "security":""
}

Response Body 在返回值中查看data字段包含的信息

参数 类型 是否必需 描述
valid bool 根据开发者自己服务器设定的规则判断消息是否合法。
code String 自定义信息,字符串类型。
payload Object 如果需要更改消息内容可以回传修改后的内容,不修改则无需传该内容。格式同传入的消息内容,目前仅支持文本的形式,并且消息大小不能超过 1K。

返回的结果示例:

{
     "valid": true,
    "code": "HX:10000",
     "payload":{
    // 具体的消息内容
    // 仅支持文本类型消息
    },
}

2、发送后回调

发送后回调经常用在App后台需要实现必要的数据同步的场景。比如:

  • 针对客户消息的内容进行自动回复
  • 在 APP 自己的服务端及时保存聊天历史

注:如果您对聊天消息没有时效性需求,可以直接通过免费的聊天记录拉取 REST API 获取聊天记录,无需使用发送后回调。

以下是发送后回调功能说明,在高并发可用性的基础上的使用限制说明,请按照此限制正确使用回调。

  • 消息回调属于增值服务,请联系环信商务询问价格,或者直接注册环信console账号自助付费开通。
  • 消息回调开通允许用户配置提供2个回调规则配额,如果需要再增加回调规则,需要联系环信商务。
  • 消息回调规则设置成功后,即刻正常使用。
  • 发送后回调范围,所有上行消息有效(包含REST发送的消息),包含单聊/群聊;如果 APP 开通了反垃圾/敏感词过滤,被识别的消息会在服务器被拦截并禁止发送,将不会回调。
  • 发送后回调接收延时,是指环信服务器接收到客户端上行消息、再将消息成功回调至客户指定服务器地址的时间间隔。消息接收延时保障是99.95% 的消息在30s内。
  • 发送后回调对同一个 APP 可以针对不同类型的消息(chat 和 chat_offline)做配置,如果 APP 同时需要 chat 和 chat_offline 两种消息,建议区分回调地址。当然,规则也可以把这两种消息同时回调至一个指定服务器地址,在接收到消息后,可以对 eventType 做判断,区分消息的类型。
  • 发送后回调重试,当环信服务器执行发出回调后,响应状态码非200,认为是指定服务器有网络或者其他因素导致失败,记录一次失败,然后立即重试,若再次失败,再记录一次失败,重试失败后不会再重试。30秒内累计90次失败,会对应封禁该 APP 回调规则,5分钟后自动解封。重试失败以及封禁期间的回调不会自动补录,可以下载历史消息文件自行补充。
  • 指定服务器收到回调消息后,向环信服务器发出响应内容不能超过1000长度,如果连续发送超长的响应内容,会导致回调规则封禁,只能手动解除,需要用户手动重新设置。

APPKEY 可以配置回调规则的数据格式,可以配置多个回调规则(默认最多开通2个规则),开通服务后才允许用户配置,前往Console后台配置

环信对回调地址http,https均支持。

参数说明
规则名称填写唯一的规则名称(不能用中文)
消息类型需要回调的类型,目前有两种消息类型可以回调(chat为上行消息;chat_offline为离线消息,可以同时选择)
回调地址 环信会把消息推送到填写的URL地址上,可以针对不同类型的消息配置不同的回调地址。
密钥(可选)默认情况下,环信发给 URL(也就是您自己服务器的)的数据,签名时使用的密钥是环信生成的,Console后台可查看。如果您想提供自己的密钥用来替换默认的,可以联系商务沟通

chat 上行消息

这个消息跟通过 REST 导出聊天记录查询到的消息一致。比如:一个用户(u1)给另一个用户(u2)发送消息,那么就会产生一条 chat 消息,与接收方是否在线无关。接收到的消息里面 from 为 u1,to 为 u2。一个用户(u1)给一个群(g1)发送消息,那么会产生一条 chat 消息,接收到的消息里面 from 为 u1,to 为 g1,且返回值包含 group_id 字段。

chat_offline 离线消息

APP 可以根据这个消息做 APNS 推送等个性化的推广。例如:给一个用户发送消息,如果用户不在线,那么会产生一条离线消息。如果给一个群发送消息,那么群里有几个用户不在线,就会产生几条离线消息,那么这几条离线消息的to为接收消息用户的id,并不是群组id。

chat_type的选择

  • 如果APP只需要用户的聊天记录,那么配置chat类型消息的回调即可。
  • 如果APP只需要针对离线消息做APNS推送等推送,那么配置chat_offline类型的消息回调即可。
  • 如果APP同时需要用户的聊天记录也需要针对离线消息做处理,那么需要同时配置chat和chat_offline两种类型的消息回调。

目前支持 HTTP/HTTPS 方式的回调,采用 POST 方式,正文部分为 JSON 格式的字符串,字符集为 UTF-8。

回调时,会对发送的正文做 MD5 签名。环信这边 MD5 使用的是org.apache.commons.codec.digest.DigestUtils#md5Hex

APP 的响应内容不能超过1000个字符。

回调消息的参数说明

参数说明
callId每个回调的ID都不一样
eventType必填。“chat“上行消息、“chat_offline”离线消息,可以都选择
timestamp环信接收到此消息的时间戳
chat_type“chat”单聊回调、“groupchat”群聊回调包含了群组和聊天室的消息回调,默认全选
group_id群聊时才有此参数,回调消息所在的群组
from消息的发送方
to消息的接收方
msg_id消息的 ID
payload消息内容,与通过REST API发送过来的一致,查看消息格式文档
securityVersion安全校验版本,目前为1.0.0。忽略此参数,以后会改成Console后台做设置
security签名。格式如下: MD5(callId+密钥+timestamp)。

回调成功返回的示例

{
    "callId":"",
    "eventType":"chat_offline",
    "timestamp":0,
    "chat_type":"groupchat", 
    "group_id":'',
    "from":"",
    "to":"",
    "msg_id":"",
    "payload":{
    // 具体的消息内容
    },
    "securityVersion":"",
    "security":""
}

Payload 数据格式说明

环信不验证回调响应的response内容,只要您服务器给我们返回http状态码是200即可。