跳到主要内容

版本:2.X

单聊介绍

概述

适用于应用内两个用户之间一对一聊天方式,两个用户间可以是好友也可以是陌生人,融云不对用户的关系进行维护管理,会话关系由融云负责建立并保持。

消息发送时序图

!theme materia
skinparam sequence {
ArrowFontSize 13
ParticipantFontSize 11
}
UserA -> RongCloudServer: 用户 A 向用户 B 发送消息
RongCloudServer -> RongCloudServer: 消息中是否含有屏蔽敏感词,如包含则不下发消息。
RongCloudServer -> RongCloudServer: 是否在用户 B 的黑/白名单中
RongCloudServer --> UserA: 在黑名单中或不在白名单中,返回发送失败状态
RongCloudServer -> RongCloudServer: 判断用户 B 是否在线
RongCloudServer -> UserB: 在线状态向用户 B 正常发送消息
UserB -> UserB: 在线状态直接接收消息
RongCloudServer -> RongCloudServer: 用户不在线时,将消息存储为离线消息
RongCloudServer -> UserB: 同时向用户 B 发送 Push,用户登录后接收离线消息

主要功能

功能描述
离线消息支持离线消息存储,存储时间可设置(1 ~ 7 天),默认存储 7 天。
消息提醒离线状态,单聊中有新消息时,支持 Push 通知。
本地存储存储在移动端本地,提供本地消息搜索功能。
历史消息提供服务端消息存储存功能,需开通单群聊消息云存储,默认存储时长为 6 个月。
消息删除支持按会话删除本地和存储在服务器的指定消息或会话中全部历史消息。
消息搜索支持按关键字或用户搜索本地指定会话的消息内容。
消息阅读回执发送单聊消息后如需要查看消息的阅读状态,可以使用此功能来发送阅读回执请求。
消息撤回消息发送成功后,在有效时间内可撤回该条消息,默认可撤回时间为 2 分钟,时间可配置。
单聊会话免打扰可设置指定的单聊会话,收到新的消息后是否进行提醒,默认进行新消息提醒。
单聊黑名单不想接收到某一用户的消息时,可将此用户加入到黑名单中,应用中的每个用户都可以设置自己的黑名单列表
单聊白名单对用户之间相互发送消息有限制要求的客户,可使用用户白名单功能,将用户加入白名单后,才能收到该用户发送的单聊消息

注:用户白名单服务与用户黑名单服务不能同时使用,融云默认开启的是用户黑名单服务,如需要开通白名单服务请提交工单申请开通。服务开通 30 分钟后生效,同时黑名单服务不再生效。

消息类型

消息类型描述
文字消息用来发送文字类消息,其中可以包括表情、超链接(会自动识别),客户端收到消息后计入未读消息数、进行存储。
语音消息发送高质量的短语音消息,录制的语音文件存储到融云服务端,语音文件格式为 AAC,时长上限为 60 秒,客户端收到消息后计入未读消息数、进行存储。
图片消息用来发送图片类消息,客户端收到消息后计入未读消息数、进行存储。图片缩略图格式为 JPG,大小建议不超过 100k。
GIF 图片消息用来发送 GIF 动态图片消息,客户端收到消息后计入未读消息数、进行存储。
图文消息用来发送图文消息,包含一个标题,一段文字内容和一张图片,客户端收到消息后计入未读消息数、进行存储。
文件消息用来发送文件类消息,客户端收到消息后计入未读消息数、进行存储。
位置消息用来发送地理位置消息,客户端收到消息后计入未读消息数、进行存储。
小视频消息用来发送小视频消息,支持录制发送及选择本地视频文件发送两种方式,录制时长不超过 10 秒,本地选择视频文件方式时长不超过 2 分钟,小视频消息小视频文件格式为 .mp4,客户端收到消息后计入未读消息数、进行存储。
合并转发消息IMKit SDK 中支持将多条消息合并为一条消息进行发送,合并后的消息以 HTML 文件的方式存储到融云服务端,客户端收到消息后计入未读消息数、进行存储。红包、阅后即焚及自定义消息的合并转发功能
命令消息用来发送通用的指令通知消息,消息内可以定义任意 JSON 内容,与通用命令通知消息的区别是不存储、不计数,此类型消息没有 Push 通知。
自定义消息融云内置消息类型,无法满足客户业务需求时,可通过自定义消息类型进行实现,接收自定义消息的格式解析及展示处理需要开发者自行实现

消息结构说明

以下为融云内置消息类型说明:

文本消息

ObjectName存储属性计数属性离线属性推送属性推送内容
RC:TxtMsg存储计数存储推送消息内容

消息结构:

发送文本消息时 content 参数的 JSON 结构如下:

{
"content":"Hello world!",
"user":
{
"id":"4242",
"name":"Robin",
"portrait":"http://example.com/p1.png",
"extra":"extra"
},
"extra":""
}

属性说明:

名称类型必传说明
contentString文字消息的文字内容,包括表情。
userString消息中携带的用户信息,详细查看 user 参数说明。
extraString扩展信息,可以放置任意的数据内容,也可以去掉此属性。

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":""
}

属性说明:

名称类型必传说明
contentString图片缩略图,格式为 JPG,Base64 字符串长度建议为 5k,最大不超过 10k,注意在 Base64 进行 Encode 后需要将所有 `
` 替换成空。
imageUriString图片上传到图片存储服务器后的地址。
userString消息中携带的用户信息,详细查看 user 参数说明。
extraString扩展信息,可以放置任意的数据内容,也可以去掉此属性。

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":""
}

属性说明:

名称类型必传说明
gifDataSizeIntGIF 图片文件大小,单位为 KB。
localPathString下载 GIF 图片后存储在本地的图片地址。
remoteUrlStringGIF 图片的服务器地址。
widthIntGIF 图片宽度。
heightIntGIF 图片高度。
userString消息中携带的用户信息,IMKit SDK 会话界面中优先显示消息中携带的用户信息,可去掉此属性。
extraString扩展信息,可以放置任意的数据内容,也可以去掉此属性。

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":""
}

参数说明:

参数类型必传说明
localPathString采用 AAC 格式进行编码录制的媒体内容本地路径。
remoteUrlString媒体内容上传服务器后的网络地址。
durationInt语音消息的时长,最长为 60 秒(单位:秒)。
userString消息中携带的用户信息,详细查看 user 参数说明。
extraString扩展信息,可以放置任意的数据内容,也可以去掉此属性。

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":""
}

属性说明:

名称类型必传说明
nameString文件名称。
sizeString文件大小,单位:bytes。
typeString文件类型。
fileUrlString文件地址。
userString消息中携带的用户信息,详细查看 user 参数说明。
extraString扩展信息,可以放置任意的数据内容,也可以去掉此属性。

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"
}

属性说明:

名称类型必传说明
sightUrlString上传到文件服务器的小视频地址。
contentString小视频首帧的缩略图进行 Base64 编码的结果值,格式为 JPG,注意在 Base64 进行 Encode 后需要将所有
替换成空。
durationInt视频时长,单位:秒。
sizeString视频大小单位 bytes。
nameString发送端视频的文件名,小视频文件格式为 MP4(H.264+AAC)。
userString消息中携带的用户信息,详细查看 user 参数说明。
extraString扩展信息,可以放置任意的数据内容,也可以去掉此属性。

user 属性说明:

名称说明
id发送用户 Id。
name发送用户需要显示的名称。
portrait发送用户需要显示的头象。
extra扩展信息,可以放置任意的数据内容。

常见问题

1、通过 Server API 发送视频消息时,需要自行上传视频文件到应用的文件服务器,生成文件地址后进行发送。

2、IMKit SDK 中目前支持播放的视频文件格式为 mp4,IMLib SDK 中播放功能需要开发者自行实现。

位置消息

ObjectName存储属性计数属性离线属性推送属性推送内容
RC:LBSMsg存储计数存储推送[位置]

消息结构:

发送位置消息时 content 参数的 JSON 结构如下:

{
"content":"bhZPzJXimRwrtvc=",
"latitude":39.9139,
"longitude":116.3917,
"poi":"北京云中融信网络科技有限公司",
"user":
{
"id":"4242",
"name":"Robin",
"portrait":"http://example.com/p1.png",
"extra":"extra"
},
"extra":""
}

属性说明:

名称类型必传说明
contentString表示位置图片缩略图,格式为 JPG,以 Base64 进行 Encode 后需要将所有 `
` 替换成空。
latitudeString位置的纬度值。
longitudeString位置的经度值。
poiString表示位置的 poi 信息。
userString消息中携带的用户信息,详细查看 user 参数说明。
extraString扩展信息,可以放置任意的数据内容,也可以去掉此属性。

user 属性说明:

名称说明
id发送用户 Id。
name发送用户需要显示的名称。
portrait发送用户需要显示的头象。
extra扩展信息,可以放置任意的数据内容。

提示小灰条消息

ObjectName存储属性计数属性离线属性推送属性推送内容
RC:InfoNtf存储不计数存储不推送

消息结构:

发送小灰条消息时 content 参数的 JSON 结构如下:

{
"message":"请在聊天中注意人身财产安全",
"extra":""
}

属性说明:

名称类型必传说明
messageString提示条消息内容。
extraString扩展信息,可以放置任意的数据内容,也可以去掉此属性。

资料变更通知消息

ObjectName存储属性计数属性离线属性推送属性推送内容
RC:ProfileNtf存储不计数存储不推送

消息结构:

发送用户资料变更消息时 content 参数的 JSON 结构如下:

{
"operation":"Update",
"data":"{\"nickname\":\"韩梅梅\", \"hometown\":\"beijing\"}",
"extra":""
}

属性说明:

名称类型必传说明
operationString资料通知操作,可以自行定义。
dataString操作的数据。
extraString扩展信息,可以放置任意的数据内容,也可以去掉此属性。

联系人(好友)通知消息

ObjectName存储属性计数属性离线属性推送属性推送内容
RC:ContactNtf存储不计数存储不推送

消息结构:

发送加好友消息时 content 参数的 JSON 结构如下:

{
"operation":"Request",
"sourceUserId":"123",
"targetUserId":"456",
"message":"我是小艾,能加一下好友吗?",
"extra":""
}

属性说明:

名称类型必传说明
operationString联系人操作的指令,官方针对 operation 属性定义了 "Request", "AcceptResponse", "RejectResponse" 几个常量,也可以由开发者自行扩展。
sourceUserIdString发出通知的用户 Id。
targetUserIdString单聊会话为接收通知的用户 Id,群聊、聊天室会话为会话 Id。
messageString表示请求或者响应消息,如添加理由或拒绝理由。
extraString扩展信息,可以放置任意的数据内容,也可以去掉此属性。