融云开发者文档

更新时间: 2021-03-08

# 全量用户发送

# 落地通知

落地通知是指系统向 App 中所有用户发送消息的行为。当用户正在打开 App 时，消息会展示在聊天界面和会话列表界面，同时该消息会存储在客户端的本地数据库中，会话类型为 SYSTEM。

该功能开发环境下可免费使用。生产环境下，需要在开发者后台高级功能设置 (opens new window)中开通 IM 商用版后，在“全量用户通知”中，开启后才能使用。

融云服务端的消息处理默认为每秒钟 2000 条，即每秒钟可以向 2000 个目标用户发送消息。

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

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

请求方法： POST

调用频率： 通过 Server API 单个应用每小时只能发送 2 次，每天最多发送 3 次。可在开发者后台 (opens new window)调整发送频率。

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

输入参数：

参数	类型	必传	说明
fromUserId	String	是	发送人用户 Id。
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。
contentAvailable	否	Int	针对 iOS 平台，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。允许应用在收到通知后在后台运行一段代码，且能够马上执行，查看详细 (opens new window)。1 表示为开启，0 表示为关闭，默认为 0
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/broadcast.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&objectName=RC:TxtMsg&pushContent=thisisapush&pushData=%7B%22pushData%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

# 不落地通知

不落地通知无论用户是否正在使用 App，都会向该用户发送通知，通知只会展示在通知栏，通知中不携带消息内容，登录 App 后不会在聊天页面看到该内容，不会存储到本地数据库。

融云将 30 天内连接过 IM 服务的设备作为推送的目标。30 天内未打开过应用的设备，被视为应用已被卸载。

该功能开发环境下可免费使用。生产环境下，需要在开发者后台高级功能设置 (opens new window)中开通 IM 商用版后，在“广播消息和推送”中，开启后才能使用。

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

请求方法： POST

调用频率： 每小时只能发送 2 次，每天最多发送 3 次。如需要调整发送频率，可联系销售咨询，电话 13161856839。

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

输入参数：

参数	类型	必传	说明
platform	String[]	是	目标操作系统，iOS、Android 最少传递一个。如果需要给两个系统推送消息时，则需要全部填写。
audience	String	是	推送条件，包括：tag 、userid 、packageName 、 is_to_all。
tag	String[]	否	用户标签，每次发送时最多发送 20 个标签，标签之间为 AND 的关系，is_to_all 为 true 时参数无效。
tag_or	String[]	否	用户标签，每次发送时最多发送 20 个标签，标签之间为 OR 的关系，is_to_all 为 true 时参数无效，tag_or 同 tag 参数可以同时存在。
userid	String[]	否	用户 Id，每次发送时最多发送 1000 个用户，如果 tag 和 userid 两个条件同时存在时，则以 userid 为准，如果 userid 有值时，则 platform 参数无效，is_to_all 为 true 时参数无效。
packageName	String	否	应用包名，is_to_all 为 true 时，此参数无效。与 tag、tag_or 同时存在时为 And 的关系，向同时满足条件的用户推送。与 userid 条件同时存在时，以 userid 为准进行推送。
is_to_all	String	是	是否全部推送，false 表示按 tag 、tag_or 或 userid 条件推送，true 表示向所有用户推送，tag、tag_or 和 userid 条件无效。
notification	String	是	按操作系统类型推送消息内容，如 platform 中设置了给 iOS 和 Android 系统推送消息，而在 notification 中只设置了 iOS 的推送内容，则 Android 的推送内容为最初 alert 设置的内容。
alert	String	是	notification 下 alert，默认推送消息内容，如填写了 iOS 或 Android 下的 alert 时，则推送内容以对应平台系统的 alert 为准。
ios	String	否	设置 iOS 平台下的推送及附加信息。
android	String	否	设置 Android 平台下的推送及附加信息。
title	String	否	通知栏显示的推送标题，仅针对 iOS 平台，支持 iOS 8.2 及以上版本，参数在 `ios` 节点下设置，详细可参考“设置 iOS 推送标题请求示例”。
contentAvailable	Int	否	针对 iOS 平台，静默推送是 iOS7 之后推出的一种推送方式。允许应用在收到通知后在后台运行一段代码，且能够马上执行，查看详细 (opens new window)。1 表示为开启，0 表示为关闭，默认为 0
alert	String	否	iOS 或 Android 不同平台下的推送消息内容，传入后默认的推送消息内容失效，不能为空。
extras	JSONObject	否	iOS 或 Android 不同平台下的附加信息，如果开发者自己需要，可以自己在 App 端进行解析。
badge	int	否	应用角标，仅针对 iOS 平台；不填时，表示不改变角标数；为 0 或负数时，表示 App 角标上的数字清零；否则传相应数字表示把角标数改为指定的数字，最大不超过 9999，参数在 `ios` 节点下设置，详细可参考“设置 iOS 角标数 HTTP 请求示例”。
category	String	否	iOS 富文本推送的类型开发者自己定义，自己在 App 端进行解析判断，与 richMediaUri 一起使用，当设置 category 后，推送时默认携带 mutable-content 进行推送，属性值为 1。
richMediaUri	String	否	iOS 富文本推送内容的 URL，与 category 一起使用。

返回结果：

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

示例代码：

Request：

POST /push.json HTTP/1.1
Host: api-cn.ronghub.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1585127132438
Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
Content-Type: application/json

{
  "platform":["ios","android"],
  "audience":{
    "tag":["女","年轻"],
    "tag_or":["北京","上海"],
    "userid":["123","456"],
    "is_to_all":false
  },
  "notification":{
    "alert":"this is a push",
    "ios": {"title": "标题","alert": "override alert","extras": {"id": "1","name": "2"}},
    "android": {"alert": "override alert","extras": {"id": "1","name": "2"}}
  }
}
已复制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

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 收到该消息后将无法解析。

文档是否解决您的问题 ?

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