融云开发者文档

更新时间: 2021-03-01

# 实现方法

# 普通消息发送

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

请求方法： POST

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

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

输入参数：

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

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/private/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=2193&toUserId=2192&objectName=RC:TxtMsg&pushContent=thisisapush&pushData=%7B%22pushData%22%3A%22hello%22%7D&count=4&verifyBlacklist=0&isPersisted=1&isIncludeSender=0&disablePush=false&expansion=false
已复制

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/private/publish_template.json

请求方法： POST

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

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

输入参数：

参数	类型	必传	说明
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 之后推出的一种推送方式。允许应用在收到通知后在后台运行一段代码，且能够马上执行，查看详细 (opens new window)。1 表示为开启，0 表示为关闭，默认为 0
expansion	Boolean	否	是否为可扩展消息，默认为 false，设为 true 时终端在收到该条消息后，可对该条消息设置扩展信息。
disablePush	Boolean	否	是否为静默消息，默认为 false，设为 true 时终端用户离线情况下不会收到通知提醒。
pushExt	String	否	推送通知属性设置，详细查看 pushExt 结构说明，pushExt 为 JSON 结构请求时需要做转义处理。disablePush 为 true 时此属性无效。

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/private/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"],
  "verifyBlacklist":0,
  "disablePush":false,
  "expansion":false
}
已复制

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

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

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

Response：

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

{"code":200}
已复制

1
2
3
4

# 状态消息发送

说明：

目标用户在线时会收到此条消息，如未在线则不会收到此条消息，不会保存到离线消息中。状态消息在服务端不计数、不存储，移动端 App 收到状态消息时，会根据消息在本地注册时设置的计数、存储属性决定是否计数、是否进行本地存储。

单聊状态消息默认不支持消息路由功能，如需要开通请提交工单申请，开通后如客户使用了单聊“正在输入的状态”功能，“正在输入的状态消息”也会进行路由，消息量较大请谨慎开通。

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

请求方法： POST

发送频率： 通过 Server API 单个应用每分钟最多发送 6000 条信息，每次可发送目标用户上限为 1000 人。可在开发者后台 (opens new window)调整发送频率。

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

输入参数：

参数	类型	必传	说明
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 为正常。

示例代码：

Request：

POST /statusmessage/private/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
已复制

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

# 自定义消息发送

通过 Server API 发送消息，都支持发送自定义消息，开发者需要定义消息的 ObjectName 消息类型，需要注意，不要以 "RC:" 开头，以避免与融云系统内置消息的 ObjectName 重名，同时 content 设置为自己需要的消息结构即可。

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

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

# 注意事项

1、发送消息所使用的用户 Id 必须曾经通过获取 Token 接口或者刷新用户信息接口，将用户昵称同步给融云过，否则接收者终端未在线发送 Push 时无法正确显示发送者用户信息。

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

# 消息结构说明

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

# 内容类消息

融云内置了一些内容类消息：

消息类型	ObjectName
[文字消息]	`RC:TxtMsg`
[语音消息]	旧消息类型 `RC:VcMsg`，新消息类型 `RC:HQVCMsg`
[图片消息]	`RC:ImgMsg`
[GIF 图片消息]	`RC:GIFMsg`
[图文消息]	`RC:ImgTextMsg`
[文件消息]	`RC:FileMsg`
[位置消息]	`RC:LBSMsg`
[小视频消息]	`RC:SightMsg`
[引用消息]	`RC:ReferenceMsg`
[合并转发消息]	`RC:CombineMsg`

内容类消息具体明细，请参考：消息类型-内容类消息文档。

# 提示小灰条消息

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	是	命令的内容。

# 已读通知消息

用来发送消息已经被接收到的状态消息，客户端收到消息后不计入未读消息数、不存储，此类型消息没有 Push 通知。

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

消息结构：

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

{
  "lastMessageSendTime":1408706337,
  "messageUId":"XXXXXX",
  "type":1
}
已复制

1
2
3
4
5

属性说明：

名称	类型	必传	说明
lastMessageSendTime	Int	是	已读的最后一条消息的发送时间。
messageUId	String	是	已读的最后一条消息的 UId，消息唯一标识。
type	Int	是	会话类型，目前该消息只支持单聊会话，类型为 1。

文档是否解决您的问题 ?

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