====== 实时消息回调 ======

----

===== 常用场景 =====

实时消息回调经常用在应用需要针对用户发送的消息进行处理的场景。比如：

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

__注：如果您对聊天消息没有实时性需求，可以直接通过免费的[[start:100serverintegration:30chatlog|聊天记录拉取REST API]] 获取聊天记录，无需使用实时消息回调。__

===== 开通回调 =====

**实时消息回调属于增值服务，请联系环信的商务经理询问价格，付费开通。**

APP 需要提供以下配置信息：

  * 需要回调的类型，目前有两种消息类型可以回调（chat 和 chat_offline）。
  * APP 的回调地址，环信会把消息推送到该地址上，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个字符。

==== 回调的正文 ====

<code json>
{
    "callId":"",//每个回调的ID都不一样
    "eventType":"chat_offline",//用于以后的扩展，现在只推送聊天消息（离线和所有），以后会加入更多，比如用户加入了某个群组
    "timestamp":0,//环信接收到此消息的时间
    "chat_type":"groupchat", // 群聊，如果是单聊则为"chat"
    "group_id":'',//群聊时才有此参数
    "from":"",//消息的发送方
    "to":"",//消息的接收方
    "msg_id":"",// 消息ID
    "payload":{//消息，与通过REST API发送过来的一致
    },
    "securityVersion":"",//安全校验版本，目前为1.0.0。忽略此参数，以后会改成Console后台做设置
    "security":""//签名。格式如下: MD5（callId+约定的key+timestamp），约定的key为123456，以后会改成Console后台做设置
}
</code>

==== Payload 数据格式说明 ====

详情可参见：[[start:100serverintegration:50messages|发送消息]]。

<code json>
{
     "bodies": [ //消息bodies
       {
         "msg": "hhhhhh", //消息内容
         "type": "txt" //消息类型。txt: 文本消息；img: 图片；loc: 位置；audio: 语音
         "length": 3, //语音时长，单位为秒，这个属性只有语音消息有
         "url": "", //图片语音等文件的网络URL，图片和语音消息有这个属性
         "filename": "22.png", //文件名字，图片和语音消息有这个属性
         "secret": "pCY80PdfEeO4Jh9URCOfMQWU9QYsJytynu4n-yhtvAhmt1g9", //获取文件的secret，图片和语音消息有这个属性
         "lat": 39.983805, //发送的位置的纬度，只有位置消息有这个属性
         "lng": 116.307417, //位置经度，只有位置消息有这个属性
         "addr": "北京市海淀区北四环西路66号" //位置消息详细地址，只有位置消息有这个属性
       }
     ],
     "ext": { //自定义扩展属性
         "key1": "value1",   //你设置的key和value的值
    	    ...
     }
}
</code>

==== APP 返回的响应正文 ====

<code json>
{
    "callId":"",//与环信推送的一致
    "accept":"true",//表明接受了此推送
    "reason":"",//可选，accept为false时使用
    "security":""//签名。格式如下: MD5（callId+约定的key+"true"），约定key为654321
}
</code>

===== 注意事项 =====

  * APP 服务器接收到消息时，需要做签名校验，以保证消息的安全性。
  * 同一个 APP 可以针对不同类型的消息（chat 和 chat_offline）做配置，如果 APP 同时需要 chat 和 chat_offline 两种消息，那么最好区分回调地址。当然，APP 也可以把这两种消息的回调地址配置成一个，那么需要 APP 在接收到消息的时候，对 eventType 做判断，区分消息是属于哪种类型的。
  * **APP 服务器接到回调消息后的响应内容不能超过1000个字符，如果连续发送超长消息会导致回调接口被封禁。接收回调消息的 APP 服务器需要保证回调接口高并发下的可用性如果接收回调消息时出现504错误等页面会因为响应消息过长而停止回调。**


----
<WRAP group>
<WRAP half column>
上一页：[[start:000quickstart:25communicationandmessagestorage|通信过程及聊天记录保存]]
</WRAP>

<WRAP half column>
下一章节：[[start:100serverintegration:10intro|服务端集成]]
</WRAP>
</WRAP>