# 概述

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

消息发送时序图： 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 String 是 文字消息的文字内容，包括表情。

user String 否 消息中携带的用户信息，详细查看 user 参数说明。

extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。

user 属性说明： 名称 说明 id 发送用户 Id。

name 发送用户需要显示的名称。

portrait 发送用户需要显示的头象。

extra 扩展信息，可以放置任意的数据内容。

# 图片消息 ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容 RC:ImgMsg 存储 计数 存储 推送 [图片]

消息结构：

发送图片消息时 content 参数的 JSON 结构如下：

属性说明： 名称 类型 必传 说明 content String 是 图片缩略图，格式为 JPG，大小建议为 5k，最大不超过 80k，注意在 Base64 进行 Encode 后需要将所有 \r\n 和 \r 和 \n 替换成空。缩略图生成逻辑说明

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 Int 是 GIF 图片文件大小，单位为 KB。

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 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 String 是 文件名称。

size String 是 文件大小，单位：bytes。

type String 是 文件类型。

fileUrl String 是 文件地址。

user String 否 消息中携带的用户信息，详细查看 user 参数说明。

extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。

user 属性说明： 名称 说明 id 发送用户 Id。

name 发送用户需要显示的名称。

portrait 发送用户需要显示的头象。

extra 扩展信息，可以放置任意的数据内容。

常见问题

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

# 小视频消息 ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容 RC:SightMsg 存储 计数 存储 推送 [小视频]

消息结构：

发送小视频消息时 content 参数的 JSON 结构如下：

属性说明： 名称 类型 必传 说明 sightUrl String 是 上传到文件服务器的小视频地址。

content String 是 小视频首帧的缩略图进行 Base64 编码的结果值，格式为 JPG，注意在 Base64 进行 Encode 后需要将所有 \r\n 和 \r 和 \n 替换成空。

duration Int 是 视频时长，单位：秒。

size String 是 视频大小单位 bytes。

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:LBSMsg 存储 计数 存储 推送 [位置]

消息结构：

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

属性说明： 名称 类型 必传 说明 content String 是 表示位置图片缩略图，格式为 JPG，以 Base64 进行 Encode 后需要将所有 \r\n 和 \r 和 \n 替换成空。

latitude String 是 位置的纬度值。

longitude String 是 位置的经度值。

poi String 是 表示位置的 poi 信息。

user String 否 消息中携带的用户信息，详细查看 user 参数说明。

extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。

user 属性说明： 名称 说明 id 发送用户 Id。

name 发送用户需要显示的名称。

portrait 发送用户需要显示的头象。

extra 扩展信息，可以放置任意的数据内容。

# 提示小灰条消息 ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容 RC:InfoNtf 存储 不计数 存储 不推送 无

消息结构：

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

属性说明： 名称 类型 必传 说明 message String 是 提示条消息内容。

extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。

# 资料变更通知消息 ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容 RC:ProfileNtf 存储 不计数 存储 不推送 无

消息结构：

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

属性说明： 名称 类型 必传 说明 operation String 是 资料通知操作，可以自行定义。

data String 是 操作的数据。

extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。

# 联系人(好友)通知消息 ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容 RC:ContactNtf 存储 不计数 存储 不推送 无

消息结构：

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

属性说明： 名称 类型 必传 说明 operation String 是 联系人操作的指令，官方针对 operation 属性定义了 "Request", "AcceptResponse", "RejectResponse" 几个常量，也可以由开发者自行扩展。

sourceUserId String 是 发出通知的用户 Id。

targetUserId String 是 单聊会话为接收通知的用户 Id，群聊、聊天室会话为会话 Id。

message String 是 表示请求或者响应消息，如添加理由或拒绝理由。

extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。