消息概述
消息概述
消息：表示发送方给接收方发送的内容。消息包括多种类型，如：文本、图片、语音、视频、位置消息等。
利用即时通讯 IM，开发者可方便以会话为单位对本地消息进行管理，从服务端获取历史会话和消息，提供消息回执等功能。
消息应用场景
| 消息 | 应用场景 |
|---|---|
| 单聊消息 | - 应用内一对一聊天 - 应用管理员向用户发消息 - 向单个用户发送系统通知 |
| 群组消息 | - 多用户群组内沟通 - 应用管理员向群组发消息 - 向群组发送系统通知 |
| 聊天室消息 | - 多用户聊天室内沟通 - 应用管理员向聊天室发消息 - 向所有聊天室发系统通知 |
消息类型
消息分为以下三大类：
- 非附件类消息：文本消息、位置消息、透传消息；
- 附件类消息：图片消息、语音消息、视频消息；
- 自定义消息。
| 类型 | 描述 |
|---|---|
| 文本消息 | 文本消息的内容是文本，包含超链接和表情符号等。表情消息基于文本消息实现。 文本消息大小限制为 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 的消息功能包括发送和接收消息、获取历史消息、撤回消息、搜索、修改和转发消息、以及导入、更新、删除和置顶消息等。
下表为各平台/框架支持的消息功能。
| 消息功能 | Android | iOS | Web | 小程序 | HarmonyOS | Flutter | React Native | Unity | Windows |
|---|---|---|---|---|---|---|---|---|---|
| 发送和接收消息 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 获取服务端历史消息 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 获取本地历史消息 | ✓ | ✓ | — | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| 撤回消息 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 搜索消息 | ✓ | ✓ | — | — | — | ✓ | ✓ | ✓ | ✓ |
| 修改消息 | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ |
| 转发消息 | ✓ | ✓ | — | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| 导入和插入消息 | ✓ | ✓ | — | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| 更新消息 | ✓ | ✓ | — | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| 删除服务端历史消息 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 删除本地历史消息 | ✓ | ✓ | — | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| 消息回执 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 置顶消息 | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
| 翻译消息 | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
| 只投在线用户 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 获取消息流量统计 | ✓ | ✓ | — | — | — | — | — | — | — |
| 多端同步 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 离线推送 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
消息发送控制
单聊消息发送控制
| 单聊消息发送控制 | 描述 |
|---|---|
| 陌生人之间发送消息 | App 内任意两个用户之间均可发送单聊消息。 |
| App 管理员发送单聊消息 | App 管理员模拟其他用户向 app 内任意用户发送消息。 |
| 只给好友发送消息 | 只能给好友发送消息。你可以联系声网商务开通。 |
| 拒绝来自某用户的消息 | 可通过以下两种方法拒绝来自某个用户的消息： - 将用户添加到黑名单，拒绝来自该用户的消息。 - **将该用户从联系人列表移除。**这种情况适用于 app 仅支持好友之间发送消息的情况。如果 app 支持陌生人之间发送消息，例如，用户 A 从用户 B 的联系人列表移除，用户 A 仍然可以向用户 B 发送消息吧。 - 全局禁言 （RESTful API）：可通过全局禁言功能，使指定用户无法向 app 内的任何用户发送单聊消息。 |
| 对消息放行或拦截 | 发送前回调：即时通讯 IM 服务器会在发送消息之前，向你的应用服务器发送请求，你可以根据业务需求配置规则决定下发或拦截消息。 |
群组/聊天室消息发送控制
| 群组/聊天室消息发送控制 | 描述 |
|---|---|
| 消息发送优先级（仅对聊天室有效） | 你可以设置聊天室的消息优先级：高、普通和低三种级别。在聊天室内消息并发量较大或消息发送频率过高的情况下，服务器首先丢弃低优先级消息，优先送达高优先级的消息。 |
| 消息优先发送（聊天室白名单） | 聊天室白名单中的成员在聊天室中发送的消息为高优先级，会优先送达，但不保证必达。当负载较高时，服务器会优先丢弃低优先级的消息。即便如此若负载仍很高，服务器也会丢弃高优先级消息。 |
| 禁止发送消息 | - 黑名单：成员加入黑名单后，会被移出群组/聊天室，无法再收发消息。 - 禁言：成员被加入禁言列表后，将无法在群组/聊天室内发送消息，即使其被加入白名单也不能发消息，但可以正常接收消息。全员禁言开启后，除了在白名单中的成员，其他成员不能发消息。 - 全局禁言 （RESTful API）：用户被全局禁言后，无法发送单聊消息、或在无法在所有群组或聊天室中发送消息。群组或聊天室白名单中的成员被全局禁言后，仍无法在所有单聊、群组或聊天室中发消息。 |
| 对消息放行或拦截 | 发送前回调：即时通讯 IM 服务器会在发送消息之前，向你的应用服务器发送请求，你可以根据业务需求配置规则决定下发或拦截消息。 |
消息存储
消息存储分为本地存储和服务器存储。例如，客户端 A 向客户端 B 发送消息，客户端 A 发送消息到声网服务器的同时，SDK 会保存这条消息到本地数据库（SDK 内部创建数据库，不允许直接操作），声网服务器将消息发送到客户端 B 的同时也会进行记录，客户端 B 收到消息后，SDK 会将消息存储到本地数据库。
SDK 存储
SDK 内部使用 SQLite 保存本地消息，你可以获取本地消息。
提示
Web 和小程序端无本地消息存储。
服务端存储
历史消息存储
历史消息在服务器上的存储时间与你订阅的套餐包有关，详见产品价格。即时通讯 IM 提供消息漫游功能，即将用户的所有会话的历史消息保存在消息服务器，用户在任何一个终端设备上都能获取到历史信息，使用户在多个设备切换使用的情况下也能保持一致的会话场景。默认可获取单聊和群组聊天的历史消息。若要获取聊天室的历史消息，需联系声网商务。
消息附件的存储
默认情况下，消息附件可在服务器存储 7 天。若要提升该限制，你需要联系声网商务。消息附件的大小及存储时间限制与群组共享文件的相同。如果消息附件的其中一个限制进行了上调，群组共享文件的对应限制也会随之自动调整，反之亦然。
离线消息存储
对于单聊和群聊，离线消息默认保存 7 天。对于每个终端用户，所有的单聊会话可存储 500 条离线消息，所有的群聊会话可存储 200 条离线消息。若超过存储天数和条数的上限，最新的离线消息会挤掉最早的。如需提升上限，可联系声网商务。
事件通知存储
各类事件通知的存储时间与消息的存储一致。
消息重发机制
- 对于 Android、iOS 、HarmonyOS、Windows 端和三个跨平台框架 Unity、React Native 和 Flutter 来说，消息重发机制如下：
客户端调用发送消息的方法后，会等待服务器返回响应，超时时间为 10 秒。若因响应超时导致发送失败，客户端会再次尝试发送消息，即通过长连接重连服务器，然后发送消息。如果再次失败，SDK 认为消息发送失败，返回服务器不可达的错误消息，即错误码 300，iOS 为 EMErrorServerNotReachable，Android, HarmonyOS 和 Windows 为 SERVER_NOT_REACHABLE。
- 对于 Web 来说，消息重发机制如下：
发送消息时如果 WebSocket 已经断开正在进行重连时，重新连接后会重新发送消息；若 WebSocket 断开时发送消息，SDK 会提示网络断开连接导致消息发送失败的错误，即错误码 510 MESSAGE_WEBSOCKET_DISCONNECTED。
消息格式
关于各类型消息格式以及离线推送的消息扩展字段，详见消息格式文档。