更新时间: 2021-06-02

# 功能描述

是指系统向 App 中所有在线用户发送消息的行为。当用户正在使用 App 时,消息会展示在聊天界面和会话列表界面,会话类型为 SYSTEM。

# 在线广播消息

# 功能接口

系统通知消息,只能通过 Server API 进行发送,终端用户收到系统消息后,不支持消息回复功能。
在线广播消息使用的是服务端通知 SDK 拉取机制实现,发送消息后极端情况下用户 5 分钟内可收到此条消息。

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

请求方法: POST

调用频率: 通过 Server API 单个应用每分钟最多发送 10 次。

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

输入参数:

参数 类型 必传 说明
fromUserId String 发送人用户 Id。
objectName String 消息类型,可自定义消息类型,长度不超过 32 个字符,在自定义消息时需要注意,不要以 "RC:" 开头,以避免与融云系统内置消息的 ObjectName 重名。
content String 发送消息内容,单条消息最大 128k,内置消息以 JSON 方式进行数据序列化,消息中可选择是否携带用户信息,详见消息结构示例;如果 objectName 为自定义消息类型,该参数可自定义格式,不限于 JSON。

返回结果:

返回值 返回类型 说明
code Int 返回码,200 为正常。
# 调用示例

Request:

POST /message/online/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
已复制
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 发送的消息,消息体为 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 命令的内容。

文档是否解决您的问题 ?

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