Merge pull request #1066 from haoxiuwen/doc-v2

Modify Post-Sending Callback Events
easemob · Nov 29, 2024 · 92f8a28 · 92f8a28
2 parents cbc53c9 + 33a5296
commit 92f8a28
Show file tree

Hide file tree

Showing 35 changed files with 2,929 additions and 1,318 deletions.
diff --git a/docs/.vuepress/sidebar/document.ts b/docs/.vuepress/sidebar/document.ts
@@ -415,7 +415,7 @@ const documentSidebar = [
     children: [
       { text: 'Java Server SDK 2.0', link: 'java_server_sdk_2.0.html' },
       { text: 'Java Server SDK 1.0', link: 'java_server_sdk.html' },
-      { text: 'PHP Server SDK', link: 'php_server_sdk.html' },
+      { text: 'PHP Server SDK', link: 'php_server_sdk.html' }
     ],
     only: ['server-side']
   },
@@ -430,7 +430,47 @@ const documentSidebar = [
     text: '设置回调',
     children: [
       { text: '设置回调', link: 'callback.html' },
-      { text: '发送后回调-事件回调', link: 'callback_configurations.html' }
+      { text: '发送后回调事件',
+        collapsible: true,
+        children: [
+          { text: '用户登入/登出', link: 'callback_login_logout.html' },
+          { text: '发送消息', link: 'callback_message_send.html' },
+          { text: '发送单聊消息已读回执', link: 'callback_single_read_ack.html' },
+          { text: '撤回消息', link: 'callback_message_recall.html' },
+          { text: '群组/聊天室操作（新）', 
+            collapsible: true,
+            children: [
+              { text: '创建群组/聊天室', link: 'callback_group_room_create.html' },
+              { text: '更新群组/聊天室',
+                collapsible: true,
+                children: [
+                  { text: '更新群组_聊天室信息', link: 'callback_group_room_info.html' },
+                  { text: '变更群主/聊天室所有者', link: 'callback_group_room_owner.html' },
+                  { text: '设置/更新公告', link: 'callback_group_room_announcement.html' },
+                  { text: '封禁/解禁群组', link: 'callback_group_ban.html' },
+                  { text: '全员禁言', link: 'callback_group_room_muteall.html' }
+                ]
+              },
+              { text: '删除群组/聊天室', link: 'callback_group_room_delete.html' },
+              { text: '屏蔽/解除屏蔽群组', link: 'callback_group_block.html' },
+              { text: '上传/删除群共享文件', link: 'callback_group_shared_file.html' },
+              { text: '用户加入', link: 'callback_group_room_join.html' },
+              { text: '成员离开', link: 'callback_group_room_leave.html' },
+              { text: '添加/移除管理员', link: 'callback_group_room_admin.html' },
+              { text: '加入/移出禁言列表', link: 'callback_group_room_mute.html' },
+              { text: '添加/移出白名单', link: 'callback_group_room_allowlist.html' },
+              { text: '加入/移出黑名单', link: 'callback_group_room_blocklist.html' },
+              { text: '添加/移除聊天室超级管理员', link: 'callback_room_superadmin.html' }
+            ]
+          },
+          { text: '群组/聊天室操作（旧）', link: 'callback_group_room_old.html' },
+          { text: '用户关系操作', link: 'callback_contact.html' },
+          { text: '离线推送', link: 'callback_offline_push.html' },
+          { text: 'Reaction', link: 'callback_reaction.html' },
+          { text: 'Thread', link: 'callback_thread.html' },
+          { text: '敏感词监测', link: 'callback_sensitive_word.html' }
+        ]
+      }
     ],
     only: ['server-side']
   }

diff --git a/docs/document/server-side/callback_contact.md b/docs/document/server-side/callback_contact.md
@@ -0,0 +1,244 @@
+# 好友关系操作
+
+| 事件                  | payload 中类型                 | 触发事件             |
+| :-------------------- | :----------------------------- | :------------------- |
+| `roster`                | -                              | 好友关系操作所有事件 |
+| `roster:add`            | `{“operation”:“add”}`           | 添加好友             |
+| `roster:remove`         | `{“operation”:“remove”}`         | 删除好友             |
+| `roster:accept`         | `{“operation”:“accept”}`         | 同意好友申请。对方用户收到该事件。         |
+| `roster:decline`        | `{“operation”:“decline”}`        | 拒绝好友申请。对方用户收到该事件。       |
+| `roster:ban`            | `{“operation”:“ban”}`           | 拉黑好友             |
+| `roster:allow`          | `{“operation”:“allow”}`          | 解除拉黑好友         |
+
+## 添加好友
+
+payload 字段含义：
+
+| 字段        | 数据类型 | 含义              |
+| :---------- | :------- | :---------------- |
+| `reason`    | object   | /                 |
+| `operation` | String   | `add`：添加好友。 |
+
+payload 之外的字段如下表所示：
+
+| 字段     | 数据类型 | 含义                                                         |
+| :------- | :------- | :----------------------------------------------------------- |
+| `callId`    | String   | `callId` 为每个回调请求的唯一标识，格式为 “App Key_添加好友事件的消息 ID”。 | 
+| `msg_id`    | String   | 添加好友事件的消息 ID。 | 
+
+payload 示例：
+
+```json
+{
+    "chat_type":"roster",
+    "callId":"XXXX#XXXX",
+    "security":"XXXX",
+    "payload":{
+        "reason":"",
+        "operation":"add"
+        },
+    "host":"XXXX",
+    "appkey":"XXXX#XXXX",
+    "from":"XXXX#XXXX",
+    "to":"tst01",
+    "eventType":"chat",
+    "msg_id":"9XXXX2",
+    "timestamp":1642648175092
+    }
+```
+
+## 删除好友
+
+payload 字段含义：
+
+| 字段         | 数据类型 | 含义                 |
+| :----------- | :------- | :------------------- |
+| `roster_ver` | String   | 好友列表的版本号。   |
+| `operation`  | String   | `remove`：移除好友。 |
+
+payload 之外的字段如下表所示：
+
+| 字段     | 数据类型 | 含义                                                         |
+| :------- | :------- | :----------------------------------------------------------- |
+| `callId`    | String   | `callId` 为每个回调请求的唯一标识，格式为 “App Key_删除好友事件的消息 ID”。 | 
+| `msg_id`    | String   | 删除好友事件的消息 ID。 | 
+
+payload 示例：
+
+```json
+{
+    "chat_type":"roster",
+    "callId":"XXXX#XXXX736",
+    "security":"2e7XXXX2d7",
+    "payload":{
+        "roster_ver":"003DD920ADD15B51EB0B806E83BDD97F089B0092",
+        "operation":"remove"
+        },
+    "host":"XXXX",
+    "appkey":"XXXX#XXXX",
+    "from":"XXXX#XXXX",
+    "to":"tst01",
+    "eventType":"chat",
+    "msg_id":"XXXX463736",
+    "timestamp":1642648138571
+    }
+```
+
+## 同意好友申请
+
+用户发送好友申请后，对方用户同意加好友后会收到服务器发送的该事件。
+
+payload 字段含义：
+
+| 字段         | 数据类型 | 含义                     |
+| :----------- | :------- | :----------------------- |
+| `roster_ver` | String   | 好友列表的版本号。       |
+| `operation`  | String   | `accept`：同意好友申请。 |
+
+payload 之外的字段如下表所示：
+
+| 字段     | 数据类型 | 含义                                                         |
+| :------- | :------- | :----------------------------------------------------------- |
+| `callId`    | String   | `callId` 为每个回调请求的唯一标识，格式为 “App Key_同意好友申请事件的消息 ID”。 | 
+| `msg_id`    | String   | 同意好友申请事件的消息 ID。 | 
+
+回调请求示例：
+
+```json
+{
+    "chat_type":"roster",
+    "callId":"XXXX#XXXX_966725899779049516",
+    "security":"a2e1545231e8acf60513b50984af0c6c",
+    "payload":{
+        "roster_ver":"DD6E14FE5EE5A9ABC52CA86C5DE1601CF729BFD6",
+        "operation":"accept"
+        },
+    "host":"XXXX",
+    "appkey":"XXXX#XXXX",
+    "from":"XXXX#XXXX",
+    "to":"tst01",
+    "eventType":"chat",
+    "msg_id":"96XXXX516",
+    "timestamp":1642648213494
+    }
+```
+
+## 拒绝好友申请
+
+用户发送好友申请后，对方用户拒绝添加好友后会收到服务器发送的该事件。
+
+payload 字段含义：
+
+| 字段         | 数据类型 | 含义                      |
+| :----------- | :------- | :------------------------ |
+| `roster_ver` | String   | 好友列表的版本号。        |
+| `operation`  | String   | `decline`：拒绝好友申请。 |
+
+payload 之外的字段如下表所示：
+
+| 字段     | 数据类型 | 含义                                                         |
+| :------- | :------- | :----------------------------------------------------------- |
+| `callId`    | String   | `callId` 为每个回调请求的唯一标识，格式为 “App Key_拒绝好友申请事件的消息 ID”。 | 
+| `msg_id`    | String   | 拒绝好友申请事件的消息 ID。 | 
+
+回调请求示例：
+
+```json
+{
+    "chat_type":"roster",
+    "callId":"XXXX#XXXX_966726099692161068",
+    "security":"747d6297660e57bcf38315aa98c206ac",
+    "payload":{
+        "roster_ver":"3D81EC24A6E732B2EB1B654AA446930DB9BAFE59",
+        "operation":"remote_decline"
+        },
+    "host":"XXXX",
+    "appkey":"XXXX#XXXX",
+    "from":"XXXX#XXXX",
+    "to":"tst",
+    "eventType":"chat",
+    "msg_id":"9XXXX68",
+    "timestamp":1642648260029
+    }
+```
+
+## 拉黑好友
+
+payload 字段含义：
+
+| 字段         | 数据类型 | 含义                   |
+| :----------- | :------- | :--------------------- |
+| `operation`  | String   | `ban`：拉黑好友。      |
+| `status`     | object   | 包含 `error_code`。    |
+| `error_code` | String   | 操作失败对应的错误码。 |
+
+payload 之外的字段如下表所示：
+
+| 字段     | 数据类型 | 含义                                                         |
+| :------- | :------- | :----------------------------------------------------------- |
+| `callId`    | String   | `callId` 为每个回调请求的唯一标识，格式为 “App Key_拉黑好友事件的消息 ID”。 | 
+| `msg_id`    | String   | 拉黑好友事件的消息 ID。 | 
+
+payload 示例：
+
+```json
+{
+    "chat_type":"roster",
+    "callId":"XXXX#XXXX_966725184268539960",
+    "security":"00f070116668034ddecf3fb7db92087c",
+    "payload":{
+        "operation":"ban",
+        "status":{
+            "error_code":"ok"
+            }
+        },
+    "host":"XXXX",
+    "appkey":"XXXX#XXXX",
+    "from":"XXXX#XXXX",
+    "to":"tst",
+    "eventType":"chat",
+    "msg_id":"9XXXX0",
+    "timestamp":1642648046912
+}
+```
+
+
+## 解除拉黑好友
+
+payload 字段含义：
+
+| 字段         | 数据类型 | 含义                    |
+| :----------- | :------- | :---------------------- |
+| `operation`  | String   | `allow`：解除拉黑好友。 |
+| `status`     | object   | 包含 `error_code`。     |
+| `error_code` | String   | 操作失败对应的错误码。  |
+
+payload 之外的字段如下表所示：
+
+| 字段     | 数据类型 | 含义                                                         |
+| :------- | :------- | :----------------------------------------------------------- |
+| `callId`    | String   | `callId` 为每个回调请求的唯一标识，格式为 “App Key_解除拉黑好友事件的消息 ID”。 | 
+| `msg_id`    | String   | 解除拉黑好友事件的消息 ID。 | 
+
+回调请求示例：
+
+```json
+{
+    "chat_type":"roster",
+    "callId":"XXXX#XXXX_966725018736134200",
+    "security":"cbe8a5f1ba384107b63ef61637f55cad",
+    "payload":{
+        "operation":"allow",
+        "status":{
+            "error_code":"ok"
+            }
+        },
+    "host":"XXXX",
+    "appkey":"XXXX#XXXX",
+    "from":"XXXX#XXXX",
+    "to":"tst",
+    "eventType":"chat",
+    "msg_id":"966725018736134200",
+    "timestamp":1642648008357
+}
+```
diff --git a/docs/document/server-side/callback_group_ban.md b/docs/document/server-side/callback_group_ban.md
@@ -0,0 +1,53 @@
+ # 群组封禁/解禁事件
+
+成功封禁或解禁群组后，环信服务器会按照[发送后回调规则](/product/enable_and_configure_IM.html#配置回调规则)向你的 App Server 发送回调请求，App Server 可通过该回调查看群组封禁或解禁相关信息，进行数据同步。
+
+:::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)。
+:::
+
+## 回调时机
+
+[调用 RESTful API 封禁](/document/server-side/group_manage.html#封禁群组)或[解禁群组](/document/server-side/group_manage.html#解禁群组)时触发该事件。
+
+## 回调请求
+
+### 请求示例
+
+```json
+{
+	"callId": "XXXX#XXXX_9536cc9b-XXXX-XXXX-affb-8eaf67741180",
+	"security": "2106f88ddbaXXXX57c60430493e74dc3",
+	"payload": {
+		"disable": true,
+		"type": "DISABLE"
+	},
+	"appkey": "XXXX#XXXX",
+	"id": "262246968131585",
+	"type": "GROUP",
+	"event": "group_op_event",
+	"operation": "UPDATE",
+	"operator": "@ppAdmin",
+	"timestamp": 1729497011797
+}
+```
+
+### 请求字段说明
+
+| 字段名称         | 类型   | 描述                                                         |
+| :------------- | :----- | :----------------------------------------------------------- |
+| `callId`       | String   | `callId` 为每个回调请求的唯一标识，格式为 `App Key_UUID`。 | 
+| `security`     | String | 签名，格式如下: `MD5（callId+secret+timestamp）`。详见[配置环信控制台回调规则](/product/enable_and_configure_IM.html#配置回调规则)。|
+| `paylod`       | Object | 事件内容。                                                     |
+|  - `disabled`| Boolean | <br/> - `true`：封禁  <br/> - `false`：解禁 |
+|  - `type`   | String | `DISABLE`：封禁或解禁操作。  |
+| `appkey`       | String | 你在环信管理后台注册的应用唯一标识。  |
+| `id`       | String | 群组 ID。                                                 |
+| `type`         | String | 区分群组或聊天室事件。由于聊天室无封禁或解禁事件，本次事件仅对群组有效，因此值只能为 `GROUP`。   |
+| `event`        | String | 对于群组和聊天室，该参数的值固定为 `group_op_event`。接收方可按此字段区分是否是群组/聊天室操作事件。 | 
+| `operation`    | String | 操作。群组封禁或解禁的操作为 `UPDATE`。 |
+| `operator`     | String | 操作人。                     | 
+| `timestamp`    | Long   | 操作完成的时间戳。                | 
+