差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录 前一修订版
后一修订版 		前一修订版
后一修订版 两侧同时换到之后的修订记录
im:extensions:value:rtmsgcallback [2018/12/19 05:04]
jk 		im:extensions:value:rtmsgcallback [2022/03/17 08:52]
jennifer.zeng [消息回调]
行 1: 行 1:
-====== ​实时消息回调 ======+ ====== 消息回调 ======
  
----- 
  
-===== 常用场景 =====+新版文档见：[[ccim:​rest:​setupcallback|回调功能]]。
  
-实时消息回调经常用在应用需要针对用户发送的消息进行处理的场景。比如：+消息回调，即IM服务器会在事件发生之前或之后，向客户的应用服务器发送请求，应用服务器可以据此进行必要的数据同步（发送后回调），或者根据业务需求干预事件的后续处理流程（发送前回调）。 
 + 
 +====== 回调分类 ====== 
 +从处理角度看，回调分为以下两类： 
 +  * 发送前回调：回调的主要目的在于让 App 后台可以干预该事件的处理逻辑，IM服务器会根据回调返回码和返回值确定后续处理流程。 
 +  * 发送后回调：回调的主要目的在于让 App 后台实现必要的数据同步，IM服务器忽略回调返回码。 
 + 
 +====== 1、发送前回调 ====== 
 +===== 使用场景 ===== 
 +应用服务器可以通过发送前回调实时监控用户的聊天消息，包括： 
 +  * 对聊天消息进行实时同步； 
 +  * 拦截用户的消息请求。可拦截所有类型的消息，包含文本、图片、自定义消息等； 
 +{{ :​playground:​im文档.jpg |}} 
 +===== 回调发生时机 ===== 
 +IM 服务器收到用户发送的单聊消息之后、将该消息下发给目标用户之前。 
 +===== 功能说明 ===== 
 +以下是发送前回调功能说明，在高并发可用性的基础上的使用限制说明，请按照此限制正确使用回调。 
 +  * 要启用消息回调，必须在管理后台开通消息回调服务，并配置回调规则和URL。 
 +  * 回调的方向是环信 IM 服务器向应用服务器发起 HTTPS POST 请求。 
 +  * 若同时设置了消息发送前和发送后两种回调，且消息发送前回调返回拒绝，则消息发送后回调将不会被触发。 
 +  * 发送前回调只对客户端发送的消息有效，不包含REST发送的消息。对同一个 APP 可以针对不同类型的消息（"​TEXT","​IMAGE",​ "​VIDEO","​LOCATION","​VOICE"​和"​FILE"​）做配置；规则支持选择两种以上消息类型同时回调至一个指定服务器地址，在接收到消息后，可以区分消息的类型（详情查看API文档）。 
 +  * 当环信服务器执行发送前回调后，没有返回valid状态或者返回其他错误码时，当条消息会根据默认设置处理，不会再重试；后续消息依然正常执行回调。 
 +  * 消息发送到应用服务器后，应用服务器需要返回 HTTP 应答码 200，同时返回 valid 属性，根据 valid 状态决定是否进行下发。  
 + 
 +===== 开通规则配置 ===== 
 +^配置说明 ​       ^是否必填 ​     ^内容 ​    ^ 
 +|规则名称 ​ |必填 ​  | 填写文字，支持中英文，长度限制为 32 字符。 |  
 +|会话类型 ​     |必填 ​     | * 单聊；<​html></​br></​html>​ * 群组；<​html></​br></​html> ​ * 聊天室。 ​    | 
 +|消息类型 ​   |必填 ​      ​|多选：<​html></​br></​html>​ 文本；图片；视频；位置；语音；文件；自定义消息。 | 
 +|等待响应时间 ​   |必填 ​     |后台判断超时时间，默认 200，单位为毫秒。 ​                        | 
 +|调用失败时默认策略 ​   |必填 ​  | 当您的服务器返回结果异常或等待时间内未返回结果时，消息放行或不放行。 ​ | 
 +|消息拦截报错时显示 ​   |必填 ​  | 当消息被拦截时，是否通知发送者 SDK 消息发送失败：<​html></​br></​html>​ * 报错：通知发送者 SDK 消息发送失败，发送者会感知到消息发送失败；<​html></​br></​html>​ * 不报错：不通知发送者 SDK 消息发送失败，发送者无感知。 ​     | 
 +|启用状态 ​   |必填 ​ |回调规则是否马上生效：<​html></​br></​html>​ * 启用：马上生效；<​html></​br></​html>​ * 不启用：暂不生效。<​html></​br></​html>​(建议首次创建配置为“不启用”，等您的服务器配置好验证信息后再修改为“启用”) ​        | 
 +|回调地址 ​    ​|必填 ​       |回调 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发送过来的一致，查看[[im:​server:​basics:​chatrecord#​聊天记录数据结构|消息格式文档]]|  
 +|security|签名。格式如下:​ MD5（callId+密钥+timestamp）。|  
 + 
 +**请求示例** 
 +<code json> 
 +{ 
 +    "​callId":"",​ 
 +    "​eventType":"​chat_offline",​ 
 +    "​timestamp":​0,​ 
 +    "​chat_type":"​groupchat",​  
 +    "​group_id":'',​ 
 +    "​from":"",​ 
 +    "​to":"",​ 
 +    "​msg_id":"",​ 
 +    "​payload":​{ 
 +    // 具体的消息内容 
 +    }, 
 +    "​securityVersion":"",​ 
 +    "​security":""​ 
 +} 
 +</​code>​ 
 +===== 应答包字段说明 ===== 
 +Response Body 
 +在返回值中查看data字段包含的信息 
 + 
 +^参数 ​       ^类型 ​   ^是否必需^ ​     ^描述 ​                       ^ 
 +|''​%%valid%%''​ | bool |是|根据开发者自己服务器设定的规则判断消息是否合法。 ​ | 
 +|''​%%code%%'' ​   |String ​ |否|自定义信息，字符串类型。 ​             | 
 +|''​%%payload%%''​ | Object |否 |如果需要更改消息内容可以回传修改后的内容，不修改则无需传该内容。格式同传入的消息内容，目前仅支持文本的形式，并且消息大小不能超过 1K。 | 
 + 
 +返回的结果示例： 
 +<code json> 
 +{ 
 +     "​valid":​ true, 
 +    "​code":​ "​HX:​10000",​ 
 +     "​payload":​{ 
 +    // 具体的消息内容 
 +    // 仅支持文本类型消息 
 +    }, 
 +} 
 +</​code>​ 
 +====== 2、发送后回调 ====== 
 + 
 +===== 使用场景 ===== 
 +发送后回调经常用在App后台需要实现必要的数据同步的场景。比如：
  
   * 针对客户消息的内容进行自动回复   * 针对客户消息的内容进行自动回复
-  * 在 APP 自己的服务端实时保存聊天历史+  * 在 APP 自己的服务端及时保存聊天历史
  
-__注：如果您对聊天消息没有实时性需求，可以直接通过免费的[[im:​server:​basics:​chatrecord|聊天记录拉取 REST API]] 获取聊天记录，无需使用实时消息回调。__+注：如果您对聊天消息没有时效性需求，可以直接通过免费的[[im:​server:​basics:​chatrecord|聊天记录拉取 REST API]] 获取聊天记录，无需使用发送后回调。 
 +{{ :​im:​extensions:​value:​消息回调.png |}} 
 +===== 功能说明 =====
  
-===== 开通回调 ​=====+以下是发送后回调功能说明，在高并发可用性的基础上的使用限制说明，请按照此限制正确使用回调。
  
-**实时消息回调属于增值服务，请联系环信的商务经理询问价格，付费开通。**+  ​* 消息回调属于增值服务，请联系环信商务询问价格，或者直接注册环信console账号自助付费开通。 
 +  * 消息回调开通允许用户配置提供2个回调规则配额，如果需要再增加回调规则，需要联系环信商务。 
 +  * 消息回调规则设置成功后，即刻正常使用。 
 +  * 发送后回调范围，所有上行消息有效（包含REST发送的消息），包含单聊/​群聊；如果 APP 开通了反垃圾/​敏感词过滤，被识别的消息会在服务器被拦截并禁止发送，将不会回调。 
 +  * 发送后回调接收延时，是指环信服务器接收到客户端上行消息、再将消息成功回调至客户指定服务器地址的时间间隔。''​消息接收延时保障是99.95% 的消息在30s内。''​ 
 +  * 发送后回调对同一个 APP 可以针对不同类型的消息（chat 和 chat_offline）做配置，如果 APP 同时需要 chat 和 chat_offline 两种消息，建议区分回调地址。当然，规则也可以把这两种消息同时回调至一个指定服务器地址，在接收到消息后，可以对 eventType 做判断，区分消息的类型。 
 +  * **发送后回调重试，当环信服务器执行发出回调后，响应状态码非200，认为是指定服务器有网络或者其他因素导致失败，记录一次失败，然后立即重试，若再次失败，再记录一次失败，重试失败后不会再重试。30秒内累计90次失败，会对应封禁该 APP 回调规则，5分钟后自动解封。重试失败以及封禁期间的回调不会自动补录，可以下载历史消息文件自行补充。** 
 +  * **指定服务器收到回调消息后，向环信服务器发出响应内容不能超过1000长度，如果连续发送超长的响应内容，会导致回调规则封禁，只能手动解除，需要用户手动重新设置。**
  
-APP需要提供以下配置信息： 
  
-  * 需要回调的类型，目前有两种消息类型可以回调（chat 和 chat_offline）。 +===== 开通规则配置 ​=====
-  * APP 的回调地址，环信会把消息推送到该地址上，APP 可以针对不同类型的消息配置不同的回调地址。 +
-  * （可选）APP 可以提供自己的密钥用来替换默认的密钥。（默认情况下，环信发给 APP 的数据，签名时使用的密钥是环信生成的，APP 发到环信的数据，签名时使用的密钥亦为环信生成秘钥）。+
  
-消息类型描述：+APPKEY 可以配置回调规则的数据格式，可以配置多个回调规则（默认最多开通2个规则），开通服务后才允许用户配置，[[https://​console.easemob.com|前往Console后台配置]]：
  
-  * chat 表示聊天的上行消息，这个消息跟通过 REST 导出聊天记录查询到的消息一致。比如：一个用户（u1）给另一个用户（u2）发送消息，那么就会产生一条 chat 消息，与接收方是否在线无关。接收到的消息里面 from 为 u1，to 为 u2。一个用户（u1）给一个群（g1）发送消息，那么会产生一条 ​chat 消息，接收到的消息里面 from 为 u1，to 为 g1，且返回值包含 group_id 字段。 +''​环信对回调地址http，https均支持。''​ 
-  * chat_offline 表示离线消息，APP 可以根据这个消息做 APNS 推送等个性化的推广。例如：给一个用户发送消息，如果用户不在线，那么会产生一条离线消息。如果给一个群发送消息，那么群里有几个用户不在线，就会产生几条离线消息。+^参数^说明^ 
 +|规则名称|填写唯一的规则名称(不能用中文)| 
 +|消息类型|需要回调的类型，目前有两种消息类型可以回调（chat为上行消息；chat_offline为离线消息，可以同时选择）| 
 +|回调地址| 环信会把消息推送到填写的URL地址上，可以针对不同类型的消息配置不同的回调地址。| 
 +|密钥|（可选）默认情况下，环信发给 URL（也就是您自己服务器的）的数据，签名时使用的密钥是环信生成的，Console后台可查看。如果您想提供自己的密钥用来替换默认的，可以联系商务沟通|
  
-chat_type的选择： 
  
-  * 如果APP只需要用户的聊天记录，那么配置chat类型消息的回调即可。 +=== chat 上行消息 ​===
-  * 如果APP只需要针对离线消息做APNS推送等推广，那么配置chat_offline类型的消息回调即可。 +
-  * 如果APP同时需要用户的聊天记录也需要针对离线消息做处理，那么需要配置chat和chat_offline两种类型的消息回调。+
  
-===== 消息回调接口参数说明 =====+这个消息跟通过 REST 导出聊天记录查询到的消息一致。比如：一个用户（u1）给另一个用户（u2）发送消息，那么就会产生一条 chat 消息，与接收方是否在线无关。接收到的消息里面 from 为 u1，to 为 u2。一个用户（u1）给一个群（g1）发送消息，那么会产生一条 chat 消息，接收到的消息里面 from 为 u1，to 为 g1，且返回值包含 group_id 字段。
  
-目前只支持 HTTP 方式的回调，采用 POST 方式，正文部分为 JSON 格式的字符串，字符集为 UTF-8。+=== chat_offline 离线消息 ===
  
-回调时，会对发送的正文做 MD5 签名，APP 返回的响应也需要做 MD5 签名。环信这边 MD5 使用的是''​org.apache.commons.codec.digest.DigestUtils#​md5Hex''​。+APP 可以根据这个消息做 APNS 推送等个性化的推广。例如：给一个用户发送消息，如果用户不在线，那么会产生一条离线消息。如果给一个群发送消息，那么群里有几个用户不在线，就会产生几条离线消息，那么这几条离线消息的to为接收消息用户的id，并不是群组id。
  
-APP 的响应内容不能超过1000个字符。+=== chat_type的选择 ===
  
-==== 回调的正文 ====+  * 如果APP只需要用户的聊天记录，那么配置chat类型消息的回调即可。 
 +  * 如果APP只需要针对离线消息做APNS推送等推送，那么配置chat_offline类型的消息回调即可。 
 +  * 如果APP同时需要用户的聊天记录也需要针对离线消息做处理，那么需要同时配置chat和chat_offline两种类型的消息回调。
  
-<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为654321，以后会改成Console后台做设置 +
-} +
-</​code>​+
  
-==== Payload 数据格式说明 ====+目前支持 HTTP/HTTPS 方式的回调，采用 POST 方式，正文部分为 JSON 格式的字符串，字符集为 UTF-8。
  
-详情可参见：[[im:​server:​basics:​messages|发送消息]]。+回调时，会对发送的正文做 MD5 签名。环信这边 MD5 使用的是''​org.apache.commons.codec.digest.DigestUtils#​md5Hex''​。
  
-<code json> +APP 的响应内容不能超过1000个字符。
-{ +
-     "​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|每个回调的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+密钥+timestamp）。|
 +
 +===回调成功返回的示例===
 <code json> <code json>
 { {
-    "​callId":"",​//​与环信推送的一致 +    "​callId":"",​ 
-    "accept":"​true",//​表明接受了此推送 +    "eventType":"​chat_offline", 
-    "reason":"",​//​可选，accept为false时使用 +    "timestamp":0, 
-    "security":""//​签名。格式如下:​ MD5（callId+约定的key+"true"），约定key为654321+    ​"chat_type":"​groupchat",  
 +    "group_id":'',​ 
 +    ​"from":"",​ 
 +    "​to":"",​ 
 +    "​msg_id":"",​ 
 +    "​payload":​{ 
 +    ​// 具体的消息内容 
 +    }, 
 +    "​securityVersion":"",​ 
 +    "​security":​""​
 } }
 </​code>​ </​code>​
  
-===== 注意事项 ​===== +[[im:​server:​basics:​chatrecord#​聊天记录数据结构|Payload 数据格式说明]]。 
- +===== 应答包字段说明 ​=====
-  * APP 服务器接收到消息时，需要做签名校验，以保证消息的安全性。 +
-  * 同一个 APP 可以针对不同类型的消息（chat 和 chat_offline）做配置，如果 APP 同时需要 chat 和 chat_offline 两种消息，那么最好区分回调地址。当然，APP 也可以把这两种消息的回调地址配置成一个，那么需要 APP 在接收到消息的时候，对 eventType 做判断，区分消息是属于哪种类型的。 +
-  * **APP 服务器接到回调消息后的响应内容不能超过1000个字符，如果连续发送超长消息会导致回调接口被封禁。接收回调消息的 APP 服务器需要保证回调接口高并发下的可用性，如果接收回调消息时出现504错误等，页面会因为响应消息过长而停止回调。** +
- +
- +
----- +
-<WRAP group> +
-<WRAP half column>​ +
-上一章节：[[im:​linux:​integration|Linux SDK集成]] +
-</​WRAP>​ +
- +
-<WRAP half column>​ +
-下一页：[[im:​extensions:​value:​multidevice|多设备同步]] +
-</​WRAP>​ +
-</​WRAP>​+
  
 +环信不验证回调响应的response内容，只要您服务器给我们返回http状态码是200即可。