融云开发者文档

( 最近更新时间：2020-04-28 19:00:00 )

# 全量消息路由

# 功能描述

1、支持将单聊、讨论组、群组、聊天室、客服的消息数据同步到开发者应用服务器。该服务需要开通 IM 商用版 (opens new window)后才有使用。

2、调用 Server API 接口发送的消息，默认不会通过消息路由服务，如果需要路由可在开发者后台免费基础功能 (opens new window)中开通，需要注意开通后广播消息也不进行消息路由。

3、默认消息中包含屏蔽敏感词时，不会同步到应用服务器，如果含有替换敏感词时，会将消息中的敏感词替换成设置的内容同步到应用服务器。如需要将含有屏蔽敏感词的消息也路由到应用服务器，可在开发者后台免费基础功能 (opens new window)中开通。

4、路由的消息为图片、视频类消息时，开发者如果需要获取图片、视频等文件信息，可通过地址进行下载，融云文件存储有效期为 6 个月。

5、如果公司网络有 IP 访问限制需要将以下 IP 地址加入到白名单中，才可以使用消息路由服务：

120.92.12.217、120.92.12.60、120.92.12.253、120.92.12.113、120.92.12.29、120.92.12.214、120.92.12.164、120.92.12.153、120.92.12.204、120.92.12.138、120.92.13.82、120.92.13.83、120.92.13.84、120.92.13.85、120.131.13.147

使用场景

存储聊天记录：可通过开启此服务，实时同步用户发送的消息至应用服务器，由应用服务器进行存储。
数据迁移：实现第三方通讯云服务到融云的平滑迁移，您的新客户端（集成融云 SDK）向老客户端（即集成原第三方 SDK）发送消息时，融云会通过消息路由服务调用原第三方的相应服务端接口，实现向指定老客户端（即集成原第三方 SDK）用户发送消息。详细请查看如何实现第三方通讯云服务到融云的平滑迁移。

# 参数说明

参数	类型	说明
fromUserId	String	发送用户 Id。
toUserId	String	目标 Id，即为客户端 targetId，根据会话类型 channelType 的不同，可能为二人会话 Id、群聊 Id、聊天室 Id、客服 Id 等。
objectName	String	消息类型，文本消息 `RC:TxtMsg` 、图片消息 `RC:ImgMsg` 、语音消息 `RC:VcMsg` 、图文消息 `RC:ImgTextMsg` 、位置消息 `RC:LBSMsg` 、添加联系人消息 `RC:ContactNtf` 、提示条通知消息 `RC:InfoNtf` 、资料通知消息 `RC:ProfileNtf` 、通用命令通知消息 `RC:CmdNtf` ，详细请参见消息类型说明文档。
content	String	发送消息内容，参考融云消息类型说明
channelType	String	会话类型，二人会话是 `PERSON` 、讨论组会话是 `PERSONS` 、群组会话是 `GROUP` 、聊天室会话是 `TEMPGROUP` 、客服会话是 `CUSTOMERSERVICE` 、系统通知是 `NOTIFY` 、应用公众服务是 `MC` 、公众服务是 `MP`。对应客户端 SDK 中 `ConversationType` 类型，二人会话是 1 、讨论组会话是 2 、群组会话是 3 、聊天室会话是 4 、客服会话是 5 、系统通知是 6 、应用公众服务是 7 、公众服务是 8。
msgTimestamp	String	服务端收到客户端发送消息时的服务器时间（1970年到现在的毫秒数）。
msgUID	String	可通过 msgUID 确定消息唯一。
sensitiveType	Int	消息中是否含有敏感词标识，0 为不含有敏感词，1 为含有屏蔽敏感词，2 为含有替换敏感词。消息路由功能默认含有屏蔽敏感词的消息不进行路由，可提交工单开通含有敏感词的消息路由功能，未开通情况下 sensitiveType 值默认为 0 不代表任何意义。开通后可通过该属性判断消息中是否含有敏感词。目前支持单聊、群聊、聊天室会话类型，其他会话类型默认为 0 ，开通后含有屏蔽敏感词的消息也不会进行下发，只会进行消息路由。
source	String	标识消息的发送源头，包括：iOS、Android、Websocket、MiniProgram（小程序）、Server（通过 Server API 发送，需要开通 Server API 发送消息进行消息路由功能）。目前支持单聊、群聊会话类型，其他会话类型为空。
groupUserIds	String[]	channelType 为 GROUP 时此参数有效，显示为群组中指定接收消息的用户 ID 数组，该条消息为群组定向消息。非定向消息时内容为空，如指定的用户不在群组中内容也为空。

同步消息时需要服务提供应答 200，收到应答后表示消息同步成功，如果应答超时 5 秒，融云会再尝试推送 2 次，如果仍然失败，融云将不再推送此消息，如短时间内有大面积超时，将暂停推送，1 分钟后会继续推送。

# 代码示例

为了验证数据有效性并确保调用者为融云 Server，每个请求前添加数据签名，详细参见 API 接收签名规则，签名信息参数在接收地址的 URL 上提供。

假设开发者注册的接收地址：http://example.com/receive_message.php

请求方法： POST

Request：

POST /receive_message.php?signTimestamp=1408710653491&nonce=14314&signature=45beb7cc7307889a8e711219a47b7cf6a5b000e8 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
User-Agent: RongCloud/1.0

fromUserId=123&toUserId=456&objectName=RC%3ATxtMsg&content=%7B"content"%3A"hello"%7D&channelType=PERSON&msgTimestamp=1408710653491&msgUID=596E-P5PG-4FS2-7OJK&groupUserIds=[543,567]
已复制

1
2
3
4
5
6

# 消息结构说明

以下为融云内置消息类型说明：

# 文本消息

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 图片文件大小，单位为 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":"/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	是	文件大小，单位：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":"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	是	视频大小单位 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: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	扩展信息，可以放置任意的数据内容。

# 发送 @ 消息

@ 消息推送会越过所有免打扰逻辑，给用户推送 Push 通知。

消息结构：

发送文本消息时在参数 content 中携带 mentionedInfo 属性可支持发送群＠消息

{
  "content":"@张三 c#hello",
  "mentionedInfo":{
    "type":2,
    "userIdList":["123","456"],
    "mentionedContent":"有人@你"
  },
  "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
16

属性说明：

名称	类型	必传	说明
content	String	是	文字消息的文字内容，包括表情。
mentionedInfo	String	是	群组中 @ 消息详细信息。
type	int	是	@ 功能类型，1 表示 @ 所有人、2 表示 @ 指定用户。
userIdList	String[]	否	指定用户列表，type 为 2 时有效，为 1 时 userIdList 可以为空。
mentionedContent	String	否	@ 消息的自定义 Push 内容。
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:GrpNtf	存储	不计数	存储	不推送	无

消息结构：

发送群组操作通知消息时 content 参数的 JSON 结构如下：

{
  "operatorUserId":"4324",
  "operation":"Rename",
  "data":"群组中各种通知的操作数据",
  "message":"修改本群名为本地生活",
  "extra":""
}
已复制

1
2
3
4
5
6
7

属性说明：

名称	类型	必传	说明
operatorUserId	String	是	操作人用户 Id。
operation	String	是	操作名称，可以自行定义。
data	String	是	群组中各种通知的操作数据，详见“群组通知消息结构数据说明”。
message	String	是	消息内容。
extra	String	否	扩展信息，可以放置任意的数据内容，也可以去掉此属性。

群组通知消息结构数据说明：

融云内置的群组操作通知消息结构 JOSN 格式如下：

创建群组：

{
  "operatorUserId":"4324",
  "operation":"Create",
  "data":"{\"operatorNickname\":\"李天\",\"targetGroupName\":\"群名\"}",
  "message":"创建群组",
  "extra":""
}
已复制

1
2
3
4
5
6
7

属性说明：

operatorUserId 为操作人用户 Id
operation：操作名，默认为 Create
data 数据说明： operatorNickname 为操作者，targetGroupName 为群名称

修改群名称

{
  "operatorUserId":"4324",
  "operation":"Rename",
  "data":"{\"operatorNickname\":\"李天\",\"targetGroupName\":\"群名\"}",
  "message":"修改群名称",
  "extra":""
}
已复制

1
2
3
4
5
6
7

属性说明：

operatorUserId 为操作人用户 Id
operation：操作名，默认为 Rename
data 数据说明：operatorNickname 为操作者，targetGroupName 为群名称

添加群成员

{
  "operatorUserId":"4324",
  "operation":"Add",
  "data":"{\"operatorNickname\":\"李天\",\"targetUserIds\":[\"wGPkc0\"],\"targetUserDisplayNames\":[\"腾飞\"]}",
  "message":"添加群成员",
  "extra":""
}
已复制

1
2
3
4
5
6
7

属性说明：

operatorUserId 为操作人用户 Id
operation：操作名，默认为 Add
data 数据说明：operatorNickname 为操作者
targetUserIds 为被加入群的用户 ID
targetUserDisplayNames 为被加入群的用户与 targetUserIds 相对应

移出群成员

{
  "operatorUserId":"4324",
  "operation":"Kicked",
  "data":"{\"operatorNickname\":\"李天\",\"targetUserIds\":[\"wGPkc0\"],\"targetUserDisplayNames\":[\"腾飞\"]}",
  "message":"移出群成员",
  "extra":""
}
已复制

1
2
3
4
5
6
7

属性说明：

operatorUserId 为操作人用户 Id
operation：操作名，默认为 Kicked
data 数据说明：operatorNickname 为操作者
targetUserIds 为被移出群的用户 ID
targetUserDisplayNames 为被移出群的用户名与 targetUserIds 相对应

退出群组

{
  "operatorUserId":"4324",
  "operation":"Quit",
  "data":"{\"operatorNickname\":\"李天\",\"targetUserIds\":[\"wGPkc0VpO\"],\"targetUserDisplayNames\":[\"腾飞\"],\"newCreatorId\":\"newCreatorId\"}",
  "message":"退出群组",
  "extra":""
}
已复制

1
2
3
4
5
6
7

属性说明：

operatorUserId 为操作人用户 Id
operation：操作名，默认为 Quit
data 数据说明：operatorNickname 为操作者，targetUserIds 为操作者 ID ，targetUserDisplayNames 为操作者
newCreatorId 如退出群的用户为群创建者则 newCreatorId 为新的群创建者 ID ，否则为 null

解散群组

{
  "operatorUserId":"4324",
  "operation":"Dismiss",
  "data":"{\"operatorNickname\":\"李天\"}",
  "message":"解散群组",
  "extra":""
}
已复制

1
2
3
4
5
6
7

属性说明：

operatorUserId 为操作人用户 Id
operation：操作名，默认为 Dismiss
data 数据说明：operatorNickname 为操作者

文档是否解决您的问题 ?

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