更新时间: 2021-04-16

# 功能描述

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

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

3、默认消息中包含屏蔽敏感词时,不会同步到应用服务器,如果含有替换敏感词时,会将消息中的敏感词替换成设置的内容同步到应用服务器。如需要将含有屏蔽敏感词的消息也路由到应用服务器,可在提交工单申请开通。

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

如果公司网络有 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、117.50.18.131、120.92.114.181、106.75.117.2

  • 海外数据中心:

    52.221.93.74

# 使用场景

  1. 存储聊天记录:可通过开启此服务,实时同步用户发送的消息至应用服务器,由应用服务器进行存储。

  2. 数据迁移:实现第三方通讯云服务到融云的平滑迁移,您的新客户端(集成融云 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 不代表任何意义。开通后可通过该属性判断文本消息中是否含有敏感词,图片、语言消息审核不通过时标识为 1。目前支持单聊、群聊、聊天室会话类型,其他会话类型默认为 0 ,开通后含有屏蔽敏感词的消息也不会进行下发,只会进行消息路由。
source String 标识消息的发送源头,包括:iOS、Android、Websocket、MiniProgram(小程序)、PC、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

# 内置消息结构说明

当消息路由收到的消息为融云内置消息,消息类型和json结构请参考:内置消息类型

# 消息结构说明

通过 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:ReferenceMsg 存储 计数 存储 推送 消息内容

消息结构:

发送引用消息时 content 参数,以引用对象为文本消息为例,结构如下:

{
  "content":"消息内容!",
  "referMsgUserId":"432432",
  "objName":"RC:TxtMsg",
  "referMsg":{
    "content":"Hello world!",
    "extra":""
  },
  "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
17
18
19
20
21
22

属性说明:

名称 类型 必传 说明
content String 引用消息时发送的文字内容,包括表情。
referMsgUserId String 被引用消息的发送用户 Id。
referMsg String 被引用消息的消息结构 JSON 格式。
objName String 被引用消息的消息类型,目前支持的消息类型:文本 RC:TxtMsg、图片 RC:ImgMsg、文件 RC:FileMsg
mentionedInfo String 群组中 @ 消息信息,详细查看属性说明,单聊场景下无需设置此属性。
user String 消息中携带的用户信息,详细查看 user 参数说明。
extra String 扩展信息,可以放置任意的数据内容,也可以去掉此属性。

user 属性说明:

名称 说明
id 发送用户 Id。
name 发送用户需要显示的名称。
portrait 发送用户需要显示的头象。
extra 扩展信息,可以放置任意的数据内容。

mentionedInfo 属性说明:

名称 类型 必传 说明
type int @ 功能类型,1 表示 @ 所有人、2 表示 @ 指定用户。
userIdList String[] 指定用户列表,type 为 2 时有效,为 1 时 userIdList 可以为空。
mentionedContent String @ 消息的自定义 Push 内容。
# 位置消息
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 命令的内容。
# 已读通知消息

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

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

消息结构:

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

{
  "lastMessageSendTime":1408706337,
  "messageUId":"XXXXXX",
  "type":1
}
已复制
1
2
3
4
5

属性说明:

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

文档是否解决您的问题 ?

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