消息概述
消息管理
环信即时通讯 IM 支持多种消息类型,开发者可以方便地对本地会话、消息进行管理,可以从服务端获取历史会话和消息,提供送达回执和已读回执能力。
消息:环信即时通讯 IM 中消息表示发送方给接收方发送的内容,消息包括多种类型,如:文本、图片、语音等。
会话:环信即时通讯 IM 中会话分为 3 种,单聊、群聊、聊天室会话。单聊是指 2 个用户建立的会话,双方可以在会话中收发消息。群聊会话是由群成员发送消息所组成的,群成员可以在群会话中收发消息。聊天室会话与群聊会话类似。
消息类型
类型 | 描述 |
---|---|
文本消息 | 文本消息的内容是文本,可以包含超链接、emoji 表情符号等。表情消息是基于文本消息实现的。 文本消息大小限制为 5 KB。 |
图片消息 | 图片消息是附件消息,需要先将图片上传至消息服务器。接收方收到图片时自动下载图片缩略图。 图片不能超过 10 MB,图片消息大小限制为 5 KB。 |
语音消息 | 语音消息是附件消息,需要先将语音上传至消息服务器。接收方收到语音时自动下载语音。 音频文件不能超过 10 MB,音频消息大小限制为 5 KB。 |
视频消息 | 视频消息是附件消息,需要先将视频上传至消息服务器。接收方收到视频时自动下载视频缩略图,点击下载视频消息。 视频文件不能超过 10 MB,视频消息大小限制为 5 KB。 |
文件消息 | 文件消息是附件消息,需要先将文件上传至消息服务器。接收方收到文件时自动下载文件。 附件大小不能超过 10 MB,文件消息大小限制为 5 KB。 |
位置消息 | 位置消息需要第三方的地图服务提供经纬度信息。接收方接收到位置消息,通过经纬度信息可以在第三方的地图服务中显示位置。 |
透传消息 | 透传消息可视为命令消息,通过发送这条命令给对方,通知对方要执行的操作,对方收到消息后系统可以自定义处理。透传消息不会在 UI 上展示。 消息大小限制为 5 KB。 透传消息的使用场景:头像、昵称的更新、状态同步等。 透传消息不会存入本地数据库。 |
消息自定义扩展 | 当基础的消息类型不满足需求时,可以使用消息自定义扩展增强基础消息类型。 使用扩展后,消息大小不能超过原类型消息的大小。 消息自定义扩展的使用场景:消息中需要携带被回复的消息内容和图文消息等。 |
自定义消息 | 开发者自定义的消息类型。自定义消息支持设置类型名称,开发者可以添加多种自定义消息。 自定义消息大小限制为 5 KB。 自定义消息的使用场景:红包消息、模板消息等。 |
消息功能
Web 和小程序端无本地消息存储,只支持管理服务端消息。
- 发送和接收消息;
- 获取历史消息;
- 撤回消息;
- 置顶消息;
- 修改消息;
- 删除消息;
- 消息回执;
- 翻译消息。
发送和接收消息
用户可以在单聊、群聊、聊天室中发送如下类型的消息:
- 文字消息,包含超链接和表情消息。
- 附件消息,包含图片、语音、视频及文件消息。
- 位置消息。
- 透传消息。
- 自定义消息。
- 合并消息。
- 定向消息(只适用于群组聊天和聊天室聊天)。
当目前消息类型不满足用户需求时,可以在扩展部分保存更多信息,例如消息中需要携带被回复的消息内容或者是图文消息等场景。
获取历史消息
从服务器获取指定会话的历史消息。默认可获取单聊和群组聊天的历史消息。若要获取聊天室的历史消息,需联系环信商务。
撤回消息
发送方可以撤回一条发送成功的消息,包括已经发送的历史消息,离线消息或漫游消息。
撤回消息后,服务端的该条消息(历史消息,离线消息或漫游消息)以及消息发送方和接收方的内存和数据库中的消息均会被移除。
默认情况下,发送方可撤回发出 2 分钟内的消息。你可以在环信即时通讯云控制台的功能配置 > 功能配置总览 > 基础功能页面设置消息撤回时长,该时长不超过 7 天。
置顶消息
消息置顶指将会话中的消息固定在会话的顶部,方便用户查找。例如,将重点消息置顶,可快速定位消息。
目前,群组和聊天室聊天支持对消息置顶和取消置顶,单聊消息不支持该功能。
修改消息
对于单聊或群组聊天会话中已经发送成功的文本消息,SDK 支持对这些消息的内容进行修改。聊天室会话不支持消息修改功能。
对于修改后的消息,消息体中除了内容变化,还新增了修改者的用户 ID、修改时间和修改次数属性。除消息体外,该消息的其他信息(例如,消息发送方、接收方和扩展属性)均不会发生变化。
- 对于单聊会话,只有消息发送方才能对消息进行修改。
- 对于群聊会话,普通群成员只能修改自己发送的消息。群主和群管理员除了可以修改自己发送的消息,还可以修改普通群成员发送的消息。这种情况下,消息的发送方不变,消息体中的修改者的用户 ID 属性为群主或群管理员的用户 ID。
删除消息
单向删除服务端的历史消息:删除后,消息自动从设备本地移除且该用户无法从服务端拉取到该消息。其他用户不受该操作影响。每次最多可删除 50 条消息。
登录该账号的其他设备会收到漫游消息删除回调。
消息回执
即时通讯 IM 消息投递成功会返回送达回执,而且提供消息已读功能,接收方查看消息后会返回已读回执。
功能 | 描述 |
---|---|
单聊消息送达回执 | 消息下发成功后,返回消息送达回执。 |
单聊消息已读回执 | 接收方查看消息后,返回消息已读回执。 |
单聊会话已读回执 | 接收方查看单聊会话后,返回会话已读回执。 |
群组消息已读回执 | 提供群组消息已读回执能力。 |
翻译消息
环信即时通讯 IM SDK 集成了 Microsoft Azure Translation API,支持在发送或接收消息时对文本消息进行按需翻译或自动翻译:
- 按需翻译:接收方在收到文本消息后,将消息内容翻译为目标语言。
- 自动翻译:发送方发送消息时,SDK 根据发送方设置的目标语言自动翻译文本内容,然后将消息原文和译文一起发送给接收方。
只投在线用户
环信即时通讯 IM 支持只将消息投递给在线用户。若接收方不在线,则无法收到消息。该功能用于实现应用只需要向在线用户进行展示目的,例如,利用透传消息实现群投票的票数实时变化, 只有在线用户需要关注实时变化的动态, 离线用户只需要再次上线时获取最终状态。
各类型的消息均支持该功能,但该功能只支持单聊和群组聊天,不适用于聊天室。 该类的消息与普通消息相比,存在如下差异:
- 不支持离线存储:若发送消息时,接收方离线则无法收到消息,即使重新登录后也收不到消息。对于普通消息,当接收方在线时, 实时收到消息提醒;当接收方离线时,实时发送离线推送消息,接收方再次上线时, 由环信 IM 服务器主动推给客户端离线期间的消息。
- 默认不支持漫游存储:发送的消息默认不存储在环信消息服务器,用户在其他终端设备上无法获取到该消息。如需开通在线消息的漫游存储,需联系环信商务。
消息重发机制
发送消息时如果 WebSocket 已经断开正在进行重连时,重新连接后会重新发送消息;若 WebSocket 断开时发送消息,SDK 会提示网络断开连接导致消息发送失败的错误,即错误码 510 MESSAGE_WEBSOCKET_DISCONNECTED
。