Merge pull request #1289 from haoxiuwen/doc-v2

haoxiuwen · web-flow · commit f33c27cde609 · 2025-05-19T09:52:08.000+08:00
Modify REST API Format
diff --git a/docs/document/server-side/chatroom_member_obtain.md b/docs/document/server-side/chatroom_member_obtain.md
@@ -30,8 +30,12 @@
 
 ## 分页获取聊天室成员列表
 
+### 功能说明
+
 可以分页获取聊天室成员列表。
 
+**调用频率**：100 次/秒/App Key
+
 ### HTTP 请求
 
 ```http
diff --git a/docs/document/server-side/chatroom_superadmin.md b/docs/document/server-side/chatroom_superadmin.md
@@ -60,7 +60,12 @@
 
 ## 添加超级管理员
 
-添加一个聊天室超级管理员。
+#### 功能说明
+
+- 添加一个聊天室超级管理员。
+- 添加聊天室超级管理员，会触发发送后回调，详见 [添加超级管理员事件](callback_room_superadmin.html#添加超级管理员)。
+
+**调用频率**：100 次/秒/App Key
 
 #### HTTP 请求
 
@@ -147,8 +152,12 @@ curl -X POST 'https://XXXX/XXXX/XXXX/chatrooms/super_admin'  \
 
 ## 分页获取超级管理员列表
 
+#### 功能说明
+
 可以分页获取超级管理员列表的接口。
 
+**调用频率**：100 次/秒/App Key
+
 #### HTTP 请求
 
 直接获取：
@@ -239,7 +248,12 @@ curl -X GET https://XXXX/XXXX/XXXX/chatrooms/super_admin?pagenum=2&pagesize=2 -H
 
 ## 撤销超级管理员
 
-撤销超级管理员权限，用户将不能再创建聊天室。
+#### 功能说明
+
+- 撤销超级管理员权限，用户将不能再创建聊天室。
+- 撤销聊天室超级管理员，会触发发送后回调，详见 [移除超级管理员事件](callback_room_superadmin.html#移除超级管理员)。
+
+**调用频率**：100 次/秒/App Key
 
 #### HTTP 请求
 
diff --git a/docs/document/server-side/group_member_obtain.md b/docs/document/server-side/group_member_obtain.md
@@ -30,8 +30,12 @@
 
 ## 分页获取群成员列表
 
+### 功能说明
+
 可以分页获取群组成员列表。
 
+**调用频率上限**：100 次/秒/App Key   
+
 ### HTTP 请求
 
 ```http
@@ -72,7 +76,7 @@ GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/users?pagenum={N}
 | `action`          | String | 请求方法。                                                                     |
 | `application`     | String | 应用在系统内的唯一标识。该标识由系统生成，开发者无需关心。                     |
 | `params`        | JSON | 查询参数。  |
-| - `joined_time` | Bool  | 是否需返回用户加入群组的时间：<br/> - `true`：返回 <br/> - `false`：不返回 |
+|  - `joined_time` | Bool  | 是否返回用户加入群组的时间：<br/> - `true`：返回 <br/> - `false`：不返回 |
 |  - `pagesize`        | Array | 每页期望显示的群组成员数量。  |
 |  - `pagenum`        | Array | 当前页码。  |
 | `uri`                | String | 请求 URL。   |
diff --git a/docs/document/server-side/message_attachment_storage.md b/docs/document/server-side/message_attachment_storage.md
@@ -1,14 +1,14 @@
 # 设置指定消息附件的存储方式 
 
-环信服务器支持对用户指定的消息附件设置存储方式，可延长存储时间或实现永久存储，支持通过客户端和 RESTful API 发送图片、语音、视频、文件消息和合并消息时上传的附件（包括图片和视频的缩略图）。
+## 功能说明
 
-对于永久存储的消息附件，用户可以随时获取这些附件。
+- 支持对用户指定的消息附件设置存储方式，可延长存储时间或实现永久存储。
+- 支持通过客户端和 RESTful API 发送图片、语音、视频、文件消息和合并消息时上传的附件（包括图片和视频的缩略图）。
+- 对于永久存储的消息附件，用户可以随时获取这些附件。
+- 关于消息附件存储时间限制，详见 [消息附件存储文档](/product/product_message_overview.html#历史消息存储)。
+- 若使用该接口，需 **联系环信商务开通**。
 
-:::tip
-若使用该接口，需联系环信商务开通。
-:::
-
-**调用频率**：100 次/秒/App Key
+**调用频率上限**：100 次/秒/App Key
 
 ## 前提条件
 
@@ -25,13 +25,13 @@
 
 为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 REST API 仅支持使用 App Token 的鉴权方式，详见 [使用 App Token 鉴权](easemob_app_token.html)。
 
-#### HTTP 请求
+## HTTP 请求
 
 ```http
 POST https://{host}/{org_name}/{app_name}/users/{username}/chatfiles/lifetime
 ```
 
-##### 路径参数
+#### 路径参数
 
 | 参数       | 类型   | 是否必需 | 描述        |
 | :--------- | :----- | :------- | :--------------- |
@@ -40,24 +40,24 @@ POST https://{host}/{org_name}/{app_name}/users/{username}/chatfiles/lifetime
 | `app_name` | String | 是       | 你在环信即时通讯云控制台创建应用时填入的应用名称。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。  |
 | `username`     | String | 是       | 调用该接口的用户 ID。 | 
 
-##### 请求 Header
+#### 请求 Header
 
 | 参数           | 类型   | 是否必需 | 描述                                |
 | :------------- | :----- | :------- | :---------------------------------- |
 | `Content-Type` | String | 是       | 内容类型。请填 `application/json`。 |
 | `Accept`        | String | 是       | 内容类型。请填 `application/json`。  |            
 | `Authorization` | String | 是       | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 |
     
-##### 请求 body
+#### 请求 body
 
 | 参数       | 类型   | 是否必需 | 描述          |
 | :--------- | :----- | :------- | :-------------------------------------------- |
 | `lifetime`      | String   | 是 | 消息附件保存时间：<br/> - （默认）`default`：配置的消息附件的默认有效期；<br/> - `refresh`：刷新消息附件的有效期，相当于重新设置存储时间，延长了存储时长。例如，消息附件可存储 7 天，在存储的第五天时调用了该接口，即将附件的存储时间设置为 7 天，则附件的剩余存储时间为 7 天。该设置可用于延长合并消息的附件存储时间，例如，发送合并消息时，原始图片的存储时间只剩余 1 天，调用该接口时利用该设置可将存储时间延长。<br/> - `forever`：永久有效。 |
 | `chatfile_ids`      | Array   | 是 | 消息附件的文件 UUID，最多可传入 100 个。 | 
 
-#### HTTP 响应
+## HTTP 响应
 
-##### 响应 body
+#### 响应 body
 
 如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体中包含以下字段：
 
@@ -77,9 +77,9 @@ POST https://{host}/{org_name}/{app_name}/users/{username}/chatfiles/lifetime
 
 如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [错误码](#错误码)了解可能的原因。
 
-#### 示例
+## 示例
 
-##### 请求示例
+#### 请求示例
 
 ```shell
 # 将 <YourUserToken> 替换为你的用户 Token
@@ -94,7 +94,7 @@ curl -X PUT -L "http://localhost/{org}/{app}/users/{username}/chatfiles/lifetime
     }'
 ```
 
-##### 响应示例
+#### 响应示例
 
 ```json
 {
@@ -111,7 +111,7 @@ curl -X PUT -L "http://localhost/{org}/{app}/users/{username}/chatfiles/lifetime
   "applicationName": "XXXX"
 }
 ```
-#### 错误码
+## 错误码
 
 如果返回的 HTTP 状态码非 `200`，表示请求失败，可能提示以下错误码：
 
diff --git a/docs/document/server-side/message_broadcast.md b/docs/document/server-side/message_broadcast.md
@@ -4,14 +4,16 @@
 
 ## 向 app 所有用户发送广播消息
 
+#### 功能说明
+
 可通过该接口向 app 下的所有用户发送广播消息，支持所有消息类型：
 
 - 广播消息向 app 下的所有用户发送。
 - 广播消息支持离线存储，若用户离线，服务器会存储离线消息（默认 7 天），若你集成了离线推送，则服务器会发送离线通知。
 - 广播消息写入服务端会话列表，支持消息漫游。
 - 广播消息支持计入消息未读数。
 - 广播消息没有消息 ID，只有广播 ID。
-- 广播消息不触发[发送前回调](callback_presending.html)。
+- 广播消息不触发 [发送前回调](callback_presending.html)。
  
 **发送频率**：
 
@@ -300,6 +302,8 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/broadcast' \
 
 ## 向 app 在线用户发送广播消息
 
+#### 功能说明
+
 可通过该接口向 app 下的所有在线用户发送广播消息，支持所有消息类型。
 
 - 广播消息只向 app 下的在线用户发送。
@@ -577,6 +581,8 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \
 
 ## 发送聊天室全局广播消息
 
+#### 功能说明
+
 即时通讯 IM 支持向 app 下的所有活跃聊天室（聊天室至少存在一个成员，而且曾经至少发送过一条消息）发送广播消息，支持所有消息类型。
 
 - 广播消息不支持离线存储，即离线用户收不到这些消息。
diff --git a/docs/document/server-side/message_download.md b/docs/document/server-side/message_download.md
@@ -2,11 +2,6 @@
 
 <Toc />
 
-对于附件类型的消息，如图片、语音、视频或其他类型文件，发送消息前需上传文件。你可以将文件上传到自己的服务器，也可以上传至环信服务器。若你将文件上传至自己的服务器，需注意以下两点：
-
-- 对于图片，发送图片消息时不存在图片缩略图。这是因为图片上传至环信服务器时，环信服务器会自动生成缩略图，发送图片消息时无需传入缩略图 URL 地址。
-- 对于视频，你需要将视频和缩略图均上传至你的服务器，发送视频消息时需传入这两个文件的 URL 地址。
-
 本文介绍如何调用 RESTful API 将文件上传到环信服务器、下载图片、语音、视频或其他类型的文件以及下载图片和视频文件的缩略图。
 
 ## 前提条件
@@ -50,15 +45,30 @@
 
 ## 上传文件
 
-对于附件类型的消息，如图片、语音、视频或其他类型文件，发送消息前需上传文件。图片和视频存在缩略图，文件上传详情如下：
+### 功能说明
+
+- 对于附件类型的消息，如图片、语音、视频或其他类型文件，发送消息前需上传文件。
+- 可将文件上传到自己的服务器，也可以上传至环信服务器。若你将文件上传至自己的服务器。
+
+**调用频率上限**：100 次/秒/App Key
+
+#### 图片消息
+
+- 可调上传原图，环信服务器会自动为图片生成缩略图。
+- 若上传的图片在 10 KB 以内，缩略图与原图等同。
+- 若图片超过 10 KB，环信服务器会根据你在请求中设置的图片高度和宽度，即 `thumbnail-height` 和 `thumbnail-width` 参数，生成缩略图。若这两个参数未传，则图片的高度和宽度均默认为 170 像素。
 
-- 图片：可调用文件上传接口上传原图，环信服务器会自动为图片生成缩略图。若上传的图片在 10 KB 以内，缩略图与原图等同；若图片超过 10 KB，环信服务器会根据你在请求中设置的图片高度和宽度，即 `thumbnail-height` 和 `thumbnail-width` 参数，生成缩略图。若这两个参数未传，则图片的高度和宽度均默认为 170 像素。
-- 视频：环信服务器不会自动为视频文件生成缩略图。若需要视频缩略图，需先调用文件上传接口上传缩略图。然后，再次调用文件上传接口上传视频源文件。上传视频文件时，无需传 `thumbnail-height` 和 `thumbnail-width` 参数。上传视频缩略图时，若图片在 10 KB 以内，视频缩略图即为上传的图片。如果图片超过 10 KB，而且设置了这两个参数，视频缩略图的高度和宽度取决于这两个参数的设置。若这两个参数未传，则图片的高度和宽度均默认为 170 像素。
+#### 视频消息
 
-同时，为了保证聊天文件的安全，我们的 API 保证了以下几点：
+- 环信服务器不会自动为视频文件生成缩略图。你需要上传视频源文件和视频缩略图（若需要的话）。
+- 上传视频文件时，无需传 `thumbnail-height` 和 `thumbnail-width` 参数。
+- 上传视频缩略图时，若图片在 10 KB 以内，视频缩略图即为上传的图片。
+- 如果图片超过 10 KB，而且设置了 `thumbnail-height` 和 `thumbnail-width` 参数，视频缩略图的高度和宽度取决于这两个参数的设置。若这两个参数未传，则图片的高度和宽度均默认为 170 像素。
 
-- 上传文件的大小不能超过 10 MB，超过会上传失败。
-- 支持对上传的文件限制访问。要使用该功能，请联系商务开通。该功能开启后，你需要从文件上传响应中返回的 `share-secret` 通过密钥才能下载被限制访问的文件。消息回调（包含发送前回调和发送后回调）和获取历史消息涉及下载文件时，都需要在下载 URL 中拼接密钥，才能正常下载文件，拼接规则为：`{{url}}?share-secret={{secret}}`。
+#### 文件限制
+
+- 上传文件的大小默认不能超过 10 MB，超过会上传失败。
+- 支持文件限制访问。要使用该功能，请联系商务开通。该功能开启后，你需要从文件上传响应中返回的 `share-secret` 通过密钥才能下载被限制访问的文件。消息回调（包含发送前回调和发送后回调）和获取历史消息涉及下载文件时，都需要在下载 URL 中拼接密钥，才能正常下载文件，拼接规则为：`{{url}}?share-secret={{secret}}`。
 
 ### HTTP 请求
 
@@ -153,12 +163,13 @@ curl -X POST 'https://XXXX/XXXX/XXXX/chatfiles'  \
 
 ## 下载文件
 
-你可利用该方法下载图片、语音、视频或其他类型的文件。
+### 功能说明
 
-:::tip
-如果上传文件时设置了文件访问限制（`restrict-access` 设置为 `true`），需要在下载请求头中包含文件上传响应中返回的 `share-secret` 和当前登录用户的 token 才能下载文件。
-:::
+- 支持下载图片、语音、视频或其他类型的文件。
+- 支持文件访问限制：如果上传文件时设置了文件访问限制（`restrict-access` 设置为 `true`），需要在下载请求头中包含文件上传响应中返回的 `share-secret` 和当前登录用户的 token 才能下载文件。
 
+**调用频率上限**：100 次/秒/App Key
+  
 ### HTTP 请求
 
 ```http
@@ -226,8 +237,12 @@ curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer <You
 
 ## 下载缩略图
 
+### 功能说明
+
 收到图片或视频消息，你可以先下载图片或视频的缩略图，需要时再下载图片或视频原文件。下载缩略图与下载原文件的唯一区别是前者在请求 header 中多了 `thumbnail: true`。当服务器收到包含该字段的请求 header 时，返回缩略图，否则返回原文件。
 
+**调用频率上限**：100 次/秒/App Key
+
 ### HTTP 请求
 
 ```http
diff --git a/docs/document/server-side/message_modify.md b/docs/document/server-side/message_modify.md
@@ -1,21 +1,31 @@
 # 修改消息
 
-本文展示如何调用环信 IM RESTful API 在服务端修改单聊、群组聊天和聊天室中发送成功的消息：
+## 功能说明
+
+### 功能开通
+
+若使用该功能，需联系环信商务开通。
+
+### 功能描述
+
+环信即时通讯 IM 支持在服务端修改单聊、群组聊天和聊天室中发送成功的消息：
 
  - 文本消息：支持修改消息内容字段 `msg` 和扩展字段 `ext`。
  - 自定义消息：支持修改 `customEvent` 、`customExts` 和扩展字段 `ext`。
  - 图片/语音/视频/文件/位置消息：仅支持修改扩展字段 `ext`。
  - 命令消息：不支持修改。
 
+### 消息修改后的生命周期
+
 修改消息没有时间限制，即只要这条消息仍在服务端存储就可以修改。消息修改后，消息生命周期（在服务端的保存时间）会重新计算，例如，消息可在服务器上保存 180 天，用户在消息发送后的第 30 天（服务器上的保存时间剩余 150 天）修改了消息，修改成功后该消息还可以在服务器上保存 180 天。
 
+### 消息修改后的变化
+
 对于修改后的消息，消息体中除了内容或扩展字段变化，还新增了修改者的用户 ID、修改时间和修改次数属性。除消息体外，该消息的其他信息（例如，消息发送方、接收方）均不会发生变化。
 
-**调用频率**：100 次/秒/App Key
+### 接口调用频率上限
 
-:::tip
-若使用该功能，需联系环信商务开通。
-:::
+100 次/秒/App Key
 
 ## 前提条件
 
diff --git a/docs/document/server-side/push.md b/docs/document/server-side/push.md
diff --git a/docs/document/server-side/reaction.md b/docs/document/server-side/reaction.md
diff --git a/docs/document/server-side/userprofile.md b/docs/document/server-side/userprofile.md
