差别
这里会显示出您选择的修订版和当前版本之间的差别。
| 两侧同时换到之前的修订记录 前一修订版 后一修订版 | 前一修订版 后一修订版 两侧同时换到之后的修订记录 | ||
|
im:extensions:value:rtmsgcallback [2018/12/19 05:04] jk |
im:extensions:value:rtmsgcallback [2019/06/12 03:44] jk [实时回调功能说明] |
||
|---|---|---|---|
| 行 1: | 行 1: | ||
| - | ====== 实时消息回调 ====== | + | ====== 实时消息回调 ====== |
| ---- | ---- | ||
| - | ===== 常用场景 ===== | + | ===== 使用场景 ===== |
| 实时消息回调经常用在应用需要针对用户发送的消息进行处理的场景。比如： | 实时消息回调经常用在应用需要针对用户发送的消息进行处理的场景。比如： | ||
| 行 10: | 行 10: | ||
| * 在 APP 自己的服务端实时保存聊天历史 | * 在 APP 自己的服务端实时保存聊天历史 | ||
| - | __注：如果您对聊天消息没有实时性需求，可以直接通过免费的[[im:server:basics:chatrecord|聊天记录拉取 REST API]] 获取聊天记录，无需使用实时消息回调。__ | + | 注：如果您对聊天消息没有实时性需求，可以直接通过免费的[[im:server:basics:chatrecord|聊天记录拉取 REST API]] 获取聊天记录，无需使用实时消息回调。 |
| + | {{ :im:quickstart:essential:image029.png?nolink |}} | ||
| + | ===== 实时回调功能说明 ===== | ||
| - | ===== 开通回调 ===== | + | 以下是实时回调功能说明，在高并发可用性的基础上的使用限制说明，请按照此限制正确使用回调。 |
| - | **实时消息回调属于增值服务，请联系环信的商务经理询问价格，付费开通。** | + | * 实时消息回调属于增值服务，请联系环信商务询问价格，或者直接注册环信console账号自助付费开通。 |
| + | * 实时消息回调开通允许用户配置提供2个回调规则配额，如果需要再增加回调规则，需要联系环信商务。 | ||
| + | * 实时消息回调规则设置成功后，即刻正常使用。 | ||
| + | * 实时消息回调范围，所有上行消息有效（包含REST发送的消息），包含单聊/群聊；如果 APP 开通了反垃圾/敏感词过滤，被识别的消息会在服务器被拦截并禁止发送，将不会回调。 | ||
| + | * 实时消息回调接收延迟，是指环信服务器执行发出回调至环信服务器收到指定服务器的返回值200，代表实时回调已成功。接收延迟需要根据实际情况判断，在正常情况下是秒级延迟。 | ||
| + | * 实时消息回调对同一个 APP 可以针对不同类型的消息（chat 和 chat_offline）做配置，如果 APP 同时需要 chat 和 chat_offline 两种消息，建议区分回调地址。当然，规则也可以把这两种消息同时回调至一个指定服务器地址，在接收到消息后，可以对 eventType 做判断，区分消息的类型。 | ||
| + | * **实时消息回调重试，当环信服务器执行发出回调后，没有返回200或者返回其他错误码时，认为是指定服务器有网络或者其他因素导致失败，超过60秒后，会进行1次重连尝试，60秒内仍没有成功，将不会再次进行重试，记一次失败次数，1分钟累计180次失败 ，会对应封禁该 APP 回调规则，需要用户手动重新设置。** | ||
| + | * **指定服务器收到回调消息后，向环信服务器发出响应内容不能超过1000长度，如果连续发送超长的响应内容，会导致回调规则封禁，只能手动解除，需要用户手动重新设置。** | ||
| - | APP需要提供以下配置信息： | ||
| - | * 需要回调的类型，目前有两种消息类型可以回调（chat 和 chat_offline）。 | + | ===== 开通规则配置 ===== |
| - | * APP 的回调地址，环信会把消息推送到该地址上，APP 可以针对不同类型的消息配置不同的回调地址。 | + | |
| - | * （可选）APP 可以提供自己的密钥用来替换默认的密钥。（默认情况下，环信发给 APP 的数据，签名时使用的密钥是环信生成的，APP 发到环信的数据，签名时使用的密钥亦为环信生成秘钥）。 | + | |
| - | 消息类型描述： | + | APP 可以配置回调规则的数据格式，可以配置多个回调规则（默认最多开通2个规则），开通服务后才允许用户配置，[[https://console.easemob.com/app-detail/service/app-msgback|前往配置]]： |
| + | ^参数^说明^ | ||
| + | |规则名称|填写唯一的规则名称| | ||
| + | |消息类型|需要回调的类型，目前有两种消息类型可以回调（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的选择： | + | === 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只需要用户的聊天记录，那么配置chat类型消息的回调即可。 | ||
| - | * 如果APP只需要针对离线消息做APNS推送等推广，那么配置chat_offline类型的消息回调即可。 | + | * 如果APP只需要针对离线消息做APNS推送等推送，那么配置chat_offline类型的消息回调即可。 |
| - | * 如果APP同时需要用户的聊天记录也需要针对离线消息做处理，那么需要配置chat和chat_offline两种类型的消息回调。 | + | * 如果APP同时需要用户的聊天记录也需要针对离线消息做处理，那么需要同时配置chat和chat_offline两种类型的消息回调。 |
| ===== 消息回调接口参数说明 ===== | ===== 消息回调接口参数说明 ===== | ||
| 行 41: | 行 58: | ||
| APP 的响应内容不能超过1000个字符。 | APP 的响应内容不能超过1000个字符。 | ||
| - | ==== 回调的正文 ==== | + | === 回调消息的参数说明 === |
| + | ^参数^说明^ | ||
| + | |callId|每个回调的ID都不一样| | ||
| + | |eventType|必填。“chat“上行消息、“chat_offline”离线消息，可以都选择| | ||
| + | |timestamp|环信接收到此消息的时间戳| | ||
| + | |chat_type|"chat"单聊回调、"groupchat"群聊回调包含了群组和聊天室的消息回调，默认全选| | ||
| + | |group_id|群聊时才有此参数，回调消息所在的群组| | ||
| + | |from|消息的发送方| | ||
| + | |to|消息的接收方| | ||
| + | |msg_id|消息的 ID | | ||
| + | |payload|消息内容，与通过REST API发送过来的一致，查看[[im:server:basics:chatrecord#聊天记录数据结构|消息格式文档]]| | ||
| + | |securityVersion|安全校验版本，目前为1.0.0。忽略此参数，以后会改成Console后台做设置| | ||
| + | |security|签名。格式如下: MD5（callId+约定的key+timestamp），约定的key为654321，以后会改成Console后台做设置| | ||
| + | |||
| + | ===回调成功返回的示例=== | ||
| <code json> | <code json> | ||
| { | { | ||
| - | "callId":"",//每个回调的ID都不一样 | + | "callId":"", |
| - | "eventType":"chat_offline",//用于以后的扩展，现在只推送聊天消息（离线和所有），以后会加入更多，比如用户加入了某个群组 | + | "eventType":"chat_offline", |
| - | "timestamp":0,//环信接收到此消息的时间 | + | "timestamp":0, |
| - | "chat_type":"groupchat", // 群聊，如果是单聊则为 "chat" | + | "chat_type":"groupchat", |
| - | "group_id":'',//群聊时才有此参数 | + | "group_id":'', |
| - | "from":"",//消息的发送方 | + | "from":"", |
| - | "to":"",//消息的接收方 | + | "to":"", |
| - | "msg_id":"",// 消息ID | + | "msg_id":"", |
| - | "payload":{//消息，与通过REST API发送过来的一致 | + | "payload":{ |
| + | // 具体的消息内容 | ||
| }, | }, | ||
| - | "securityVersion":"",//安全校验版本，目前为1.0.0。忽略此参数，以后会改成Console后台做设置 | + | "securityVersion":"", |
| - | "security":""//签名。格式如下: MD5（callId+约定的key+timestamp），约定的key为654321，以后会改成Console后台做设置 | + | "security":"" |
| } | } | ||
| </code> | </code> | ||
| - | ==== Payload 数据格式说明 ==== | + | [[im:server:basics:chatrecord#聊天记录数据结构|Payload 数据格式说明]]。 |
| - | + | ===== 指定服务器回调回执参数说明 ===== | |
| - | 详情可参见：[[im:server:basics:messages|发送消息]]。 | + | |
| - | + | ||
| - | <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 返回的响应正文 ==== | + | ^参数^说明^ |
| + | |callId|与环信推送的一致| | ||
| + | |accept|"true"表明接受了此推送| | ||
| + | |reason|可选，accept为false时使用| | ||
| + | |security|签名。格式如下: MD5（callId+约定的key+"true"），约定key为654321。APP 服务器接收到消息时，需要做签名校验，以保证消息的安全性。| | ||
| + | ===APP 返回示例=== | ||
| <code json> | <code json> | ||
| { | { | ||
| - | "callId":"",//与环信推送的一致 | + | "callId":"", |
| - | "accept":"true",//表明接受了此推送 | + | "accept":"true", |
| - | "reason":"",//可选，accept为false时使用 | + | "reason":"", |
| - | "security":""//签名。格式如下: MD5（callId+约定的key+"true"），约定key为654321 | + | "security":"" |
| } | } | ||
| </code> | </code> | ||
| - | ===== 注意事项 ===== | ||
| - | * APP 服务器接收到消息时，需要做签名校验，以保证消息的安全性。 | ||
| - | * 同一个 APP 可以针对不同类型的消息（chat 和 chat_offline）做配置，如果 APP 同时需要 chat 和 chat_offline 两种消息，那么最好区分回调地址。当然，APP 也可以把这两种消息的回调地址配置成一个，那么需要 APP 在接收到消息的时候，对 eventType 做判断，区分消息是属于哪种类型的。 | ||
| - | * **APP 服务器接到回调消息后的响应内容不能超过1000个字符，如果连续发送超长消息会导致回调接口被封禁。接收回调消息的 APP 服务器需要保证回调接口高并发下的可用性，如果接收回调消息时出现504错误等，页面会因为响应消息过长而停止回调。** | ||
| 行 107: | 行 117: | ||
| <WRAP group> | <WRAP group> | ||
| <WRAP half column> | <WRAP half column> | ||
| - | 上一章节：[[im:linux:integration|Linux SDK集成]] | + | 上一页：[[im:quickstart:essential:communicationandmessagestorage|通信过程及聊天记录保存]] |
| </WRAP> | </WRAP> | ||
| <WRAP half column> | <WRAP half column> | ||
| - | 下一页：[[im:extensions:value:multidevice|多设备同步]] | + | 下一页：[[im:quickstart:essential:console|环信管理后台使用指南]] |
| </WRAP> | </WRAP> | ||
| </WRAP> | </WRAP> | ||