Skip to content

Commit

Permalink
modify
Browse files Browse the repository at this point in the history
  • Loading branch information
@haoxiuwen
haoxiuwen committed Jan 29, 2024
1 parent 572a27f commit 98daf07
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 73 deletions.
44 changes: 3 additions & 41 deletions docs/document/server-side/message_chatroom.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@

### 发送聊天室消息
# 发送聊天室消息

本文展示如何调用环信 IM RESTful API 在服务端实现聊天室场景中全类型消息的发送与接收，包括文本消息、图片消息、语音消息、视频消息、透传消息和自定义消息。

聊天室场景下，发送各类型的消息调用需调用同一 RESTful API，不同类型的消息只是请求体中的 body 字段内容存在差异，发送方式与单聊类似，详见[发送单聊消息](message_single.html)。

:::notice
:::tip
接口调用过程中，请求体和扩展字段的总长度不能超过 5 KB。
:::

Expand Down Expand Up @@ -86,8 +85,6 @@ POST https://{host}/{org_name}/{app_name}/messages/chatrooms
| `chatroom_msg_level` | String | 否 | 聊天室消息优先级：<br/> - `high`：高； <br/> - （默认）`normal`：普通；<br/> - `low`：低。 |
| `type` | String | 是 | 消息类型：<br/> - `txt`：文本消息；<br/> - `img`：图片消息；<br/> - `audio`：语音消息；<br/> - `video`：视频消息；<br/> - `file`：文件消息；<br/> - `loc`：位置消息；<br/> - `cmd`：透传消息；<br/> - `custom`：自定义消息。 |
| `body` | JSON | 是 | 消息内容。body 包含的字段见下表说明。 |
| `sync_device` | Bool | 否 | 消息发送成功后，是否将消息同步到发送方。<br/> - `true`：是；<br/> - （默认）`false`：否。 |
| `routetype` | String | 否 | 若传入该参数，其值为 `ROUTE_ONLINE`，表示接收方只有在线时才能收到消息，若接收方离线则无法收到消息。若不传入该参数，无论接收方在线还是离线都能收到消息。 |
| `ext` | JSON | 否 | 消息支持扩展字段，可添加自定义信息。不能对该参数传入 `null`。同时，推送通知也支持自定义扩展字段，详见 [APNs 自定义显示](/document/ios/push.html#自定义显示) 和 [Android 推送字段说明](/document/android/push.html#自定义显示)。 |

请求体中的 `body` 字段说明详见下表。
Expand Down Expand Up @@ -148,9 +145,7 @@ curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatrooms' \
"type": "txt",
"body": {
"msg": "testmessages"
},
"routetype":"ROUTE_ONLINE",
"sync_device":true
}
}'
```

Expand Down Expand Up @@ -824,7 +819,6 @@ POST https://{host}/{org_name}/{app_name}/messages/chatrooms/users
| `chatroom_msg_level` | String | 否 | 聊天室消息优先级：<br/> - `high`：高； <br/> - （默认）`normal`：普通；<br/> - `low`：低。 |
| `type` | String | 是 | 消息类型：<br/> - `txt`：文本消息；<br/> - `img`：图片消息；<br/> - `audio`：语音消息；<br/> - `video`：视频消息；<br/> - `file`：文件消息；<br/> - `loc`：位置消息；<br/> - `cmd`：透传消息；<br/> - `custom`：自定义消息。 |
| `body` | JSON | 是 | 消息内容。body 包含的字段见下表说明。 |
| `sync_device` | Bool | 否 | 消息发送成功后，是否将消息同步到发送方。<br/> - `true`：是；<br/> - （默认）`false`：否。 |
| `ext` | JSON | 否 | 消息支持扩展字段，可添加自定义信息。不能对该参数传入 `null`。同时，推送通知也支持自定义扩展字段，详见 [APNs 自定义显示](/document/ios/push.html#自定义显示) 和 [Android 推送字段说明](/document/android/push.html#自定义显示)。 |
| `users` | Array | 是 | 接收消息的聊天室成员的用户 ID 数组。每次最多可传 20 个用户 ID。 |

Expand Down Expand Up @@ -854,28 +848,6 @@ POST https://{host}/{org_name}/{app_name}/messages/chatrooms/users

#### 请求示例

发送给目标用户，消息无需同步给发送方：

```bash
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatrooms' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
"from": "user1",
"to": ["185145305923585"],
"type": "txt",
"body": {
"msg": "testmessages"
},
"users": ["user2", "user3"]
}'
```

仅发送给在线用户，消息同步给发送方：

```bash
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

Expand All @@ -890,7 +862,6 @@ curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatrooms' \
"body": {
"msg": "testmessages"
},
"sync_device": true,
"users": ["user2", "user3"]
}'
```
Expand Down Expand Up @@ -948,7 +919,6 @@ POST https://{host}/{org_name}/{app_name}/messages/chatrooms/broadcast
| `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`。同时，推送通知也支持自定义扩展字段，详见 [APNs 自定义显示](/document/ios/push.html#自定义显示) 和 [Android 推送字段说明](/document/android/push.html#自定义显示)。 |
| `sync_device` | Bool | 否 | 广播消息发送成功后，是否将消息同步到发送方。<br/> - `true`：是；<br/> - （默认）`false`：否。 |

不同类型的消息的请求体只在 `msg` 字段有差别，其他参数相同。除了 `type` 字段，`msg` 字段中包含的参数与发送聊天室消息的请求体中的 `body` 字段含义相同，详见各类消息的参数说明。
- [发送图片消息](#发送图片消息)
Expand Down Expand Up @@ -996,7 +966,6 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/chatrooms/broadcast' \
"ext": {
"extKey": "extValue"
},
"sync_device": false,
"chatroom_msg_level": "low"
}'
```
Expand Down Expand Up @@ -1024,7 +993,6 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/chatrooms/broadcast' \
"ext": {
"extKey": "extValue"
},
"sync_device": false,
"chatroom_msg_level": "low"
}'
```
Expand All @@ -1049,7 +1017,6 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/chatrooms/broadcast' \
"ext": {
"extKey": "extValue"
},
"sync_device": false,
"chatroom_msg_level": "low"
}'
```
Expand All @@ -1076,7 +1043,6 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/chatrooms/broadcast' \
"ext": {
"extKey": "extValue"
},
"sync_device": false,
"chatroom_msg_level": "low"
}'
```
Expand All @@ -1100,7 +1066,6 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/chatrooms/broadcast' \
"ext": {
"extKey": "extValue"
},
"sync_device": false,
"chatroom_msg_level": "low"
}'
```
Expand All @@ -1124,7 +1089,6 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/chatrooms/broadcast' \
"ext": {
"extKey": "extValue"
},
"sync_device": false,
"chatroom_msg_level": "low"
}'
```
Expand All @@ -1146,7 +1110,6 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/chatrooms/broadcast' \
"ext": {
"extKey": "extValue"
},
"sync_device": false,
"chatroom_msg_level": "low"
}'
```
Expand All @@ -1168,7 +1131,6 @@ curl -L 'https://XXXX/XXXX/XXXX/messages/chatrooms/broadcast' \
"ext": {
"extKey": "extValue"
},
"sync_device": false,
"chatroom_msg_level": "low"
}'
```
Expand Down
40 changes: 8 additions & 32 deletions docs/document/server-side/message_group.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
群组聊天场景下，发送各类型的消息调用需调用同一 RESTful API，不同类型的消息只是请求体中的 body 字段内容存在差异，发送方式与单聊类似，详见[发送单聊消息](message_single.html)。

:::tip
接口调用过程中，请求体和扩展字段的总长度不能超过 5 KB。
1. 接口调用过程中，请求体和扩展字段的总长度不能超过 5 KB。
2. 群组中发送的消息均同步给发送方。
:::

**发送频率**：对于单个应用来说，调用该 API 每次最多向 3 个群组发送消息，而且该 API 存在以下两个限制：
Expand Down Expand Up @@ -76,8 +77,8 @@ POST https://{host}/{org_name}/{app_name}/messages/chatgroups

下表为发送各类消息的通用请求体，为 JSON 对象，是所有消息的外层结构。与单聊消息类似，不同类型的消息的请求体只是 `body` 字段内容存在差异。

:::notice
群聊消息的通用请求体中的参数与[发送单聊消息](message_single.html)类似，唯一区别在于群聊中的 `to` 字段表示消息接收方群组 ID 数组。<br/>
:::tip
1. 群聊消息的通用请求体中的参数与[发送单聊消息](message_single.html)类似，唯一区别在于群聊中的 `to` 字段表示消息接收方群组 ID 数组。<br/>
:::

| 参数 | 类型 | 是否必需 | 描述 |
Expand All @@ -86,7 +87,6 @@ POST https://{host}/{org_name}/{app_name}/messages/chatgroups
| `to` | Array | 是 | 消息接收方群组 ID 数组。每次最多可向 3 个群组发送消息。<Container type="tip" title="提示">服务器不校验传入的群组 ID 是否存在，因此，如果你传入的群组 ID 不存在，服务器并不会提示，仍照常发送消息。</Container> |
| `type` | String | 是 | 消息类型：<br/> - `txt`：文本消息；<br/> - `img`：图片消息；<br/> - `audio`：语音消息；<br/> - `video`：视频消息；<br/> - `file`：文件消息；<br/> - `loc`：位置消息；<br/> - `cmd`：透传消息；<br/> - `custom`：自定义消息。 |
| `body` | JSON | 是 | 消息内容。body 包含的字段见下表说明。 |
| `sync_device` | Bool | 否 | 消息发送成功后，是否将消息同步到发送方。<br/> - `true`：是；<br/> - （默认）`false`：否。 |
| `routetype` | String | 否 | 若传入该参数，其值为 `ROUTE_ONLINE`，表示接收方只有在线时才能收到消息，若接收方离线则无法收到消息。若不传入该参数，无论接收方在线还是离线都能收到消息。 |
| `ext` | JSON | 否 | 消息支持扩展字段，可添加自定义信息。不能对该参数传入 `null`。同时，推送通知也支持自定义扩展字段，详见 [APNs 自定义显示](/document/ios/push.html#自定义显示) 和 [Android 推送字段说明](/document/android/push.html#自定义显示)。 |
| `ext.em_ignore_notification` | Bool | 否 | 是否发送静默消息：<br/> - `true`：是；<br/> - （默认）`false`：否。<br/> 发送静默消息指用户离线时，环信即时通讯 IM 服务不会通过第三方厂商的消息推送服务向该用户的设备推送消息通知。因此，用户不会收到消息推送通知。当用户再次上线时，会收到离线期间的所有消息。发送静默消息和免打扰模式下均为不推送消息，区别在于发送静默消息为发送方设置不推送消息，而免打扰模式为接收方设置在指定时间段内不接收推送通知。|
Expand Down Expand Up @@ -115,7 +115,7 @@ POST https://{host}/{org_name}/{app_name}/messages/chatgroups

#### 请求示例

发送给目标用户，消息无需同步给发送方：
发送给群组内所有成员，不论这些成员是否在线：

```bash
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
Expand All @@ -137,7 +137,7 @@ curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' \
}'
```

仅发送给在线用户，消息同步给发送方：
仅发送给在线用户，即 `routetype` 设置为 `ROUTE_ONLINE`：

```bash
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
Expand All @@ -156,8 +156,7 @@ curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups'
"ext": {
"em_ignore_notification": true
},
"routetype":"ROUTE_ONLINE",
"sync_device":true
"routetype":"ROUTE_ONLINE"
}'
```

Expand Down Expand Up @@ -804,6 +803,7 @@ curl -X POST -i "https://XXXX/XXXX/XXXX/messages/chatgroups" \
:::notice
1. 定向消息不写入会话列表，不计入群组会话的未读消息数。
2. 定向消息不支持消息漫游功能，因此从服务器拉取漫游消息时，不包含定向消息。
3. 群组中发送的定向消息均同步给发送方。
:::

**发送频率**：100 次/秒/App Key
Expand Down Expand Up @@ -838,7 +838,6 @@ POST https://{host}/{org_name}/{app_name}/messages/chatgroups/users
| `to` | Array | 是 | 消息接收方所属的群组 ID。每次只能传 1 个群组。 |
| `type` | String | 是 | 消息类型：<br/> - `txt`：文本消息；<br/> - `img`：图片消息；<br/> - `audio`：语音消息；<br/> - `video`：视频消息；<br/> - `file`：文件消息；<br/> - `loc`：位置消息；<br/> - `cmd`：透传消息；<br/> - `custom`：自定义消息。 |
| `body` | JSON | 是 | 消息内容。body 包含的字段见下表说明。 |
| `sync_device` | Bool | 否 | 消息发送成功后，是否将消息同步到发送方。<br/> - `true`：是；<br/> - （默认）`false`：否。 |
| `ext` | JSON | 否 | 消息支持扩展字段，可添加自定义信息。不能对该参数传入 `null`。同时，推送通知也支持自定义扩展字段，详见 [APNs 自定义显示](/document/ios/push.html#自定义显示) 和 [Android 推送字段说明](/document/android/push.html#自定义显示)。 |
| `ext.em_ignore_notification` | Bool | 否 | 是否发送静默消息：<br/> - `true`：是；<br/> - （默认）`false`：否。<br/> 发送静默消息指用户离线时，环信即时通讯 IM 服务不会通过第三方厂商的消息推送服务向该用户的设备推送消息通知。因此，用户不会收到消息推送通知。当用户再次上线时，会收到离线期间的所有消息。发送静默消息和免打扰模式下均为不推送消息，区别在于发送静默消息为发送方设置不推送消息，而免打扰模式为接收方设置在指定时间段内不接收推送通知。|
| `users` | Array | 是 | 接收消息的群成员的用户 ID 数组。每次最多可传 20 个用户 ID。 |
Expand Down Expand Up @@ -870,8 +869,6 @@ POST https://{host}/{org_name}/{app_name}/messages/chatgroups/users

#### 请求示例

发送给目标用户，消息无需同步给发送方：

```bash
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

Expand All @@ -893,27 +890,6 @@ curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups/users' \
}'
```

消息同步给发送方：

```bash
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups/users'
-H 'Content-Type: application/json'
-H 'Accept: application/json'
-H 'Authorization: Bearer <YourAppToken>'
-d '{
"from": "user1",
"to": ["184524748161025"],
"type": "txt",
"body": {
"msg": "testmessages"
},
"sync_device":true,
"users": ["user2", "user3"]
}'
```

#### 响应示例

```json
Expand Down

0 comments on commit 98daf07

Please sign in to comment.