这是本文档旧的修订版!
实时消息回调
使用场景
实时消息回调经常用在应用需要针对用户发送的消息进行处理的场景。比如:
- 针对客户消息的内容进行自动回复
- 在 APP 自己的服务端实时保存聊天历史
注:如果您对聊天消息没有实时性需求,可以直接通过免费的聊天记录拉取 REST API 获取聊天记录,无需使用实时消息回调。
实时回调功能说明
以下是实时回调功能说明,在高并发可用性的基础上的使用限制说明,请按照此限制正确使用回调。
- 实时消息回调属于增值服务,请联系环信商务询问价格,或者直接注册环信console账号自助付费开通。
- 实时消息回调开通允许用户配置提供2个回调规则配额,如果需要再增加回调规则,需要联系环信商务。
- 实时消息回调规则设置成功后,即刻正常使用。
- 实时消息回调范围,所有上行消息有效(包含REST发送的消息),包含单聊/群聊;如果 APP 开通了反垃圾/敏感词过滤,被识别的消息会在服务器被拦截并禁止发送,将不会回调。
- 实时消息回调接收延迟,是指环信服务器执行发出回调至环信服务器收到指定服务器的返回值200,代表实时回调已成功。接收延迟需要根据实际情况判断,在正常情况下是秒级延迟。
- 实时消息回调对同一个 APP 可以针对不同类型的消息(chat 和 chat_offline)做配置,如果 APP 同时需要 chat 和 chat_offline 两种消息,建议区分回调地址。当然,规则也可以把这两种消息同时回调至一个指定服务器地址,在接收到消息后,可以对 eventType 做判断,区分消息的类型。
- 实时消息回调重试,当环信服务器执行发出回调后,没有返回200或者返回其他错误码时,认为是指定服务器有网络或者其他因素导致失败,超过60秒后,会进行1次重连尝试,60秒内仍没有成功,将不会再次进行重试,记一次失败次数,1分钟累计180次失败 ,会对应封禁该 APP 回调规则,需要用户手动重新设置。
- 指定服务器收到回调消息后,向环信服务器发出响应内容不能超过1000长度,如果连续发送超长的响应内容,会导致回调规则封禁,只能手动解除,需要用户手动重新设置。
开通规则配置
APP 可以配置回调规则的数据格式,可以配置多个回调规则(默认最多开通2个规则),开通服务后才允许用户配置,前往配置:
参数 | 说明 |
---|---|
规则名称 | 填写唯一的规则名称 |
消息类型 | 需要回调的类型,目前有两种消息类型可以回调(chat为上行消息;chat_offline为离线消息,可以同时选择) |
回调地址 | APP 的回调地址,环信会把消息推送到填写的URL地址上,APP 可以针对不同类型的消息配置不同的回调地址。 |
密钥 | (可选)APP 可以提供自己的密钥用来替换默认的密钥。(默认情况下,环信发给 APP 的数据,签名时使用的密钥是环信生成的,APP 发到环信的数据,签名时使用的密钥亦为环信生成秘钥)。 |
chat 上行消息
这个消息跟通过 REST 导出聊天记录查询到的消息一致。比如:一个用户(u1)给另一个用户(u2)发送消息,那么就会产生一条 chat 消息,与接收方是否在线无关。接收到的消息里面 from 为 u1,to 为 u2。一个用户(u1)给一个群(g1)发送消息,那么会产生一条 chat 消息,接收到的消息里面 from 为 u1,to 为 g1,且返回值包含 group_id 字段。
chat_offline 离线消息
APP 可以根据这个消息做 APNS 推送等个性化的推广。例如:给一个用户发送消息,如果用户不在线,那么会产生一条离线消息。如果给一个群发送消息,那么群里有几个用户不在线,就会产生几条离线消息。
chat_type的选择
- 如果APP只需要用户的聊天记录,那么配置chat类型消息的回调即可。
- 如果APP只需要针对离线消息做APNS推送等推送,那么配置chat_offline类型的消息回调即可。
- 如果APP同时需要用户的聊天记录也需要针对离线消息做处理,那么需要同时配置chat和chat_offline两种类型的消息回调。
消息回调接口参数说明
目前只支持 HTTP 方式的回调,采用 POST 方式,正文部分为 JSON 格式的字符串,字符集为 UTF-8。
回调时,会对发送的正文做 MD5 签名,APP 返回的响应也需要做 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+约定的key+timestamp),约定的key为654321,以后会改成Console后台做设置 |
回调成功返回的示例
{
"callId":"",
"eventType":"chat_offline",
"timestamp":0,
"chat_type":"groupchat",
"group_id":'',
"from":"",
"to":"",
"msg_id":"",
"payload":{
// 具体的消息内容
},
"securityVersion":"",
"security":""
}
指定服务器回调回执参数说明
参数 | 说明 |
---|---|
callId | 与环信推送的一致 |
accept | “true”表明接受了此推送 |
reason | 可选,accept为false时使用 |
security | 签名。格式如下: MD5(callId+约定的key+“true”),约定key为654321。APP 服务器接收到消息时,需要做签名校验,以保证消息的安全性。 |