# 功能描述 消息属性 消息描述 消息属性 消息描述 消息类名 各端消息名 ObjectName 传输层名称，与消息类名一一对应

存储属性 存储 / 不存储 计数属性 计数 / 不计数

离线属性 缓存 / 不缓存 消息尺寸 128 KB

推送属性 是/否 推送内容 详见各消息类送方式

# 存储属性 存储属性 存储分类 支持平台 详细描述 存储 客户端 Android、iOS 发送、接收该消息后，本地数据库存储

Web 端 和 小程序端因本地存储不可靠，不支持客户端消息存储，但可通过历史消息云存储服务获取历史记录

存储 云端 Android、iOS、Web 默认不在云端进行存储，需开通历史消息云存储服务，开通后，可在融云服务端存储 6 个月的历史消息，供客户端按需拉取

不存储 客户端 Android、iOS 发送、接收该消息后，本地数据库不存储

不存储 云端 Android、iOS、Web 无论是否开通历史消息云存储服务，该消息均不存储

# 计数属性

接收收到消息时，会话是否累计未读数。 计数属性 支持平台 详细描述 计数 iOS、Android、Web 会话未读消息数 + 1，该属性只影响会话列表未读数计数，App 应用角标可根据每个会话列表未读数累加获得

不计数 iOS、Android、Web 会话未读消息数不变

# 离线属性

接收人当前不在线时，是否进行离线缓存。 离线属性 详细描述 存储 消息进行离线缓存，默认 7 天。接收人在 7 天内上线，均可接收到该消息。超过 7 天后，消息被离线缓存淘汰。如有需要，可通过云端存储拉取到该消息

不存储 消息不进行离线缓存，所以只有接收人在线时，才可收到该消息。该消息不进行历史消息云存储、不进入云端存储( Log 日志 )、不进行消息同步( 消息路由 )

# 推送属性

接收人是否接收推送，当离线属性为 存储 时，该属性生效。离线属性为 不存储 时属性无效。

由于 Web、小程序、PC 端没有推送平台，无法收到推送提醒。 推送属性 平台 推送方式 详细描述 ​推送 iOS、Android APNS、华为、小米、魅族、OPPO、vivo、FCM、融云 当有离线缓存消息时，进行远程推送提醒，内容为该推送提醒显示的内容

​不推送 iOS、Android -- 当有离线缓存消息时，不进行远程推送提醒

# 实现方法

# 普通消息发送

输入参数： 参数 类型 必传 说明 fromUserId String 是 发送人用户 Id。

toUserId String 是 接收用户 Id，可以实现向多人发送消息，每次上限为 1000 人。

objectName String 是 消息类型，可自定义消息类型，长度不超过 32 个字符，在自定义消息时需要注意，不要以 "RC:" 开头，以避免与融云系统内置消息的 ObjectName 重名。

content String 是 发送消息内容，单条消息最大 128KB，内置消息以 JSON 方式进行数据序列化，消息中可选择是否携带用户信息，详见消息结构示例；

如果 objectName 为自定义消息类型，该参数可自定义格式，不限于 JSON。

pushContent String 否 定义显示的 Push 内容，如果 objectName 为融云内置消息类型时，则发送后用户一定会收到 Push 信息。

如果为自定义消息，则 pushContent 为自定义消息显示的 Push 内容，如果不传则用户不会收到 Push 通知。

pushData String 否 针对 iOS 平台为 Push 通知时附加到 payload 中，客户端获取远程推送内容时为 appData，同时融云默认携带了消息基本信息，客户端可通过 'rc' 属性获取，查看详细。

针对 Android 平台收到推送消息时对应字段名为 pushData。

isIncludeSender Int 否 终端用户在线状态下，发送用户自己是否接收消息，0 表示为不接收，1 表示为接收，默认为 0 不接收，只有在 toUserId 为一个用户 Id 的时候有效。

如终端用户未登录，需要登录后也收到此条消息时，需要在开发者后台 IM 商用版中开通“多设备消息同步”功能。

count Int 否 针对 iOS 平台，Push 时用来控制未读消息显示数，只有在 toUserId 为一个用户 Id 的时候有效，客户端获取远程推送内容时为 badge 查看详细，为 -1 时不改变角标数，传入相应数字表示把角标数改为指定的数字，最大不超过 9999。

verifyBlacklist Int 否 是否过滤接收用户黑名单列表，0 表示为不过滤、 1 表示为过滤，默认为 0 不过滤。

isPersisted Int 否 针对融云服务端历史消息中是否存储此条消息，客户端则根据消息注册的 ISPERSISTED 标识判断是否存储，如果旧版客户端上未注册该消息时，收到该消息后默认为存储，但无法解析显示。0 表示为不存储、 1 表示为存储，默认为 1 存储消息，此属性不影响离线消息功能，用户未在线时都会转为离线消息存储。

contentAvailable Int 否 针对 iOS 平台，对应用处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行，查看详细。1 表示为开启，0 表示为关闭，默认为 0

返回结果： 返回值 返回类型 说明 code Int 返回码，200 为正常。

示例代码：

请求地址： https://数据中心域名/message/private/publish.json

请求方法： POST

发送频率： 通过 Server API 单个应用每分钟最多发送 6000 条信息，每次接收消息的用户上限为 1000 人，如：一次发送给 1000 人时，示为 1000 条消息。可在开发者后台调整发送频率。

签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则

Request：

Response：

# 模板消息发送

向应用中不同用户，发送不同的消息内容，如向应用中不同用户发送活动获得的积分时，可使用此功能。

输入参数： 参数 类型 必传 说明 fromUserId String 是 发送人用户 Id。

toUserId String[] 是 接收用户 Id，提供多个本参数可以实现向多人发送消息，上限为 1000 人。(

objectName String 是 消息类型，可自定义消息类型，长度不超过 32 个字符，在自定义消息时需要注意，不要以 "RC:" 开头，以避免与融云系统内置消息的 ObjectName 重名。

values String[] 是 消息内容中，标识位对应内容。

content String 是 发送消息内容，单条消息最大 128k，内置消息以 JSON 方式进行数据序列化，消息中可选择是否携带用户信息，详见消息结构示例；如果 objectName 为自定义消息类型，该参数可自定义格式，不限于 JSON。

pushContent String[] 是 定义显示的 Push 内容，如果 objectName 为融云内置消息类型时，则发送后用户一定会收到 Push 信息。

如果为自定义消息，定义显示的 Push 内容，内容中定义标识通过 values 中设置的标识位内容进行替换。如消息类型为自定义不需要 Push 通知，则对应数组传空值即可。

pushData String[] 否 针对 iOS 平台为 Push 通知时附加到 payload 中，客户端获取远程推送内容时为 appData，同时融云默认携带了消息基本信息，客户端可通过 'rc' 属性获取，查看详细。

针对 Android 平台收到推送消息时对应字段名为 pushData。

verifyBlacklist Int 否 是否过滤发送人黑名单列表，0 为不过滤、 1 为过滤，默认为 0 不过滤。

contentAvailable Int 否 针对 iOS 平台，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行，查看详细。1 表示为开启，0 表示为关闭，默认为 0

返回结果： 返回值 返回类型 说明 code Int 返回码，200 为正常。

示例代码：

请求地址： https://数据中心域名/message/private/publish_template.json

请求方法： POST

发送频率： 通过 Server API 单个应用每分钟最多发送 6000 条信息，每次接收消息的用户上限为 1000 人。可在开发者后台调整发送频率。

签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则

Request：

上面示例中用户 Id 为 21 的用户，收到信息为 123，上面示例中用户 Id 为 22 的用户，收到信息为 456

注意，如 content 中定义了标识 {d} ，则在 values 中需要对 {d} 进行设置，否则 {d} 会以文本方式随消息一起发送给用户。toUserId、values、pushContent、pushData 的数量必须相等。

Response：

# 状态消息发送

向目标用户发送消息时，只有用户在线时会收到此条消息，如当前未在线则不会再收到此条消息，状态消息不计数、不存储。

输入参数： 参数 类型 必传 说明 fromUserId String 是 发送人用户 Id。

toUserId String 是 接收用户 Id，可以实现向多人发送消息，每次上限为 1000 人。

objectName String 是 消息类型，可自定义消息类型，长度不超过 32 个字符，在自定义消息时需要注意，不要以 "RC:" 开头，以避免与融云系统内置消息的 ObjectName 重名。

content String 是 发送消息内容，单条消息最大 128k，详见消息结构示例；如果 objectName 为自定义消息类型，该参数可自定义格式。

verifyBlacklist Int 否 是否过滤发送人黑名单列表，0 表示为不过滤、 1 表示为过滤，默认为 0 不过滤。

isIncludeSender Int 否 发送用户自己是否接收消息，0 表示为不接收，1 表示为接收，默认为 0 不接收。

返回结果： 返回值 返回类型 说明 code Int 返回码，200 为正常。

示例代码：

请求地址： https://数据中心域名/statusmessage/private/publish.json

请求方法： POST

发送频率： 通过 Server API 单个应用每分钟最多发送 6000 条信息，每次接收消息的用户上限为 1000 人。可在开发者后台调整发送频率。

签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则

Request：

Response：

# 自定义消息发送

通过 Server API 发送消息接口，都支持发送自定义消息，需要将 objectName 设置为自定义消息类型，同时 content 设置为自己需要的消息结构即可。

1、当 objectName 为自定义消息类型时，需要终端 SDK 对此消息类型进行注册并自行进行解析呈现。

2、pushContent 为自定义消息显示的 Push 内容，如果不传则用户不会收到 Push 通知。

# 消息结构说明

通过 Server API 发送的消息，消息体为 JSON 结构，以下为融云内置消息类型说明：

# 文本消息 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:ReferenceMsg 存储 计数 存储 推送 消息内容

消息结构：

发送引用消息时 content 参数，以引用对象为文本消息为例，结构如下：

属性说明： 名称 类型 必传 说明 content String 是 引用消息时发送的文字内容，包括表情。

referMsgUserId String 是 被引用消息的发送用户 Id。

referMsg String 是 被引用消息的消息结构 JSON 格式。

objName String 是 被引用消息的消息类型，目前支持的消息类型：文本 RC:TxtMsg、图片 RC:ImgMsg、文件 RC:FileMsg

mentionedInfo String 否 群组中 @ 消息信息，详细查看属性说明，单聊场景下无需设置此属性。

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

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

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

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

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

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

mentionedInfo 属性说明： 名称 类型 必传 说明 type int 是 @ 功能类型，1 表示 @ 所有人、2 表示 @ 指定用户。

userIdList String[] 否 指定用户列表，type 为 2 时有效，为 1 时 userIdList 可以为空。

mentionedContent String 否 @ 消息的自定义 Push 内容。

# 位置消息 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 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。

# 命令消息 ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容 RC:CmdMsg 不存储 不计数 存储 不推送 无

消息结构：

运营平台向终端发送指令信息时可使用此命令消息，消息中 content 参数的 JSON 结构如下：

属性说明： 名称 类型 必传 说明 name String 是 命令名称，可以自行定义。

data String 是 命令的内容。

# 已读通知消息

用来发送消息已经被接收到的状态消息，客户端收到消息后不计入未读消息数、不存储，此类型消息没有 Push 通知。 ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容 RC:ReadNtf 不存储 不计数 存储 无 无

消息结构：

发送已读通知消息时 content 结构如下：

属性说明： 名称 类型 必传 说明 lastMessageSendTime Int 是 已读的最后一条消息的发送时间。

messageUId String 是 已读的最后一条消息的 UId，消息唯一标识。

type Int 是 会话类型，目前该消息只支持单聊会话，类型为 1。

# 注意事项

1、发送消息所使用的用户 Id 必须获取过用户 Token ，否则终端未在线发送 Push 时无法正确显示用户信息。

2、发送自定义消息时，需要开发者在 SDK 中注册过该消息，否则 SDK 收到该消息后将无法解析。