# 概述
一般系统消息特指会话类型(ConversationType)为“系统(SYSTEM)”的会话中的消息。
系统消息(System Message)是一种业务概念,是指利用系统帐号(非用户帐号,用户不可登录)向用户发送的消息,既可以是通过调用全量通知接口发送给所有人的消息,也可以是加好友提醒等单个用户通知消息。
# 主要功能
系统通知消息,只能通过 Server API 进行发送,终端用户收到系统消息后,不支持消息回复功能。
功能 | 描述 |
---|---|
离线消息 | 支持离线消息存储,存储时间可设置(1 ~ 7 天),默认存储 7 天。 |
消息提醒 | 离线状态,系统会话有新消息时,支持 Push 通知。 |
本地存储 | 存储在移动端本地,提供本地消息搜索功能。 |
历史消息 | 提供服务端消息存储存功能,需开通单群聊消息云存储,默认存储时长为 6 个月。 |
单个用户通知 | 向单个或多个用户发送系统消息。 |
标签用户通知 | 向标签下的所有用户发送系统消息,用户标签属性需要开发者通过 Server API 接口进行设置。 |
全量用户落地通知 | 向应用下的所有用户发送广播消息,用户在线情况下会直接收到消息内容,未在线时此条消息会转为 Push 进行推送,同时该条消息做为离线消息进行存储,用户下次登录后会通过离线消息获取。 |
全量用户不落地通知 | 向应用下的所有用户发送远程 Push,无论用户是否正在使用应用,该通知只会展示在通知栏,通知内容不会做为消息存储到本地。 |
# 消息类型
消息类型 | 描述 |
---|---|
文字消息 | 用来发送文字类消息,其中可以包括表情、超链接(会自动识别),客户端收到消息后计入未读消息数、进行存储。 |
语音消息 | 发送高质量的短语音消息,录制的语音文件存储到融云服务端,语音文件格式为 AAC,时长上限为 60 秒,客户端收到消息后计入未读消息数、进行存储。 |
图片消息 | 用来发送图片类消息,客户端收到消息后计入未读消息数、进行存储。图片缩略图格式为 JPG,大小建议不超过 100k。 |
GIF 图片消息 | 用来发送 GIF 动态图片消息,客户端收到消息后计入未读消息数、进行存储。 |
图文消息 | 用来发送图文消息,包含一个标题,一段文字内容和一张图片,客户端收到消息后计入未读消息数、进行存储。 |
文件消息 | 用来发送文件类消息,客户端收到消息后计入未读消息数、进行存储。 |
小视频消息 | 用来发送小视频消息,支持录制发送及选择本地视频文件发送两种方式,录制时长不超过 10 秒,本地选择视频文件方式时长不超过 2 分钟,小视频消息小视频文件格式为 .mp4,客户端收到消息后计入未读消息数、进行存储。 |
命令消息 | 用来发送通用的指令通知消息,消息内可以定义任意 JSON 内容,与通用命令通知消息的区别是不存储、不计数,此类型消息没有 Push 通知。 |
自定义消息 | 融云内置消息类型,无法满足客户业务需求时,可通过自定义消息类型进行实现,接收自定义消息的格式解析及展示处理需要开发者自行实现 |
# 消息结构示例
系统通知场景下融云内置消息类型说明:
# 文本消息
ObjectName | 存储属性 | 计数属性 | 离线属性 | 推送属性 | 推送内容 |
---|---|---|---|---|---|
RC:TxtMsg | 存储 | 计数 | 存储 | 推送 | 消息内容 |
消息结构:
发送文本消息时 content 参数的 JSON 结构如下:
{ "content":"Hello world!", "user": { "id":"4242", "name":"Robin", "portrait":"http://example.com/p1.png", "extra":"extra" }, "extra":"" }
已复制
2
3
4
5
6
7
8
9
10
11
属性说明:
名称 | 类型 | 必传 | 说明 |
---|---|---|---|
content | String | 是 | 文字消息的文字内容,包括表情。 |
user | String | 否 | 消息中携带的用户信息,详细查看 user 参数说明。 |
extra | String | 否 | 扩展信息,可以放置任意的数据内容,也可以去掉此属性。 |
user 属性说明:
名称 | 说明 |
---|---|
id | 发送用户 Id。 |
name | 发送用户需要显示的名称。 |
portrait | 发送用户需要显示的头象。 |
extra | 扩展信息,可以放置任意的数据内容。 |
# 图片消息
ObjectName | 存储属性 | 计数属性 | 离线属性 | 推送属性 | 推送内容 |
---|---|---|---|---|---|
RC:ImgMsg | 存储 | 计数 | 存储 | 推送 | [图片] |
消息结构:
发送图片消息时 content 参数的 JSON 结构如下:
{ "content":"bhZPzJXimRwrtvc=", "imageUri":"http://p1.cdn.com/fds78ruhi.jpg", "user": { "id":"4242", "name":"Robin", "portrait":"http://example.com/p1.png", "extra":"extra" }, "extra":"" }
已复制
2
3
4
5
6
7
8
9
10
11
12
属性说明:
名称 | 类型 | 必传 | 说明 |
---|---|---|---|
content | String | 是 | 图片缩略图,格式为 JPG,大小建议为 5k,最大不超过 80k,注意在 Base64 进行 Encode 后需要将所有 \r\n 和 \r 和 \n 替换成空。缩略图生成逻辑说明 (opens new window) |
imageUri | String | 是 | 图片上传到图片存储服务器后的地址。 |
user | String | 否 | 消息中携带的用户信息,详细查看 user 参数说明。 |
extra | String | 否 | 扩展信息,可以放置任意的数据内容,也可以去掉此属性。 |
user 属性说明:
名称 | 说明 |
---|---|
id | 发送用户 Id。 |
name | 发送用户需要显示的名称。 |
portrait | 发送用户需要显示的头象。 |
extra | 扩展信息,可以放置任意的数据内容。 |
常见问题:
1、缩略图最大尺寸为:240 x 240 像素,以宽度和高度中较长的边不超过 240 像素等比压缩。
2、大图最大尺寸为:960 x 960 像素,以宽度和高度中较长的边不超过 960 像素等比压缩。
3、图片消息包括两个主要部分:缩略图和大图,如设置为原图发送则为缩略图和原图,缩略图直接 Base64 编码后放入 content
中,大图或原图首先上传到文件服务器(融云 SDK 中默认上传到七牛云存储),然后将云存储上的大图或原图地址放入消息体中。
4、发送图片消息时,需要自行上传图片文件到应用的文件服务器,生成地址后进行发送。
# GIF 图片消息
ObjectName | 存储属性 | 计数属性 | 离线属性 | 推送属性 | 推送内容 |
---|---|---|---|---|---|
RC:GIFMsg | 存储 | 计数 | 存储 | 推送 | [图片] |
消息结构:
发送图片消息时 content 参数的 JSON 结构如下:
{ "gifDataSize":34563, "height":246, "localPath":"/var/mobile/.../GIF_53", "remoteUrl":"https://rongcloud-image.cn.ronghub.com/image_jpe64562665566.jpg", "width":263, "user": { "id":"4242", "name":"Robin", "portrait":"http://example.com/p1.png", "extra":"extra" }, "extra":"" }
已复制
2
3
4
5
6
7
8
9
10
11
12
13
14
15
属性说明:
名称 | 类型 | 必传 | 说明 |
---|---|---|---|
gifDataSize | Int | 是 | GIF 图片文件大小,单位为字节 Byte。 |
localPath | String | 是 | 下载 GIF 图片后存储在本地的图片地址。 |
remoteUrl | String | 是 | GIF 图片的服务器地址。 |
width | Int | 是 | GIF 图片宽度。 |
height | Int | 是 | GIF 图片高度。 |
user | String | 是 | 消息中携带的用户信息,IMKit SDK 会话界面中优先显示消息中携带的用户信息,可去掉此属性。 |
extra | String | 否 | 扩展信息,可以放置任意的数据内容,也可以去掉此属性。 |
user 属性说明:
名称 | 说明 |
---|---|
id | 发送用户 Id。 |
name | 发送用户需要显示的名称。 |
portrait | 发送用户需要显示的头象。 |
extra | 扩展信息,可以放置任意的数据内容。 |
# 语音消息
从 SDK 2.9.19 版本开始支持 RC:HQVCMsg
语音消息功能,RC:HQVCMsg
语音消息与旧版本 SDK 不兼容,旧版本 SDK 无法收听新的语音消息。
新语音消息 RC:HQVCMsg
和旧版本语音消息 RC:VcMsg
不同的是将录制的音频数据存储到服务端,而消息体内只保存 URL。摆脱了消息体 128K 的大小限制,所以拥有更高音质。语音时长上限为 60 秒,客户端收到消息后计入未读消息数、进行存储。
ObjectName | 存储属性 | 计数属性 | 离线属性 | 推送属性 | 推送内容 |
---|---|---|---|---|---|
RC:HQVCMsg | 存储 | 计数 | 存储 | 推送 | [语音] |
消息结构:
发送高质量语音消息时 content 参数的 JSON 结构如下:
{ "localPath":"/9j/4AAQSkZ/2wBaSiimB//9k=", "remoteUrl":"http://p1.cdn.com/fds78ruhi.aac", "duration":7, "user": { "id":"4242", "name":"Robin", "portrait":"http://example.com/p1.png", "extra":"extra" }, "extra":"" }
已复制
2
3
4
5
6
7
8
9
10
11
12
13
参数说明:
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
localPath | String | 否 | 采用 AAC 格式进行编码录制的媒体内容本地路径。 |
remoteUrl | String | 是 | 媒体内容上传服务器后的网络地址。 |
duration | Int | 是 | 语音消息的时长,最长为 60 秒(单位:秒)。 |
user | String | 否 | 消息中携带的用户信息,详细查看 user 参数说明。 |
extra | String | 否 | 扩展信息,可以放置任意的数据内容,也可以去掉此属性。 |
user 参数说明:
名称 | 说明 |
---|---|
id | 发送用户 Id。 |
name | 发送用户需要显示的名称。 |
portrait | 发送用户需要显示的头象。 |
extra | 扩展信息,可以放置任意的数据内容。 |
常见问题
1、发送高质量语音消息时,需要自行生成 AAC 格式文件并上传文件到应用的文件服务器,生成地址后进行发送。
# 文件消息
ObjectName | 存储属性 | 计数属性 | 离线属性 | 推送属性 | 推送内容 |
---|---|---|---|---|---|
RC:FileMsg | 存储 | 计数 | 存储 | 推送 | [文件] + 文件名,如:[文件] 123.txt |
消息结构:
发送文件消息时 content 参数的 JSON 结构如下:
{ "name":"file.txt", "size":190184, "type":"txt", "fileUrl":"http://www.demo.com/am.ind", "user": { "id":"4242", "name":"Robin", "portrait":"http://example.com/p1.png", "extra":"extra" }, "extra":"" }
已复制
2
3
4
5
6
7
8
9
10
11
12
13
14
属性说明:
名称 | 类型 | 必传 | 说明 |
---|---|---|---|
name | String | 是 | 文件名称。 |
size | String | 是 | 文件大小,单位:Byte。 |
type | String | 是 | 文件类型。 |
fileUrl | String | 是 | 文件地址。 |
user | String | 否 | 消息中携带的用户信息,详细查看 user 参数说明。 |
extra | String | 否 | 扩展信息,可以放置任意的数据内容,也可以去掉此属性。 |
user 属性说明:
名称 | 说明 |
---|---|
id | 发送用户 Id。 |
name | 发送用户需要显示的名称。 |
portrait | 发送用户需要显示的头象。 |
extra | 扩展信息,可以放置任意的数据内容。 |
常见问题
1、通过 Server API 发送文件消息时,需要自行上传文件到应用的文件服务器,生成文件地址后进行发送。
# 小视频消息
ObjectName | 存储属性 | 计数属性 | 离线属性 | 推送属性 | 推送内容 |
---|---|---|---|---|---|
RC:SightMsg | 存储 | 计数 | 存储 | 推送 | [小视频] |
消息结构:
发送小视频消息时 content 参数的 JSON 结构如下:
{ "sightUrl":"http://rongcloud...com/video...", "content":"/9j/4AAQSkZ/2wB...hDSaSiimB//9k=", "duration":2, "size":734320, "name":"video_xx.mp4", "user": { "id":"4242", "name":"Robin", "portrait":"http://example.com/p1.png", "extra":"extra" }, "extra":"extra" }
已复制
2
3
4
5
6
7
8
9
10
11
12
13
14
15
属性说明:
名称 | 类型 | 必传 | 说明 |
---|---|---|---|
sightUrl | String | 是 | 上传到文件服务器的小视频地址。 |
content | String | 是 | 小视频首帧的缩略图进行 Base64 编码的结果值,格式为 JPG,注意在 Base64 进行 Encode 后需要将所有 \r\n 和 \r 和 \n 替换成空。 |
duration | Int | 是 | 视频时长,单位:秒。 |
size | String | 是 | 视频大小单位 Byte。 |
name | String | 是 | 发送端视频的文件名,小视频文件格式为 MP4 。 |
user | String | 否 | 消息中携带的用户信息,详细查看 user 参数说明。 |
extra | String | 否 | 扩展信息,可以放置任意的数据内容,也可以去掉此属性。 |
user 属性说明:
名称 | 说明 |
---|---|
id | 发送用户 Id。 |
name | 发送用户需要显示的名称。 |
portrait | 发送用户需要显示的头象。 |
extra | 扩展信息,可以放置任意的数据内容。 |
常见问题
1、通过 Server API 发送视频消息时,需要自行上传视频文件到应用的文件服务器,生成文件地址后进行发送。
2、IMKit SDK 中目前支持播放的视频文件格式为 mp4,IMLib SDK 中播放功能需要开发者自行实现。
# 命令消息
ObjectName | 存储属性 | 计数属性 | 离线属性 | 推送属性 | 推送内容 |
---|---|---|---|---|---|
RC:CmdMsg | 不存储 | 不计数 | 存储 | 不推送 | 无 |
消息结构:
运营平台向终端发送指令信息时可使用此命令消息,消息中 content 参数的 JSON 结构如下:
{ "name":"AtPerson", "data":"{\"sourceId\":\"9527\"}" }
已复制
2
3
4
属性说明:
名称 | 类型 | 必传 | 说明 |
---|---|---|---|
name | String | 是 | 命令名称,可以自行定义。 |
data | String | 是 | 命令的内容。 |