Merge pull request #525 from haoxiuwen/doc-v2

Modify IM Docs

docs/document/flutter/thread_message.md

@@ -47,13 +47,14 @@
 
 ```dart
 // `chatThreadId` 为子区 ID
+
 EMMessage msg = EMMessage.createTxtSendMessage(
-  chatThreadId: threadId,
+  targetId: threadId,
   content: content,
+  // `chatType` 设置为 `GroupChat`，即群聊
+  chatType: ChatType.GroupChat,
 );
-// `chatType` 设置为 `GroupChat`，即群聊
-msg.chatType = ChatType.GroupChat;
-// isChatThreadMessage: 是否是子区消息，这里设置为 `true`，即是子区消息
+// isChatThreadMessage: 是否是子区消息，这里设置为 `true`，即是子区消息。
 msg.isChatThreadMessage = true;
 EMClient.getInstance.chatManager.sendMessage(msg);
 ```
@@ -160,8 +161,8 @@ try {
   String threadId = "threadId";
   // 会话类型，即群聊 `GroupChat`。
   EMConversationType convType = EMConversationType.GroupChat;
-  EMConversation? conversation = await EMClient.getInstance.chatManager
-      .getConversation(threadId, type: convType);
+  EMConversation? converrsation =
+        await EMClient.getInstance.chatManager.getThreadConversation(threadId);
   // 搜索的起始消息 ID。
   String startMsgId = "startMsgId";
   // 每页期望获取的消息数量。

docs/document/server-side/callback.md

@@ -10,7 +10,7 @@
 
 从处理角度看，回调分为以下两类：
 
-- 发送前回调：回调的主要目的在于让 app 后台可以干预该事件的处理逻辑，环信 IM 服务器会根据回调返回码和返回值确定后续处理流程；
+- 发送前回调：回调的主要目的在于让 app 后台可以干预该事件的处理逻辑，环信 IM 服务器会根据响应中的返回值确定后续处理流程；
 - 发送后回调：回调的主要目的在于让 app 后台实现必要的数据同步，环信 IM 服务器忽略回调返回码。
 
 ## 1、发送前回调
@@ -19,10 +19,7 @@
 
 **发送前回调只对客户端发送的消息有效，不包含 REST API 发送的消息。**
 
-应用服务器可以通过发送前回调实时监控用户的聊天消息，包括：
-
-- 对聊天消息进行实时同步；
-- 拦截用户的消息请求。可拦截所有类型的消息，包含文本、图片、自定义消息等；
+应用服务器可以通过发送前回调实时监控用户的聊天消息，对消息进行处理，例如，拦截用户的消息请求。可拦截所有类型的消息，包含文本、图片、自定义消息等；
 
 ![](@static/images/server-side/im-callback.jpeg)
 
@@ -37,7 +34,7 @@
 - 回调的方向是环信 IM 服务器向应用服务器发起 HTTP/HTTPS POST 请求。
 - 若同时设置了消息发送前和发送后两种回调，且消息发送前回调返回拒绝，则消息发送后回调将不会被触发。
 - 对同一个 app，可以针对不同类型的消息（“TEXT”，“IMAGE”，“VIDEO”，“LOCATION”，“VOICE” 和 ”FILE”）做配置；规则支持选择两种以上消息类型同时回调至一个指定服务器地址，接收到消息后，你可以区分消息的类型以便进行分类处理。详见 [消息管理 REST API](message_single.html)。
-- 环信 IM 服务器执行发送前回调后，如果你的应用服务器没有返回 valid 状态或者返回其他错误码，该条消息会根据默认设置（console 后台发送前回调中 ”调用失败时默认策略”）处理，不会再重试；后续消息依然正常执行回调。
+- 环信 IM 服务器执行发送前回调后，如果你的应用服务器没有返回 valid 状态或者未收到应答包，该条消息会根据默认设置（console 后台发送前回调中 ”调用失败时默认策略”）处理，不会重试；后续消息依然正常执行回调。
 - 消息发送到你的应用服务器后，应用服务器需返回 HTTP 响应码 200 和 valid 属性，根据 valid 状态决定是否进行下发。
 
 ### 实现步骤
@@ -56,26 +53,28 @@
 
 #### 请求 body
 
-| 参数              | 类型                                                                                                                               |
-| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
-| `callId`          | `callId` 为 `{appkey}_{uuid}`，其中 `uuid` 为随机生成，作为每条回调的唯一标识。                                                    |
-| `timestamp`       | 环信 IM 服务器接收到此消息的时间戳。                                                                                               |
-| `chat_type`       | `chat` 单聊回调、`groupchat` 群聊回调包含了群组和聊天室的消息回调，默认全选。                                                      |
-| `group_id`        | 回调消息所在的群组。群聊消息回调才有此参数。                                                                                       |
-| `from`            | 消息的发送方。                                                                                                                     |
-| `to`              | 消息的接收方。                                                                                                                     |
-| `msg_id`          | 消息的 ID。                                                                                                                        |
-| `payload`         | 消息内容，与通过 REST API 发送过来的一致，查看 [消息格式文档](message_historical.html#历史消息记录的内容)。                                   |
-| `securityVersion` | 安全校验版本，目前为 1.0.0。忽略此参数，以后会改成 Console 后台做设置。                                                            |
+| 参数              | 类型    |
+| :---------------- | :--------------------------------------- |
+| `callId`          | `callId` 为 `{appkey}_{uuid}`，其中 `uuid` 为随机生成，作为每条回调的唯一标识。  |
+| `timestamp`       | 环信 IM 服务器接收到此消息的时间戳。       |
+| `chat_type`       | `chat` 单聊回调、`groupchat` 群聊回调包含了群组和聊天室的消息回调，默认全选。|
+| `group_id`        | 回调消息所在的群组或聊天室。该参数仅对群组聊天或聊天室中的消息回调生效。        |
+| `from`            | 消息的发送方。      |
+| `to`              | 消息的接收方。该参数仅对单聊生效。  |
+| `msg_id`          | 消息的 ID。   |
+| `payload`         | 消息内容，与通过 REST API 发送过来的一致，查看 [消息格式文档](message_historical.html#历史消息记录的内容)。      |
+| `securityVersion` | 安全校验版本，目前为 1.0.0。忽略此参数，以后会改成 Console 后台做设置。   |
 | `security`        | 签名，格式如下: MD5（callId+Secret+timestamp）。Secret 见 [环信即时通讯云控制台](https://console.easemob.com/user/login)回调规则。 |
 
 #### 响应 body
 
+响应内容不能超过 1,000 个字符，否则环信服务器会认为是攻击，导致回调失败。
+
 | 参数      | 类型   | 是否必需<div style="width: 80px;"></div> | 描述      |
 | :-------- | :----- | :----------------- | :----------- |
 | `valid`   | bool   | 是   | 根据开发者自己服务器设定的规则判断消息是否合法。   |
-| `code`    | String | 否    | 自定义的客户端错误描述。环信控制台上的**发送前回调**页面中的**消息拦截报错时显示**设置为**报错** 时，该 `code` 的内容为客户端提示的错误。`code` 分为以下几种情况：<br/> - 若 `code` 的内容为字符串类型，客户端上显示的错误为该参数的内容；<br/> - 响应中不包含 `code` 字段， 客户端上显示 `custom logic denied` 错误；<br/> - 若 `code` 为空字符串，移动客户端提示 `Message blocked by external logic` 错误；<br/> - 若在指定时间内未收到应答包，则按默认配置处理，客户端上提示 `custom internal error` 错误；<br/> - 如果返回的应答包出现错误，包括缺少必填字段或字段类型不符合约定类型，客户端上提示 `custom internal error` 错误。|
-| `payload` | Object | 否   | 若无需修改消息内容，**请勿传该参数**。<br/>若需要更改消息内容可以回传修改后的内容，格式同传入的消息内容。目前仅支持文本的形式，并且消息大小不能超过 1K。       |
+| `code`    | String | 否    | 客户端上报的自定义发送前回调错误。环信控制台上的**发送前回调**页面中的**消息拦截报错时显示**设置为**报错** 时，该 `code` 的内容为客户端提示的错误。错误分为以下几种情况：<br/> - 若 `code` 的内容为字符串类型，客户端上的错误为该参数的内容；<br/> - 响应中不包含 `code` 字段， 客户端提示 `custom logic denied`；<br/> - 若 `code` 为空字符串，移动客户端提示 `Message blocked by external logic` 错误；<br/> - 若在指定时间内未收到应答包，则按默认配置处理，客户端提示 `custom internal error` 错误；<br/> - 如果返回的应答包出现错误，包括缺少必填字段 `valid` 或字段类型不符合约定类型，客户端提示 `custom internal error` 错误。|
+| `payload` | Object | 否   | 修改后的消息内容。若无需修改消息内容，**请勿传该参数**。<br/>若需要更改消息内容可以回传修改后的内容，格式同传入的消息内容。目前仅支持文本的形式，并且消息大小不能超过 1 KB。       |
 
 ### 示例
 
@@ -135,7 +134,7 @@
 - 发送后回调范围，所有聊天消息有效（包含通过 SDK 和 REST API 发送的消息），包含单聊/群聊；如果 app 开通了反垃圾/敏感词过滤，被识别的消息会在服务器被拦截并禁止发送，将不会回调。
 - 发送后回调接收延时，是指消息服务器接收到客户端聊天消息、再将消息成功回调至客户指定服务器地址的时间间隔。消息接收延时保障是 99.95% 的消息在 30s 内。
 - 发送后回调对同一个 app 可以针对不同类型的消息（聊天消息、离线消息和通过 REST API 发送的消息）进行配置，如果 app 同时需要聊天消息和离线消息两种消息，建议区分回调地址。当然，规则也可以把这两种消息同时回调至一个指定服务器地址，在接收到消息后，可以对 eventType 做判断，区分消息的类型。
-- **发送后回调重试，当环信服务器执行发出回调后，响应状态码非 200，认为是指定服务器无网络、超过 10 秒或者其他因素导致失败，记录一次失败，然后立即重试，若再次失败，再记录一次失败；针对一条回调仅重试一次，重试失败后即丢弃。若开通了[补发回调存储信息功能](#补发回调存储信息接口描述)，则将消息放入异常存储中。若 30 秒内累计 90 次失败，会封禁该 app 的回调规则，5 分钟后自动解封。重试失败以及封禁期间的回调不会自动补录，可以下载历史消息记录自行补充。**
+- **发送后回调重试，当环信服务器执行发出回调后，响应状态码非 200，则认为回调失败，然后立即重试，若再次失败，再记录一次失败；针对一条回调仅重试一次，重试失败后即丢弃。若开通了[补发回调存储信息功能](#补发回调存储信息接口描述)，则将消息放入异常存储中。若 30 秒内累计 90 次失败，会封禁该 app 的回调规则，5 分钟后自动解封。重试失败以及封禁期间的回调不会自动补录，可以下载历史消息记录自行补充。**
 - 指定服务器收到回调消息后，向消息服务器发出响应内容不能超过 1,000 字符长度，如果连续发送超长的响应内容，会导致回调规则封禁，只能手动解除，需要用户手动重新设置。
 - 客户有特殊需求不能丢失回调消息的情况下，请联系环信商务经理开通回调异常缓存功能，并使用 [查询回调异常缓存](#查询回调储存详情接口描述) 和 [补发回调储存信息](#补发回调存储信息接口描述) 接口。
 
@@ -248,9 +247,9 @@ app 的响应内容不能超过 1,000 个字符，否则环信服务器会认为
 | `duration`        | long   | 请求耗时，单位为毫秒。                                                         |
 | `applicationName` | string | 你在环信 IM 管理后台注册的 App 名称。                                          |
 | `data`            | object | 响应数据内容。包括以下三个参数：`date`、`size` 和 `retry`。                    |
-| `date`            | String | 代表本次可以发送的补发的一个十分钟 date key，key 为十分钟的起点。              |
-| `size`            | Int    | 本时段消息数量。                                                               |
-| `retry`           | Int    | 开发者已经重试补发的次数。考虑到补发也可能失败，服务器会继续存储。最开始是 0。 |
+| - `date`            | String | 当前的 date key，即每 10 分钟内的消息和事件。key 为 10 分钟的起点。              |
+| - `size`            | Int    | 该 date key 内的消息数量。                                                               |
+| - `retry`           | Int    | 该 date key 内的数据已经重试补发的次数。未重试时值为 `0`。 |
 
 #### 请求示例