单聊消息
大约 6 分钟
产品介绍
单聊消息
应用场景
- App 内一对一聊天：两个用户进行一对一私聊。
- App 管理员向用户发消息：App 管理员调用 RESTful API 向 app 用户发送消息，也可以其他用户的身份发送消息。
单聊消息类型
| 类型 | 描述 |
|---|---|
| 文本消息 | 文本消息的内容是文本，包含超链接和表情符号等。表情消息基于文本消息实现。 文本消息大小限制为 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 天。若要提升其中一个上限，请联系商务。
- 当基础的消息类型不满足需求时，可以使用消息自定义扩展增强基础消息类型，典型的用例是发送引用较早文本或图像消息的消息。使用扩展后，消息大小不能超过原类型消息的大小。
单聊消息发送控制
| 单聊消息发送控制 | 描述 |
|---|---|
| 陌生人之间发送消息 | App 内任意两个用户之间均可发送单聊消息。该场景下，在环信即时通讯控制台的 即时通讯 > 服务概览 页面的 设置 区域下关闭了 好友关系检查 功能。 |
| App 管理员发送单聊消息 | App 管理员模拟其他用户向 app 内任意用户发送消息。 |
| 只给好友发送消息 | 只能给好友发送消息，即在环信即时通讯控制台的 即时通讯 > 服务概览 页面的 设置 区域下打开 好友关系检查 功能。 |
| 拒绝来自某用户的消息 | 可通过以下两种方法拒绝来自某个用户的消息： - 将用户添加到黑名单，拒绝来自该用户的消息。 - 将该用户从联系人列表移除。 这种情况适用于 app 仅支持好友之间发送消息的情况。如果 app 支持陌生人之间发送消息，例如，用户 A 从用户 B 的联系人列表移除，用户 A 仍然可以向用户 B 发送消息吧。 - 全局禁言 （RESTful API）：可通过对单个用户进行单聊全局禁言，使指定用户无法向 app 内的任何用户发送单聊消息。 |
| 对消息放行或拦截 | - 发送前回调：环信 IM 服务器会在发送消息之前，向你的应用服务器发送请求，你可以根据业务需求配置规则决定下发或拦截消息。 - 内容审核：基于内容审核结果对消息进行处理，包括拦截、替换敏感信息和放行消息。该服务只对文本、图片、音频和视频消息有效。 |
单聊消息发送频率限制
REST API
对于单个 app，发送单聊消息 REST API 默认存在以下限制（你可以联系环信商务上调限制）：
限制 | 描述 | 超限报错 | 是否可调 |
100 次/秒 | 每秒限调 100 次 | 若超限，报 429 错误 即 “This request has reached api limit”。 | 两个限制均可调且相互关联，即上调其中一个，另一个自动等比例提升。 例如，将 100 次/秒上调至 200 次/秒后，每分钟限发消息条数也会自动上调至 12000，即 12000 条/分钟。反之，若将 6000 条/分钟上调至 12000 条/分钟，每秒的调用次数上限也自动提升至 200，即 200 次/秒。 |
6000 条/分钟 | 每分钟限发 6000 条消息 | 若超限，报 403 错误，即 " message send reach limit"。
| |
600 人/次 | 每次限发 600 人。 例如，一次向 600 人发消息，视为 600 条消息。 | 若超限，报 400 错误，即 "param to exceed limit"。 | 不可调。 |
SDK
默认情况下，SDK 对单个用户发送消息的频率未做限制。如果你联系了环信商务设置了该限制，一旦在单聊中单个用户的消息发送频率超过设定的上限，SDK 会上报错误，例如 Android 端的错误码为 509 MESSAGE_CURRENT_LIMITING。
单聊消息扩展能力
| 单聊消息扩展能力 | 功能描述 | 应用场景 |
|---|---|---|
| 获取聊天记录 | 可通过 SDK 或 REST API 获取历史消息 | - 获取实时聊天记录 - 定期下载消息记录 |
| 多终端同步 | 支持单聊消息多终端同步 | 用户多终端消息同步 |
| 单聊消息离线推送 | 支持苹果、华为、荣耀、OPPO、vivo、小米、和魅族等品牌设备的离线推送 | 消息离线推送 |
| 单聊消息中携带发送者资料 | 通过消息扩展字段实现消息中携带发送者资料 | 展示发送者昵称、头像等 |
消息格式
关于各类型消息格式以及离线推送的消息扩展字段，详见消息格式文档。