聊天室消息
大约 8 分钟
产品介绍
聊天室消息
应用场景
- 多用户聊天室内沟通：聊天室中的成员通过收发消息进行沟通。
- App 管理员向聊天室发消息：App 管理员通过调用 RESTful API 在聊天室内发送消息。
消息类型
| 类型 | 描述 |
|---|---|
| 文本消息 | 文本消息的内容是文本，包含超链接和表情符号等。表情消息基于文本消息实现。 文本消息大小限制为 5 KB。 |
| 位置消息 | 位置消息需要第三方的地图服务提供经纬度信息。接收方接收到位置消息，通过经纬度信息可以在第三方的地图服务中显示位置。 |
| 透传消息 | 透传消息可视为命令消息。通过发送这条命令给对方，通知对方要执行的操作，对方收到消息后系统可以自定义处理。 - 透传消息不会在 UI 上展示。 - 消息大小限制为 5 KB。 - 你可以使用透传消息更新头像和昵称以及进行状态同步等。 透传消息不会存入本地数据库。 |
| 图片消息 | 图片消息是附件消息，需要先将图片上传至消息服务器。接收方收到图片时自动下载图片缩略图。 图片默认不能超过 10 MB，图片消息大小限制为 5 KB。 |
| 语音消息 | 语音消息是附件消息，需要先将语音上传至消息服务器。接收方收到语音时自动下载语音。 音频文件默认不能超过 10 MB，音频消息大小限制为 5 KB。 |
| 视频消息 | 视频消息是附件消息，需要先将视频上传至消息服务器。接收方收到视频时自动下载视频缩略图，点击下载视频消息。 - 对于 Web 端，视频消息没有缩略图。 - 视频文件默认不能超过 10 MB，视频消息大小限制为 5 KB。 |
| 文件消息 | 文件消息是附件消息，需要先将文件上传至消息服务器。 附件大小不能超过 10 MB，文件消息大小限制为 5 KB。 |
| 自定义消息 | 开发者自定义的消息类型。自定义消息支持设置类型名称，开发者可以添加多种自定义消息。 - 自定义消息大小限制为 5 KB。 - 自定义消息的使用场景：红包消息、模板消息等。 |
提示
- 默认情况下，消息附件，例如图片、音频、视频和其他文件不能超过 10 MB，可存储 7 天。若要提升其中一个上限，请联系商务。
- 当基础的消息类型不满足需求时，可以使用消息自定义扩展增强基础消息类型，典型的用例是发送引用较早文本或图像消息的消息。使用扩展后，消息大小不能超过原类型消息的大小。
聊天室消息能力
| 类型 | 功能描述 | 应用场景 |
|---|---|---|
| 发送聊天室普通消息 | 聊天室成员可以通过 IM SDK 接口发送消息。App 管理员无需加入聊天室，即可调用 RESTful API 在任意聊天室中发送消息。 | 聊天室成员在聊天室内发送消息，App 管理员向任意聊天室发送消息 |
| 接收聊天室在线消息 | 聊天室成员可以通过 IM SDK 接收聊天室在线消息 | 在线聊天室成员实时接收聊天室消息 |
| 聊天室成员获历史消息 | 聊天室成员通过 IM SDK 接口查询历史消息 需要升级 SDK 到指定版本，并联系环信商务开通。 | 聊天室成员查看聊天室聊天记录 |
| App server 获取聊天室消息 | - App 管理员可通过 RESTful API 下载 App 在某一段时间内产生所有的消息； - App 管理员通过 RESTful API，获取任意聊天室的聊天记录； - App server 可以通过聊天室发消息回调，实时获取聊天室消息。 | - App 定期备份消息记录； - App 需要获取某个聊天室的历史消息； - App 需要实时获取聊天室消息 |
| 聊天室消息中携带发送者资料 | 通过消息扩展字段在聊天室消息中携带发送者的昵称、头像、用户或聊天室相关的自定义字段 | 展示消息发送方昵称、头像等用户信息 |
| 聊天室消息发送控制 | 通过禁言、聊天室消息发送前回调、黑名单、内容审核进行发送控制。 | - 禁止聊天室内某个成员发送消息 - 禁止聊天室内所有成员在该聊天室内发消息 - App server 过滤或修改消息 |
| 聊天室消息频率控制 | 对于单个 app，RESTful API 存在以下 3 个限制： - 10 个聊天室/次 - 100 条/秒 - 100 次/秒 | 控制接口的调用 |
提示
与群组聊天不同，聊天室不支持消息离线推送。
聊天室消息发送控制
| 聊天室消息发送控制 | 描述 |
|---|---|
| 消息发送优先级 | 你可以设置聊天室的消息优先级：高、普通和低三种级别。在聊天室内消息并发量较大或消息发送频率过高的情况下，服务器首先丢弃低优先级消息，优先送达高优先级的消息。 |
| 消息优先发送（聊天室白名单） | 聊天室白名单中的成员在聊天室中发送的消息为高优先级，会优先送达，但不保证必达。当负载较高时，服务器会优先丢弃低优先级的消息。即便如此若负载仍很高，服务器也会丢弃高优先级消息。 |
| 禁止发送消息 | - 黑名单：成员加入黑名单后，会被移出聊天室，无法再收发消息。 - 禁言：成员被加入禁言列表后，将无法在聊天室内发送消息，即使其被加入白名单也不能发消息，但可以正常接收消息。全员禁言 开启后，除了在白名单中的成员，其他成员不能发消息。 - 全局禁言 （RESTful API）：用户被全局禁言后，无法发送单聊消息、或在无法在所有群组或聊天室中发送消息。聊天室白名单中的成员被全局禁言后，仍无法在所有单聊、群组或聊天室中发消息。 |
| 对消息放行或拦截 | - 发送前回调：环信 IM 服务器会在发送消息之前，向你的应用服务器发送请求，你可以根据业务需求配置规则决定下发或拦截消息。 - 内容审核：基于内容审核结果对消息进行处理，包括拦截、替换敏感信息和放行消息。该服务只对文本、图片、音频和视频消息有效。 |
聊天室消息频率控制
REST API
对于单个 app，发送聊天室消息 RESTful API 存在以下限制（你可以联系环信商务上调限制）：
限制 | 描述 | 超限报错 | 是否可调 |
100 次/秒 | 每秒限调 100 次。 | 第 101 次调用时会报 429 错误：This request has reached api limit。 | 两个限制均可调。若上调其中一个，另一个自动等比例提升。 例如，将 100 次/秒上调至 200 次/秒后，每秒限发条数自动上调至 200，即 200 条/秒。反之，将 100 条/秒上调至 200 条/秒后，每秒限调次数自动上调至 200，即 200 次/秒。 |
100 条/秒 | 每秒限发 100 条消息。 | 例如，你每次向 10 个聊天室发送消息，即发送了 10 条消息，你每秒最多可调用 10 次该接口。第 11 次调用时，则报 403 错误，即 "message send reach limit"。 | |
10 个聊天室/次 | 例如，你每次向 10 个聊天室发送消息，即发送了 10 条消息。 | 若超限，报 400 错误，即 "param to exceed limit"。 | 不可调 |
SDK
默认情况下，SDK 对单个用户发送消息的频率未做限制。如果你联系了环信商务设置了该限制，一旦在聊天室中单个用户的消息发送频率超过设定的上限，SDK 会上报错误，例如 Android 端错误码为 509
MESSAGE_CURRENT_LIMITING。
消息格式
关于各类型消息格式以及离线推送的消息扩展字段，详见 消息格式文档。