diff --git "a/docs/.vuepress/public/.vuepress - \345\277\253\346\215\267\346\226\271\345\274\217.lnk" "b/docs/.vuepress/public/.vuepress - \345\277\253\346\215\267\346\226\271\345\274\217.lnk" new file mode 100644 index 00000000..b5b6dfb0 Binary files /dev/null and "b/docs/.vuepress/public/.vuepress - \345\277\253\346\215\267\346\226\271\345\274\217.lnk" differ diff --git a/docs/document/server-side/message_broadcast.md b/docs/document/server-side/message_broadcast.md index 46ec810b..16b73ee3 100644 --- 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 | 是 | 广播消息类型:
- `txt`:文本消息;
- `img`:图片消息;
- `audio`:语音消息;
- `video`:视频消息;
- `file`:文件消息;
- `loc`:位置消息;
- `cmd`:透传消息;
- `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 +# 将 替换为你在服务端生成的 App Token + +curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer ' \ +-d '{ + "msg": { + "type": "txt", + "msg": "send broadcast to all online users" + }, + "from": "admin", + "ext": { + "extKey": "extValue" + } +}' +``` + +- 发送图片广播消息 + +```bash +# 将 替换为你在服务端生成的 App Token + +curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer ' \ +-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 +# 将 替换为你在服务端生成的 App Token + +curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer ' \ +-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 +# 将 替换为你在服务端生成的 App Token + +curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer ' \ +-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 +# 将 替换为你在服务端生成的 App Token + +curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer ' \ +-d '{ + "msg": { + "type": "file", + "filename":"test.txt", + "secret":"1-g0XXXXua", + "url":"https://XXXX/XXXX/XXXX/chatfiles/d7eXXXX7444" + }, + "from": "admin", + "ext": { + "extKey": "extValue" + } +}' +``` + +- 发送位置广播消息 + +```bash +# 将 替换为你在服务端生成的 App Token + +curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer ' \ +-d '{ + "msg": { + "type": "loc", + "lat": "39.966", + "lng":"116.322", + "addr":"中国北京市海淀区中关村" + }, + "from": "admin", + "ext": { + "extKey": "extValue" + } +}' +``` -## 前提条件 +- 发送透传广播消息 -要调用环信即时通讯 RESTful API,请确保满足以下要求: +```bash +# 将 替换为你在服务端生成的 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 ' \ +-d '{ + "msg": { + "type": "cmd", + "action":"action1" + }, + "from": "admin", + "ext": { + "extKey": "extValue" + } +}' +``` + +- 发送自定义广播消息 + +```bash +# 将 替换为你在服务端生成的 App Token + +curl -L 'https://XXXX/XXXX/XXXX/messages/users/broadcast' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer ' \ +-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 index 4249b59b..dac9d3e2 100644 --- 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 存在以下三个限制:
- 100 次/秒/App Key
- 6000 条/分钟
- 600 人/次。若一次向 600 人发消息,视为 600 条消息。 | | * 发送群聊消息 | POST | /{org_name}/{app_name}/messages/chatgroups | 对于单个 app,该 REST API 存在以下三个限制:
- 20 条/秒/App Key
- 20 次/秒
- 3 个群/次 | | * 发送定向消息 | POST | /{org_name}/{app_name}/messages/chatgroups/users | 100 条/秒/App Key | | * 发送聊天室消息 | POST | /{org_name}/{app_name}/messages/chatrooms | 对于单个 app,该 REST API 存在以下三个限制:
- 100 条/秒
- 20 次/秒
- 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 |