消息管理
消息概述
环信即时通讯 IM 支持多种消息类型，开发者可以方便地对本地会话、消息进行管理，可以从服务端获取历史会话和消息，提供送达回执和已读回执能力。
消息：环信即时通讯 IM 中消息表示发送方给接收方发送的内容，消息包括多种类型，如：文本、图片、语音等。
会话：环信即时通讯 IM 中会话分为 3 种，单聊、群聊、聊天室会话。单聊是指 2 个用户建立的会话，双方可以在会话中收发消息。群聊会话是由群成员发送消息所组成的，群成员可以在群会话中收发消息。聊天室会话与群聊会话类似。
消息类型
| 类型 | 描述 |
|---|---|
| 文本消息 | 文本消息的内容是文本，包含超链接和表情符号等。表情消息基于文本消息实现。 文本消息大小限制为 5 KB。 |
| 图片消息 | 图片消息是附件消息，需要先将图片上传至消息服务器。接收方收到图片时自动下载图片缩略图。 图片默认不能超过 10 MB，图片消息大小限制为 5 KB。 |
| 语音消息 | 语音消息是附件消息，需要先将语音上传至消息服务器。接收方收到语音时自动下载语音。 音频文件默认不能超过 10 MB，音频消息大小限制为 5 KB。 |
| 视频消息 | 视频消息是附件消息，需要先将视频上传至消息服务器。接收方收到视频时自动下载视频缩略图，点击下载视频消息。对于 Web 端，视频消息没有缩略图。 视频文件默认不能超过 10 MB，视频消息大小限制为 5 KB。 |
| 文件消息 | 文件消息是附件消息，需要先将文件上传至消息服务器。 附件大小不能超过 10 MB，文件消息大小限制为 5 KB。 |
| 位置消息 | 位置消息需要第三方的地图服务提供经纬度信息。接收方接收到位置消息，通过经纬度信息可以在第三方的地图服务中显示位置。 |
| 透传消息 | 透传消息可视为命令消息。通过发送这条命令给对方，通知对方要执行的操作，对方收到消息后系统可以自定义处理。透传消息不会在 UI 上展示。 消息大小限制为 5 KB。 你可以使用透传消息更新头像和昵称以及进行状态同步等。 透传消息不会存入本地数据库。 |
| 消息自定义扩展 | 当基础的消息类型不满足需求时，可以使用消息自定义扩展增强基础消息类型。 使用扩展后，消息大小不能超过原类型消息的大小。 典型的用例是发送引用较早文本或图像消息的消息。 |
| 自定义消息 | 开发者自定义的消息类型。自定义消息支持设置类型名称，开发者可以添加多种自定义消息。 自定义消息大小限制为 5 KB。 自定义消息的使用场景：红包消息、模板消息等。 |
提示
- 默认情况下，消息附件，例如图片、音频、视频和其他文件不能超过 10 MB，可存储 7 天。若要提升其中一个上限，请联系商务。
- 消息附件的大小及存储时间限制与群组共享文件的相同。如果消息附件的其中一个限制进行了上调，群组共享文件的对应限制也会随之自动调整，反之亦然。
消息功能
环信即时通讯 IM 在消息服务器保存历史消息，方便用户在新设备上获取历史消息。历史消息存储时间与套餐版本相关，详见产品价格。
SDK 内部使用 SQLite 保存本地消息，方便消息处理。
下表为各平台/框架对消息功能的支持情况。
| 消息功能 | Android | iOS | Web | 小程序 | Flutter | React Native | Unity | Windows |
|---|---|---|---|---|---|---|---|---|
| 发送和接收消息 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 获取服务端历史消息 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 获取本地历史消息 | ✓ | ✓ | — | — | ✓ | ✓ | ✓ | ✓ |
| 撤回消息 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 搜索消息 | ✓ | ✓ | — | — | ✓ | ✓ | ✓ | ✓ |
| 修改消息 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 导入和插入消息 | ✓ | ✓ | — | — | ✓ | ✓ | ✓ | ✓ |
| 更新消息 | ✓ | ✓ | — | — | ✓ | ✓ | ✓ | ✓ |
| 删除服务端历史消息 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 删除本地历史消息 | ✓ | ✓ | — | — | ✓ | ✓ | ✓ | ✓ |
| 实现消息回执 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 翻译消息 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 获取消息流量统计 | ✓ | ✓ | — | — | — | — | — | — |
提示
- Web 和小程序端无本地消息存储。
- 对于 Android、iOS 平台，用户可以获取本地消息的流量统计信息。
发送和接收消息
用户可以在单聊、群聊、聊天室中发送如下类型的消息：
- 文字消息，包含超链接和表情消息。
- 附件消息，包含图片、语音、视频及文件消息。
- 位置消息。
- 透传消息。
- 自定义消息。
- 合并消息。
- 定向消息（只适用于群组聊天和聊天室聊天）。
当目前消息类型不满足用户需求时，可以在扩展部分保存更多信息，例如消息中需要携带被回复的消息内容或者是图文消息等场景。
获取历史消息
- 从服务器获取指定会话的历史消息。
- 从本地获取历史消息：
- 从数据库中读取指定会话的消息；
- 根据消息 ID 获取本地消息；
- 获取本地指定会话中特定类型的消息；
- 获取指定时间段内本地单个会话的消息。
提示
若要获取聊天室的历史消息，需联系环信商务。
撤回消息
发送方可以撤回一条发送成功的消息，包括已经发送的历史消息，离线消息或漫游消息。
撤回消息后，服务端的该条消息（历史消息，离线消息或漫游消息）以及消息发送方和接收方的内存和数据库中的消息均会被移除。
默认情况下，发送方可撤回发出 2 分钟内的消息。你可以在环信即时通讯云控制台的功能配置 > 功能配置总览 > 基础功能页面设置消息撤回时长，该时长不超过 7 天。
提示
除了透传消息，其他各类型的消息都支持撤回。
搜索消息
搜索消息支持以下方式的搜索：
- 根据关键字搜索本地数据库中单个会话中指定用户发送的消息。
- 根据搜索范围搜索所有会话以及当前会话中的消息：除了设置关键字、消息时间戳、消息数量、发送方、搜索方向等条件搜索所有会话中的消息时，你还可以选择搜索范围，如只搜索消息内容、只搜索消息扩展信息以及同时搜索消息内容以及扩展信息。
实现消息回执
即时通讯 IM 消息投递成功会返回送达回执，而且提供消息已读功能，接收方查看消息后会返回已读回执。
| 功能 | 描述 |
|---|---|
| 单聊消息送达回执 | 消息下发成功后，返回消息送达回执。 |
| 单聊消息已读回执 | 接收方查看消息后，返回消息已读回执。 |
| 单聊会话已读回执 | 接收方查看单聊会话后，返回会话已读回执。 |
| 群组消息已读回执 | 提供群组消息已读回执能力。 |
修改消息
对于单聊或群组聊天会话中已经发送成功的文本消息，SDK 支持对这些消息的内容进行修改。聊天室会话不支持消息修改功能。
对于修改后的消息，消息体中除了内容变化，还新增了修改者的用户 ID、修改时间和修改次数属性。除消息体外，该消息的其他信息（例如，消息发送方、接收方和扩展属性）均不会发生变化。
- 对于单聊会话，只有消息发送方才能对消息进行修改。
- 对于群聊会话，普通群成员只能修改自己发送的消息。群主和群管理员除了可以修改自己发送的消息，还可以修改普通群成员发送的消息。这种情况下，消息的发送方不变，消息体中的修改者的用户 ID 属性为群主或群管理员的用户 ID。
转发消息
转发消息即将会话中发送成功或收到的消息转发给别人，例如，用户 A 向用户 B 发送了一条消息，用户 B 收到后，将其转发给用户 C。环信即时通讯 IM 支持用户转发单条或多条消息。
- 转发单条消息：创建一条与原消息完全相同的消息，然后转发消息。
- 转发多条消息：发送合并消息。
导入和插入消息
你可以在本地会话中批量导入消息。当前用户只能导入自己发送或接收的消息。导入后，消息按照其包含的时间戳添加到对应的会话中。
如果你需要在本地会话中加入一条消息，比如收到某些通知消息时，可以构造一条消息写入会话。消息会根据消息中的 Unix 时间戳插入本地数据库，SDK 会更新会话的 latestMessage 等属性。
更新消息
你可以更新本地数据库中的消息。
删除消息
单向删除服务端的历史消息：删除后，消息自动从设备本地移除且该用户无法从服务端拉取到该消息。其他用户不受该操作影响。每次最多可删除 50 条消息。
登录该账号的其他设备会收到漫游消息删除回调。
置顶消息
消息置顶指将会话中的消息固定在会话列表的顶部，方便用户查找。例如，将重点消息置顶，可快速定位消息。
目前，群组和聊天室聊天支持对消息置顶和取消置顶，单聊消息不支持该功能。
- 置顶和取消置顶消息。
- 从服务端获取单个会话的置顶消息列表。
- 获取单条消息的置顶详情
翻译消息
环信即时通讯 IM SDK 集成了 Microsoft Azure Translation API，支持在发送或接收消息时对文本消息进行按需翻译或自动翻译：
- 按需翻译：接收方在收到文本消息后，将消息内容翻译为目标语言。
- 自动翻译：发送方发送消息时，SDK 根据发送方设置的目标语言自动翻译文本内容，然后将消息原文和译文一起发送给接收方。
只投在线用户
环信即时通讯 IM 支持只将消息投递给在线用户。若接收方不在线，则无法收到消息。该功能用于实现应用只需要向在线用户进行展示目的，例如，利用透传消息实现群投票的票数实时变化, 只有在线用户需要关注实时变化的动态, 离线用户只需要再次上线时获取最终状态。
各类型的消息均支持该功能，但该功能只支持单聊和群组聊天，不适用于聊天室。 该类的消息与普通消息相比，存在如下差异：
- 不支持离线存储：若发送消息时，接收方离线则无法收到消息，即使重新登录后也收不到消息。对于普通消息，当接收方在线时, 实时收到消息提醒；当接收方离线时，实时发送离线推送消息，接收方再次上线时, 由环信 IM 服务器主动推给客户端离线期间的消息。
- 支持本地存储：消息成功发送后，写入数据库。
- 默认不支持漫游存储：发送的消息默认不存储在环信消息服务器，用户在其他终端设备上无法获取到该消息。如需开通在线消息的漫游存储，需联系环信商务。
获取消息流量统计
对于 Android 和 iOS 平台，用户可以获取本地消息的流量统计信息。
| 功能 | 描述 |
|---|---|
| 根据消息 ID 获取消息流量统计信息 | 你可以根据消息 ID 获取指定消息的统计信息。该方法返回的消息流量统计信息包括消息 ID、消息的发送方和接收方、消息体类型、会话类型、消息方向、消息流量大小（单位为字节）以及服务器收到该消息的 Unix 时间戳。 |
| 获取一定时间段内发送和/或接收的消息条数 | 你可以统计一定时间段内发送和/或接收的指定或全部类型的消息。 |
| 获取一定时间段内发送和/或接收的消息的总流量 | 你可以统计一定时间段内发送和/或接收的指定或全部类型的消息的总流量，流量单位为字节。 |
消息存储
消息存储分为本地存储和服务器存储：
SDK 存储：SDK 内部使用 SQLite 保存本地消息，你可以获取本地消息。
服务器存储：历史消息和离线消息在服务器上的存储时间与你订阅的套餐包有关，详见产品价格。环信即时通讯 IM 提供消息漫游功能，即将用户的所有会话的历史消息保存在消息服务器，用户在任何一个终端设备上都能获取到历史信息，使用户在多个设备切换使用的情况下也能保持一致的会话场景。
默认情况下，消息附件可在服务器存储 7 天。若要提升该限制，你需要联系商务。
各类事件通知发送时，若接收的用户离线时，事件通知的存储时间与离线消息的存储时间一致，即也取决于你订阅的套餐包。
消息重发机制
- 对于 Android、iOS 、Windows 端和三个跨平台框架 Unity、React Native 和 Flutter 来说，消息重发机制如下：
客户端调用发送消息的方法后，会等待服务器返回响应，超时时间为 10 秒。若因响应超时导致发送失败，客户端会再次尝试发送消息，即通过长连接重连服务器，然后发送消息。如果再次失败，SDK 认为消息发送失败，返回服务器不可达的错误消息，即错误码 300，Android 为 EMErrorServerNotReachable，iOS 和 Windows 为 SERVER_NOT_REACHABLE。
- 对于 Web 来说，消息重发机制如下：
发送消息时如果 WebSocket 已经断开正在进行重连时，重新连接后会重新发送消息；若 WebSocket 断开时发送消息，SDK 会提示网络断开连接导致消息发送失败的错误，即错误码 510 MESSAGE_WEBSOCKET_DISCONNECTED。