群组消息
大约 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 管理员向任意群组发送消息 |
| 群组消息离线推送 | 支持苹果、华为、荣耀、OPPO、vivo、小米、魅族等品牌设备的离线推送 | 群组消息离线推送 |
| 接收群组在线消息 | 群成员可以通过 IM SDK 接收群组在线消息 | 在线群成员实时接收群消息 |
| 群组成员获取离线/历史消息 | 群成员通过 IM SDK 接口查询历史消息 | 群组成员上线接收离线消息，群成员查看群聊天记录 |
| App server 获取群组消息 | - App 管理员可通过 RESTful API 下载 App 在某一段时间内产生所有的消息； - App 管理员通过 RESTful API，获取任意群的聊天记录； - App server 可以通过群组发消息回调，实时获取群消息。 | - App 定期备份消息记录； - App 需要获取某个群组历史消息； - App 需要实时获取群组消息 |
| 消息删除 | 可通过调用 RESTful API 或 SDK API 删除历史消息 | - 避免恶意信息传播 - 保护隐私 - 管理存储空间 |
| 群聊消息中携带发送者资料 | 通过消息扩展字段在群消息中携带发送者的昵称、头像、用户或群组相关的自定义字段 | 展示消息发送方昵称、头像等用户信息 |
| 群消息发送控制 | 通过禁言、封禁群组、群消息发送前回调、黑名单、内容审核进行发送控制。 | - 禁止群内某个成员发送消息 - 禁止群组内所有成员在该群内发消息 - App server 过滤或修改消息 |
| 群消息接收控制 | - 用户可通过 SDK API 屏蔽某个群组的消息 - 封禁群组 (RESTful) | - 用户不再接收某个群组的消息 - 禁用群组中所有成员在该群内发送和接收消息 |
| 群消息频率控制 | 对于单个 app，RESTful API 存在以下 3 个限制： - 20 条/秒/App Key - 20 次/秒 - 3 个群/次。 | 避免 RESTful API 调用过于频繁，如要上调这些限制，需联系商务。 |
群组消息发送控制
| 群组消息发送控制 | 描述 |
|---|---|
| 禁止发送消息 | - 黑名单：成员加入黑名单后，会被移出群组，无法再收发消息。 - 禁言：成员被加入禁言列表后，将无法在群组内发送消息，即使其被加入白名单也不能发消息，但可以正常接收消息。全员禁言开启后，除了在白名单中的成员，其他成员不能发消息。 - 全局禁言 （RESTful API）：用户被全局禁言后，无法发送单聊消息、或在无法在所有群组或聊天室中发送消息。群组或聊天室白名单中的成员被全局禁言后，仍无法在所有单聊、群组或聊天室中发消息。 |
| 对消息放行或拦截 | - 发送前回调：环信 IM 服务器会在发送消息之前，向你的应用服务器发送请求，你可以根据业务需求配置规则决定下发或拦截消息。 - 内容审核：基于内容审核结果对消息进行处理，包括拦截、替换敏感信息和放行消息。该服务只对文本、图片、音频和视频消息有效。 |
群组消息频率控制
REST API
对于单个 app，发送群聊消息 RESTful API 存在以下限制（你可以联系环信商务上调限制）：
限制 | 描述 | 超限报错 | 是否可调 |
20 次/秒 | 每秒限调 20 次。 | 例如，你每次调用该 API 向单个或多个群组发送消息，可调用 20 次。第 21 次调用时会报 429 错误 “This request has reached api limit”。 | 两个限制均可调。若上调其中一个，另一个自动等比例提升。 例如，将 20 次/秒上调至 100 次/秒后，每秒限发条数也会自动上调至 100，即 100 条/秒。反之，将 20 条/秒上调至 100 条/秒后，每秒限调次数自动上调至 100，即 100 次/秒。 |
20 条/秒 | 每秒限发 20 条消息。 | 例如，你每次向 3 个群组发送消息，即发送了 3 条消息，你每秒最多可调用 7 次。第 8 次调用时，则报 403 错误，即 " message send reach limit"。 | |
3 个群/次 | 每次限发 3 个群。 | 若超限，报 400 错误，即 "param to exceed limit"。 | 不可调 |
SDK
默认情况下，SDK 对单个用户发送消息的频率未做限制。如果你联系了环信商务设置了该限制，一旦在群聊中单个用户的消息发送频率超过设定的上限，SDK 会上报错误，例如 Android 端的错误码为 509 MESSAGE_CURRENT_LIMITING。
消息格式
关于各类型消息格式以及离线推送的消息扩展字段，详见消息格式文档。