Merge pull request #1078 from haoxiuwen/doc-v2

haoxiuwen · web-flow · commit 7254eca104b3 · 2024-12-10T10:06:46.000+08:00
Modify RESTful API &amp; Callback Configuration
diff --git a/docs/.vuepress/sidebar/document.ts b/docs/.vuepress/sidebar/document.ts
@@ -431,7 +431,9 @@ const documentSidebar = [
   {
     text: '设置回调',
     children: [
-      { text: '设置回调', link: 'callback.html' },
+      { text: '回调概述', link: 'callback_overview.html' },
+      { text: '发送前回调', link: 'callback_presending.html' },
+      { text: '发送后回调', link: 'callback_postsending.html' },
       { text: '发送后回调事件',
         collapsible: true,
         children: [
diff --git a/docs/README.md b/docs/README.md
@@ -1211,7 +1211,7 @@ projects:
         icon: /feature/others.svg
         contexts:
           - text: 回调
-            link: /document/server-side/callback.html
+            link: /document/server-side/callback_overview.html
           - text: 错误码
             desc: SDK 中的接口和 REST 接口调用或者回调中的错误码。
             sdks:
diff --git a/docs/document/android/releasenote.md b/docs/document/android/releasenote.md
@@ -46,7 +46,7 @@
   
 ### 优化
  
-- [IM SDK] [发送前回调](/document/server-side/callback.html#_1、发送前回调)时修改的[消息扩展字段](/document/android/message_send_receive.html#使用消息扩展字段)，会同步到发送方。
+- [IM SDK] [发送前回调](/document/server-side/callback_presending.html)时修改的[消息扩展字段](/document/android/message_send_receive.html#使用消息扩展字段)，会同步到发送方。
 - [IM SDK] 调用[删除服务端会话 API](conversation_delete.html#单向删除服务端会话及本地会话)，成功后会删除本地会话。之前版本调用该接口可设置删除会话的本地消息，不能删除本地会话。
 - [IM SDK] 适配 Android 15 的 16K page size。
 - [IM SDK] 群组和聊天室操作的默认错误码提示由 `GROUP_MEMBERS_FULL`（604）和 `CHATROOM_MEMBERS_FULL`（704）调整为 `GROUP_PERMISSION_DENIED`（603）和 `CHATROOM_PERMISSION_DENIED`（703）。例如，群组普通成员设置群组管理员时，由于缺乏权限，会提示 603 错误。
@@ -551,7 +551,7 @@
 
 - [IM SDK] 新增群组详情中群组禁用状态：[EMGroup#isDisabled()](https://sdkdocs.easemob.com/apidoc/android/chat3.0/classcom_1_1hyphenate_1_1chat_1_1_e_m_group.html#acd072d7fc16e6ff89110173979ed318b) 属性，该属性需要开发者在服务端设置；
 - [IM SDK] 优化遇到连接问题时更新接入点的策略，增强可用性；
-- [IM SDK] [发送前回调](/document/server-side/callback.html#_1、发送前回调)：发送失败时返回给 app 用户的错误描述中增加你自定义的错误信息（即 [响应体参数](/document/server-side/callback.html#响应体参数) code 信息）。
+- [IM SDK] [发送前回调](/document/server-side/callback_presending.html)：发送失败时返回给 app 用户的错误描述中增加你自定义的错误信息（即 [响应体参数](/document/server-side/callback_presending.html#响应-body) code 信息）。
 - [IM SDK] 在 [EMError](https://sdkdocs.easemob.com/apidoc/android/chat3.0/classcom_1_1hyphenate_1_1_e_m_error.html) 中新增错误码 1101：[EMError#PRESENCE_CANNOT_SUBSCRIBE_YOURSELF](https://sdkdocs.easemob.com/apidoc/android/chat3.0/classcom_1_1hyphenate_1_1_e_m_error.html#abc9130b164d5cccb3559585ec38e8e99)，用来提示用户不能订阅自己的在线状态。
 
 ### 优化：
diff --git a/docs/document/ios/releasenote.md b/docs/document/ios/releasenote.md
@@ -75,7 +75,7 @@ end
   
 ### 优化
  
-- [IM SDK] [发送前回调](/document/server-side/callback.html#_1、发送前回调)时修改的[消息扩展字段](/document/android/message_send_receive.html#使用消息扩展字段)，会同步到发送方。
+- [IM SDK] [发送前回调](/document/server-side/callback_presending.html)时修改的[消息扩展字段](/document/android/message_send_receive.html#使用消息扩展字段)，会同步到发送方。
 - [IM SDK] 调用[删除服务端会话 API](conversation_delete.html#单向删除服务端会话及其历史消息)，成功后会删除本地会话。之前版本调用该接口可设置删除会话的本地消息，不能删除本地会话。
 - [IM SDK] 群组和聊天室操作的默认错误码提示由 `EMErrorGroupMembersFull`（604）和 `EMErrorChatroomMembersFull`（704）调整为 `EMErrorGroupPermissionDenied`（603）和 `EMErrorChatroomPermissionDeniedD`（703）。例如，群组普通成员设置群组管理员时，由于缺乏权限，会提示 603 错误。
 
diff --git a/docs/document/server-side/callback.md b/docs/document/server-side/callback.md
diff --git a/docs/document/server-side/callback_group_ban.md b/docs/document/server-side/callback_group_ban.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要群组封禁或解禁的回调事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
  
 ## 回调时机
diff --git a/docs/document/server-side/callback_group_block.md b/docs/document/server-side/callback_group_block.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果你需要屏蔽/解除屏蔽群组的事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
 
 ## 屏蔽群组
diff --git a/docs/document/server-side/callback_group_room_admin.md b/docs/document/server-side/callback_group_room_admin.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要添加/删除群组/聊天室管理员事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
 
 ## 添加管理员
diff --git a/docs/document/server-side/callback_group_room_allowlist.md b/docs/document/server-side/callback_group_room_allowlist.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要将群组/聊天室成员加入或移出白名单的事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
 
 ## 将成员加入白名单
diff --git a/docs/document/server-side/callback_group_room_announcement.md b/docs/document/server-side/callback_group_room_announcement.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要群组/聊天室公告事件的回调事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
 
 ## 回调时机
diff --git a/docs/document/server-side/callback_group_room_blocklist.md b/docs/document/server-side/callback_group_room_blocklist.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要群组/聊天室成员被加入/移出黑名单事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
 
 ## 将成员加入黑名单
diff --git a/docs/document/server-side/callback_group_room_create.md b/docs/document/server-side/callback_group_room_create.md
@@ -4,7 +4,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要创建群组/聊天室的回调事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
  
 ## 回调时机
diff --git a/docs/document/server-side/callback_group_room_delete.md b/docs/document/server-side/callback_group_room_delete.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要群组/聊天室解散的回调事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
  
 ## 回调时机
diff --git a/docs/document/server-side/callback_group_room_info.md b/docs/document/server-side/callback_group_room_info.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要群组/聊天室信息更新的回调事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
  
 ## 回调时机
diff --git a/docs/document/server-side/callback_group_room_join.md b/docs/document/server-side/callback_group_room_join.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要群组/聊天室加人的回调事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
 
 ## 直接加入
diff --git a/docs/document/server-side/callback_group_room_leave.md b/docs/document/server-side/callback_group_room_leave.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要群组/聊天室成员离开的回调事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
 
 ## 主动退出
diff --git a/docs/document/server-side/callback_group_room_mute.md b/docs/document/server-side/callback_group_room_mute.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要将群组或聊天室成员添加或移出禁言列表的事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
 
 ## 将成员加入禁言列表
diff --git a/docs/document/server-side/callback_group_room_muteall.md b/docs/document/server-side/callback_group_room_muteall.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要群组/聊天室全员禁言或解除禁言的事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
 
 ## 全员禁言/解除全员禁言
diff --git a/docs/document/server-side/callback_group_room_owner.md b/docs/document/server-side/callback_group_room_owner.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要变更群主或聊天室所有者的回调事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
  
 ## 回调时机
diff --git a/docs/document/server-side/callback_group_shared_file.md b/docs/document/server-side/callback_group_shared_file.md
@@ -5,7 +5,7 @@
 :::tip
 1. 你所使用的环信即时通讯 IM 的版本可能需要单独开通回调服务，详见[增值服务说明](/product/pricing.html#增值服务费用)。
 2. 如果需要上传或删除群组共享文件的回调事件，你需要在[环信控制台](https://console.easemob.com/user/login)设置发送后回调规则，详见[配置回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
-3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback.html)。
+3. 发送后回调的相关介绍，详见[回调说明](/document/server-side/callback_postsending.html)。
 :::
 
 ## 群组共享文件上传事件
diff --git a/docs/document/server-side/callback_overview.md b/docs/document/server-side/callback_overview.md
@@ -0,0 +1,58 @@
+# 回调功能
+
+<Toc />
+
+## 概述
+
+环信即时通讯云支持回调功能，即会在事件发生之前或之后，环信 IM 服务器会以 HTTP POST 请求的形式向你的应用服务器发送通知。根据是否干预消息投递，回调分为两类：
+
+- **发送前回调**：旨在让 app 后台干预该事件的处理逻辑，环信服务器会根据响应中的返回值确定后续处理流程。**该类回调仅适用于从你的客户端应用发送的消息。**
+
+  该类回调一般是对用户发送的消息内容的处理，典型的应用场景为内容审核：当环信服务器收到来自客户端应用的消息时，会向你的应用服务器发送请求并等待响应，从而决定是否通过或拒绝消息投递。
+
+- **发送后回调**：旨在让 app 后台实现必要的数据同步，环信服务器忽略回调返回码。
+
+  发送后回调包括发送消息、发送消息已读回执、进行群组或聊天室操作、好友关系操作和用户状态变化等事件，详见[发送后回调过滤规则设置](/product/enable_and_configure_IM.html#配置回调规则)。
+
+使用回调功能前，请查看你的产品套餐是否支持，详见[增值服务说明](/product/pricing.html#增值服务费用)。若不支持，你需首先在[环信即时通讯云控制台](https://console.easemob.com/user/login)[开通该功能](/product/enable_and_configure_IM.html#开通消息回调)，然后[配置发送前回调规则发送后回调规则](/product/enable_and_configure_IM.html#配置回调规则)。
+
+:::tip
+若使用了一段时间回调功能后需要将其关闭，请联系环信商务。关闭该功能会导致回调所有相关配置删除，请谨慎操作。
+:::
+
+## 两类回调的区别
+
+| 类别       | 发送前回调 | 发送后回调            |
+| ---------- | ---------- | ---------------------- |
+| 支持的消息发送方式 | 客户端 SDK | 客户端 SDK 和 RESTful API | 
+| 支持的范围 | 仅限消息   | 消息和其他事件         |
+| 发生的时间  | 环信服务器收到用户发送的上行单聊和群聊消息之后、且将该消息下发给目标用户之前   | 发送消息后或进行单聊、群聊、聊天室、联系人等相关的操作后  |
+| 是否需要响应   | 是       | 否                    |
+| 典型用例   | 内容审核   | 聊天记录同步           |
+
+## 回调安全
+
+对于发送前和发送后回调，环信服务器会向你的应用服务器发送带有 JSON 负载的 HTTP/HTTPS POST 请求。请求采用 UTF-8 编码，每个请求中的消息都使用 MD5 签名。在每个请求头中，`Content-Type` 字段为 `application/json`。
+
+对于发送后回调，请求中的消息使用通过 `org.apache.commons.codec.digest.DigestUtils#md5Hex` 计算的 MD5 签名。
+
+你可以通过以下步骤验证签名检查回调是否从环信服务器发送：
+
+1. 查找以下信息：
+
+   - 回调 ID：回调请求体中的 `callId` 参数。
+
+   - 环信服务器为回调规则生成的 secret：你可以在[环信即时通讯云控制台](https://console.easemob.com/user/login)的**消息回调**页面的回调规则列表中查看。
+
+     ![img](1.png)
+
+   - 回调时间戳：回调请求体中的时间戳参数。
+
+2. 计算回调 ID、secret、回调时间戳拼接后的字符串的 MD5 值。
+
+3. 检查计算的值是否与请求体中的 secret 参数相同。若相同，则表示该回调请求由环信服务器发送。
+
+
+
+
+
diff --git a/docs/document/server-side/callback_postsending.md b/docs/document/server-side/callback_postsending.md
diff --git a/docs/document/server-side/callback_presending.md b/docs/document/server-side/callback_presending.md
diff --git a/docs/document/server-side/callback_room_superadmin.md b/docs/document/server-side/callback_room_superadmin.md
diff --git a/docs/document/server-side/message_download.md b/docs/document/server-side/message_download.md
diff --git a/docs/document/server-side/message_import.md b/docs/document/server-side/message_import.md
diff --git a/docs/private/im/uc_configure.md b/docs/private/im/uc_configure.md
diff --git a/docs/product/moderation/moderation_record_callback.md b/docs/product/moderation/moderation_record_callback.md
diff --git a/docs/product/pricing.md b/docs/product/pricing.md
