全部文档

更新时间: 2021-03-08

# 单个用户发送

# 普通消息

系统通知消息，只能通过 Server API 进行发送，终端用户收到系统消息后，不支持消息回复功能。

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

请求方法： POST

发送频率： 通过 Server API 单个应用每秒钟最多发送 100 条消息，每次最多同时向 100 人发送，如：一次发送 100 人时，示为 100 条消息。可在开发者后台 (opens new window)调整发送频率。

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

输入参数：

参数 类型 必传 说明
fromUserId String 是 发送人用户 Id。
toUserId String 是 接收用户Id，提供多个本参数可以实现向多用户发送系统消息，上限为 100 人。
objectName String 是 消息类型，可自定义消息类型，长度不超过 32 个字符，在自定义消息时需要注意，不要以 "RC:" 开头，以避免与融云系统内置消息的 ObjectName 重名。
content String 是 发送消息内容，单条消息最大 128k，内置消息以 JSON 方式进行数据序列化，消息中可选择是否携带用户信息，详见消息结构示例；如果 objectName 为自定义消息类型，该参数可自定义格式，不限于 JSON。
pushContent String 是 定义显示的 Push 内容，如果 objectName 为融云内置消息类型时，则发送后用户一定会收到 Push 信息。 如果为自定义消息，则 pushContent 为自定义消息显示的 Push 内容，如果不传则用户不会收到 Push 通知。
pushData String 否 针对 iOS 平台为 Push 通知时附加到 payload 中，客户端获取远程推送内容时为 appData，同时融云默认携带了消息基本信息，客户端可通过 'rc' 属性获取，查看详细，Android 客户端收到推送消息时对应字段名为 pushData。
isPersisted Int 否 针对融云服务端历史消息中是否存储此条消息，客户端则根据消息注册的 ISPERSISTED 标识判断是否存储；针对自定义消息，如果旧版客户端上未注册该消息时，根据此属性确定是否存储在本地，但无法解析显示。0 表示为不存储、 1 表示为存储，默认为 1 存储消息，此属性不影响离线消息功能，用户未在线时都会转为离线消息存储。
contentAvailable Int 否 针对 iOS 平台，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行，查看详细 (opens new window)。1 表示为开启，0 表示为关闭，默认为 0
disablePush Boolean 否 是否为静默消息，默认为 false，设为 true 时终端用户离线情况下不会收到通知提醒。
pushExt String 否 推送通知属性设置，详细查看 pushExt 结构说明，pushExt 为 JSON 结构请求时需要做转义处理。

pushExt 结构说明：

参数 类型 必传 说明
title String 否 通知栏显示标题，最长不超过 50 个字符，默认情况下通知标题单聊会话显示用户名称，群聊会话显示群名称。
templateId String 否 推送模板 ID，设置后根据目标用户通过 SDK 设置的语言环境，匹配模板中设置的语言内容进行推送，未匹配成功时使用默认内容进行推送，模板内容在“开发者后台-自定义推送文案”中进行设置。
forceShowPushContent Int 否 是否强制显示通知详细，0 为不强制、1 为强制，默认为 0，当用户设置通知不显示详细时，可通过此属性强制显示通知详细。
pushConfigs String 否 按厂商设置不同推送属性，目前支持 "IM" 小米、"HW" 华为、"OPPO"、"VIVO"、"APNs" 推送通道
channelId String 否 渠道 ID，该条消息针对各厂商使用的推送渠道，目前支持的厂商包括："IM" 小米、"HW" 华为、"OPPO"
classification String 否 vivo 推送通道类型，0 为运营消息、1 为系统消息，默认为 0。
thread-id String 否 iOS 平台通知栏分组 ID，相同的 thread-id 推送分一组，单组超过 5 条推送会折叠展示
apns-collapse-id String 否 iOS 平台，从 iOS10 开始支持，设置后设备收到有相同 ID 的消息，会合并成一条

pushExt 结构示例：

{
   "title":"you have a new message.",
   "templateId":"123456",
   "forceShowPushContent":0,
   "pushConfigs": [
       {
           "HW": {"channelId": "hw-123"}
       },
       {
           "MI": {"channelId": "mi-123"}
       },
       {
           "OPPO": {"channelId": "oppo-123"}
       },
       {
           "VIVO" : {"classification": "0"}
       },
       {
           "APNs": {
               "thread-id": "123",
               "apns-collapse-id":"123456"
           }
       }
   ]
}

已复制
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

返回结果：

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

示例代码

Request：

POST /message/system/publish.json HTTP/1.1
Host: api-cn.ronghub.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: Application/x-www-form-urlencoded

content=%7B%22content%22%3A%22hello%22%2C%22extra%22%3A%22helloExtra%22%7D&fromUserId=2191&toUserId=2191&toUserId=2192&objectName=RC:TxtMsg&pushContent=thisisapush&pushData%22%3A%22hello%22%7D

已复制
1
2
3
4
5
6
7
8
9

Response：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200}

已复制
1
2
3
4
# 模板消息

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

请求方法： POST

发送频率： 通过 Server API 单个应用每秒钟最多发送 100 条消息，每次最多同时向 100 人发送，如：一次发送 100 人时，示为 100 条消息。可在开发者后台 (opens new window)调整发送频率。

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

输入参数

参数 类型 必传 说明
fromUserId String 是 发送人用户 Id。
toUserId String 是 接收用户 Id，提供多个本参数可以实现向多人发送消息，上限为 100 人。
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。
contentAvailable Int 否 针对 iOS 平台，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行，查看详细 (opens new window)。1 表示为开启，0 表示为关闭，默认为 0
disablePush Boolean 否 是否为静默消息，默认为 false，设为 true 时终端用户离线情况下不会收到通知提醒。

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

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

返回结果:

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

示例代码:

Request：

POST /message/system/publish_template.json HTTP/1.1
Host: api-cn.ronghub.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/json

{
    "fromUserId":"fromuser",
    "objectName":"RC:TxtMsg",
    "content":"{\"content\":\"{c}{d}{e}\",\"extra\":\"bb\"}",
    "toUserId":["21","22"],
    "values":[{"{c}":"1","{d}":"2","{e}":"3"},{"{c}":"4","{d}":"5","{e}":"6"}],
    "pushContent":["push{c}","push{c}"],
    "pushData":["pushd","pushd"]
}

已复制
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Response：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200}

已复制
1
2
3
4

# 消息结构示例

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

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

消息结构：

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

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

已复制
1
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":""
}

已复制
1
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":""
}

已复制
1
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":""
}

已复制
1
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":""
}

已复制
1
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"
}

已复制
1
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: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":""
}

已复制
1
2
3
4
5
6
7
8
9
10
11
12
13
14

属性说明：

名称 类型 必传 说明
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":"请在聊天中注意人身财产安全",
  "extra":""
}

已复制
1
2
3
4

属性说明：

名称 类型 必传 说明
message String 是 提示条消息内容。
extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。
# 资料变更通知消息
ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容
RC:ProfileNtf 存储 不计数 存储 不推送 无

消息结构：

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

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

已复制
1
2
3
4
5

属性说明：

名称 类型 必传 说明
operation String 是 资料通知操作，可以自行定义。
data String 是 操作的数据。
extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。
# 联系人(好友)通知消息
ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容
RC:ContactNtf 存储 不计数 存储 不推送 无

消息结构：

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

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

已复制
1
2
3
4
5
6
7

属性说明：

名称 类型 必传 说明
operation String 是 联系人操作的指令，官方针对 operation 属性定义了 "Request", "AcceptResponse", "RejectResponse" 几个常量，也可以由开发者自行扩展。
sourceUserId String 是 发出通知的用户 Id。
targetUserId String 是 单聊会话为接收通知的用户 Id，群聊、聊天室会话为会话 Id。
message String 是 表示请求或者响应消息，如添加理由或拒绝理由。
extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。
# 命令消息
ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容
RC:CmdMsg 不存储 不计数 存储 不推送 无

消息结构：

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

{
  "name":"AtPerson",
  "data":"{\"sourceId\":\"9527\"}"
}

已复制
1
2
3
4

属性说明：

名称 类型 必传 说明
name String 是 命令名称，可以自行定义。
data String 是 命令的内容。

# 注意事项

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

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

文档是否解决您的问题 ?

如果遇到产品相关问题，您可 提交工单 寻求帮助