Merge pull request #1128 from haoxiuwen/doc-v2

Add REST API of Sending Broadcast Messages to Online Users in an App
easemob · Jan 10, 2025 · 3f74e7f · 3f74e7f
2 parents d185a5a + 730e4be
commit 3f74e7f
Show file tree

Hide file tree

Showing 3 changed files with 276 additions and 37 deletions.
diff --git a/docs/.vuepress/public/.vuepress - 快捷方式.lnk b/docs/.vuepress/public/.vuepress - 快捷方式.lnk
diff --git a/docs/document/server-side/message_broadcast.md b/docs/document/server-side/message_broadcast.md
@@ -1,65 +1,301 @@
-# 发送聊天室全局广播消息
+# 发送全局广播消息
 
-即时通讯 IM 支持向 app 下的所有活跃聊天室（聊天室至少存在一个成员，而且曾经至少发送过一条消息）发送广播消息，支持所有消息类型。**该功能默认关闭，如果需要，请联系环信商务开通。**
+即时通讯 IM 支持向 app 所有在线用户发送全局广播消息以及发送聊天室全局广播消息。**该功能默认关闭，使用前需联系环信商务开通。**
 
-**发送频率**：每分钟限发 10 次，每天限发 100 次广播消息。
+## 向 app 在线用户发送广播消息
+
+可通过该接口向 app 下的所有在线用户发送广播消息，支持所有消息类型。
+
+- 广播消息只向 app 下的在线用户发送。
+- 广播消息不支持离线存储，即离线用户收不到这些消息。
+- 广播消息写入服务端会话列表，默认不支持漫游功能。**如果需要，请联系商务开通。**
+
+**发送频率**：每分钟限 1 次，每天限 50 次（可联系商务提升该上限）。
+
+#### HTTP 请求
+
+```http
+POST https://{host}/{org_name}/{app_name}/messages/users/broadcast
+```
+
+##### 路径参数
+
+参数及说明详见 [公共参数](#公共参数)。
+
+##### 请求 header
+
+| 参数       | 类型   | 是否必需 | 描述          |
+| :-------------- | :----- | :------- | :-------------- |
+| `Content-Type`  | String | 是       | 内容类型。请填 `application/json`。       |
+| `Authorization` | String | 是       | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 |
+
+##### 请求 body
+
+以下为发送文本类型的广播消息的请求 body。
+
+| 参数            | 类型   | 是否必需 | 描述       |
+| :-------------- | :----- | :------- | :--------------- |
+| `from`          | String | 否       | 广播消息发送方的用户 ID。若不传入该字段，服务器默认设置为管理员，即 `admin`；若传入字段但值为空字符串 (“”)，请求失败。  |
+| `msg` | JSON | 是 | 消息体包含的信息。  |
+| `msg.type` | String | 是 | 广播消息类型：<br/> - `txt`：文本消息；<br/> - `img`：图片消息；<br/> - `audio`：语音消息；<br/> - `video`：视频消息；<br/> - `file`：文件消息；<br/> - `loc`：位置消息；<br/> - `cmd`：透传消息；<br/> - `custom`：自定义消息。 |
+| `msg.msg` | String | 是 | 消息内容。  |
+| `ext`           | JSON   | 否       | 广播消息支持扩展字段，可添加自定义信息。不能对该参数传入 `null`。 | 
+
+不同类型的消息的请求体只在 `msg` 字段有差别，其他参数相同。除了 `type` 字段，`msg` 字段中包含的参数与单聊、群聊和聊天室消息的请求体中的 `body` 字段含义相同，详见[发送单聊消息](message_single.html)、[发送群聊消息](message_group.html)和[发送聊天室消息](message_chatroom.html)中的消息 body 的参数说明。
+
+#### HTTP 响应
+
+##### 响应 body
+
+对于各类型的广播消息来说，响应中包含的各字段相同。
+
+如果返回的 HTTP 状态码为 `200`，表示请求成功，响应 body 包含如下字段：
+
+| 参数   | 类型 | 描述   |
+| :----- | :--- | :----------- |
+| `data.id` | JSON | 广播 ID。 |
+
+其他参数及说明详见 [公共参数](#公共参数)。
+
+如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [响应状态码](error.html)了解可能的原因。
+
+#### 示例
+
+##### 请求示例
+
+- 发送文本广播消息
+
+```bash
+# 将 <YourAppToken> 替换为你在服务端生成的 App Token
+
+curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer <YourAppToken>' \
+-d '{
+    "msg": {
+        "type": "txt",
+        "msg": "send broadcast to all online users"
+    },
+    "from": "admin",
+    "ext": {
+        "extKey": "extValue"
+    }
+}'
+```
+
+- 发送图片广播消息
+
+```bash
+# 将 <YourAppToken> 替换为你在服务端生成的 App Token
+
+curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer <YourAppToken>' \
+-d '{
+    "msg": {
+        "type": "img",
+        "filename":"testimg.jpg",
+        "secret":"VfXXXXNb_",
+        "url":"https://XXXX/XXXX/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252",
+        "size":{
+           "width":480,
+           "height":720
+        }
+    },
+    "from": "admin",
+    "ext": {
+        "extKey": "extValue"
+    }
+}'
+```
+
+- 发送语音广播消息
+
+```bash
+# 将 <YourAppToken> 替换为你在服务端生成的 App Token
+
+curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer <YourAppToken>' \
+-d '{
+    "msg": {
+        "type": "audio",
+        "url": "https://XXXX/XXXX/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42",
+        "filename": "testaudio.amr",
+        "length": 10,
+        "secret": "HfXXXXCjM"
+    },
+    "from": "admin",
+    "ext": {
+        "extKey": "extValue"
+    }
+}'
+```
+
+- 发送视频广播消息
+
+```bash
+# 将 <YourAppToken> 替换为你在服务端生成的 App Token
+
+curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer <YourAppToken>' \
+-d '{
+    "msg": {
+        "type": "video",
+        "thumb" : "https://XXXX/XXXX/XXXX/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97",
+        "length" : 0,
+        "secret":"VfXXXXNb_",
+        "file_length" : 58103,
+        "thumb_secret" : "ZyXXXX2I",
+        "url" : "https://XXXX/XXXX/XXXX/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"
+    },
+    "from": "admin",
+    "ext": {
+        "extKey": "extValue"
+    }
+}'
+```
+
+- 发送文件广播消息
+
+```bash
+# 将 <YourAppToken> 替换为你在服务端生成的 App Token
+
+curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer <YourAppToken>' \
+-d '{
+    "msg": {
+        "type": "file",
+        "filename":"test.txt",
+        "secret":"1-g0XXXXua",
+        "url":"https://XXXX/XXXX/XXXX/chatfiles/d7eXXXX7444"
+    },
+    "from": "admin",
+    "ext": {
+        "extKey": "extValue"
+    }
+}'
+```
+
+- 发送位置广播消息
+
+```bash
+# 将 <YourAppToken> 替换为你在服务端生成的 App Token
+
+curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer <YourAppToken>' \
+-d '{
+    "msg": {
+        "type": "loc",
+        "lat": "39.966",
+        "lng":"116.322",
+        "addr":"中国北京市海淀区中关村"
+    },
+    "from": "admin",
+    "ext": {
+        "extKey": "extValue"
+    }
+}'
+```
 
-## 前提条件
+- 发送透传广播消息
 
-要调用环信即时通讯 RESTful API，请确保满足以下要求：
+```bash
+# 将 <YourAppToken> 替换为你在服务端生成的 App Token
 
-- 已在环信即时通讯控制台 [开通配置环信即时通讯 IM 服务](enable_and_configure_IM.html)。
-- 了解环信 IM RESTful API 的调用频率限制，详见 [接口频率限制](limitationapi.html)。
+curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer <YourAppToken>' \
+-d '{
+    "msg": {
+        "type": "cmd",
+        "action":"action1"
+    },
+    "from": "admin",
+    "ext": {
+        "extKey": "extValue"
+    }
+}'
+```
+
+- 发送自定义广播消息
+
+```bash
+# 将 <YourAppToken> 替换为你在服务端生成的 App Token
+
+curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer <YourAppToken>' \
+-d '{
+    "msg": {
+        "type": "custom",
+        "customEvent": "custom_event",
+    },
+    "from": "admin",
+    "ext": {
+        "extKey": "extValue"
+    }
+}'
+```
 
-## 公共参数 
+##### 响应示例
 
-#### 请求参数
+```json
+{
+  "path": "/messages/users/broadcast",
+  "uri": "https://XXXX/XXXX/XXXX/messages/users/broadcast",
+  "timestamp": 1699944653964,
+  "organization": "XXXX",
+  "application": "331d42e6-ad85-XXXX-XXXX-d1fb6fef9f12",
+  "action": "post",
+  "data": {
+    "id": 1173998498812376874
+   },
+  "duration": 1,
+  "applicationName": "XXXX"
+}
+```
 
-| 参数       | 类型   | 是否必需 | 描述        |
-| :--------- | :----- | :------- | :----------------------- |
-| `host`     | String | 是       | 环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 |
-| `org_name` | String | 是       | 环信即时通讯 IM 为每个公司（组织）分配的唯一标识。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。  |
-| `app_name` | String | 是       | 你在环信即时通讯云控制台创建应用时填入的应用名称。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。  |
+#### 错误码
 
-#### 响应参数
+对于应用全局广播消息，如果返回的 HTTP 状态码非 `200`，表示请求失败。除了发送普通消息的常见错误码，还可能提示以下错误码：
 
-| 参数              | 类型   | 描述          |
-| :---------------- | :----- | :------------------------------- |
-| `action`          | String | 请求方法。                                                                     |
-| `organization`    | String | 环信即时通讯 IM 为每个公司（组织）分配的唯一标识，与请求参数 `org_name` 相同。 |
-| `application`     | String | 应用在系统内的唯一标识。该标识由系统生成，开发者无需关心。                     |
-| `applicationName` | String | 你在环信即时通讯云控制台创建应用时填入的应用名称，与请求参数 `app_name` 相同。 |
-| `uri`             | String | 请求 URL。                                                                     |
-| `path`            | String | 请求路径，属于请求 URL 的一部分，开发者无需关注。                              |
-| `timestamp`       | Long   | HTTP 响应的 Unix 时间戳，单位为毫秒。                                          |
-| `duration`        | Int    | 从发送 HTTP 请求到响应的时长，单位为毫秒。                                     |
+| HTTP 状态码 | 错误类型   | 错误提示      | 可能原因    | 处理建议     |
+|:---------|:-------------------|:-----------------|:-----------|:----------|
+| 400      | invalid_request_body    | Request body is invalid. Please check body is correct. | 请求体格式不正确。 | 检查请求体内容是否合法(字段类型是否正确)。  |
+| 400      | illegal_argument | from can't be empty  | 请求参数 `from` 是空字符串。  | 输入正确的请求参数 `from` 。若不传该字段， 服务器会默认设置为 `admin`。   |
+| 400      | illegal_argument | ext must be JSONObject | 请求参数 `ext` 类型不正确。  | 输入正确的请求参数 `ext`（JSON 格式）。  |
+| 403      | forbidden_op | message broadcast service is unopened  | 未开通发送广播消息的功能配置。| 联系商务开通。 | 
 
-## 认证方式
+此外，你可以参考[发送单聊消息](message_single.html#错误码)、[发送群聊消息](message_group.html#错误码)和[发送聊天室消息](message_chatroom.html#错误码)的错误码了解可能的原因。
 
-环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 `Authorization` 字段：
+## 发送聊天室全局广播消息
 
-`Authorization: Bearer YourAppToken`
+即时通讯 IM 支持向 app 下的所有活跃聊天室（聊天室至少存在一个成员，而且曾经至少发送过一条消息）发送广播消息，支持所有消息类型。
 
-为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。本文涉及的所有消息管理 RESTful API 都需要使用 App Token 的鉴权方式，详见 [使用 App Token 鉴权](easemob_app_token.html)。
+**发送频率**：每分钟限发 10 次，每天限发 100 次广播消息。
 
-## HTTP 请求
+#### HTTP 请求
 
 ```http
 POST https://{host}/{org_name}/{app_name}/messages/chatrooms/broadcast
 ```
 
-#### 路径参数
+##### 路径参数
 
 参数及说明详见 [公共参数](#公共参数)。
 
-#### 请求 header
+##### 请求 header
 
 | 参数       | 类型   | 是否必需 | 描述          |
 | :-------------- | :----- | :------- | :-------------- |
 | `Content-Type`  | String | 是       | 内容类型。请填 `application/json`。       |
 | `Authorization` | String | 是       | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 |
 
-#### 请求 body
+##### 请求 body
 
 以下为发送文本类型的广播消息的请求 body。
 
@@ -81,9 +317,9 @@ POST https://{host}/{org_name}/{app_name}/messages/chatrooms/broadcast
 - [发送透传消息](message_chatroom.html#发送透传消息)
 - [发送自定义消息](message_chatroom.html#发送自定义消息)
 
-## HTTP 响应
+#### HTTP 响应
 
-#### 响应 body
+##### 响应 body
 
 对于各类型的广播消息来说，响应中包含的各字段相同。
 
@@ -97,7 +333,7 @@ POST https://{host}/{org_name}/{app_name}/messages/chatrooms/broadcast
 
 如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [响应状态码](error.html) 了解可能的原因。
 
-## 示例
+#### 示例
 
 #### 请求示例
 
@@ -305,7 +541,7 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/chatrooms/broadcast' \
 }
 ```
 
-## 错误码
+#### 错误码
 
 | HTTP 状态码 | 错误类型   | 错误提示      | 可能原因    | 处理建议     |
 |:---------|:-------------------|:-----------------|:-----------|:----------|

diff --git a/docs/product/limitationapi.md b/docs/product/limitationapi.md
@@ -11,12 +11,15 @@
 
 ## 消息管理
 
+### 消息管理相关 API
+
 | RESTful API 接口 |方法  | 接口 URL| 接口最高调用频率（默认值） |
 | :-------- | :----- | :---------------- | :--------------------- |
 | * 发送单聊消息                 | POST   | /{org_name}/{app_name}/messages/users                | 对于单个 app，该 REST API 存在以下三个限制：<br/> - 100 次/秒/App Key <br/> - 6000 条/分钟  <br/> - 600 人/次。若一次向 600 人发消息，视为 600 条消息。  |
 | * 发送群聊消息                 | POST   | /{org_name}/{app_name}/messages/chatgroups           | 对于单个 app，该 REST API 存在以下三个限制：<br/> - 20 条/秒/App Key   <br/> - 20 次/秒 <br/> -  3 个群/次   |
 | * 发送定向消息                 | POST   | /{org_name}/{app_name}/messages/chatgroups/users           | 100 条/秒/App Key   |
 | * 发送聊天室消息               | POST   | /{org_name}/{app_name}/messages/chatrooms            | 对于单个 app，该 REST API 存在以下三个限制：<br/> - 100 条/秒  <br/> - 20 次/秒   <br/> -  10 个聊天室/次   |
+| * 向 app 在线用户发送广播消息 | POST | /{org_name}/{app_name}/messages/users/broadcast | 每分钟限 1 次，每天限 50 次（可联系环信商务提升该上限）。 |
 | * 发送聊天室全局广播消息 | POST | /{org_name}/{app_name}/messages/chatrooms/broadcast | 每分钟限发 10 次，每天限发 100 次广播消息。 |
 | 上传文件  |    POST  | /{org_name}/{app_name}/chatfiles       | 100 次/秒/App Key                                                 |
 | 下载文件      |  GET     | /{org_name}/{app_name}/chatfiles/{file_uuid}       | 100 次/秒/App Key                                                 |