跳到主要内容

全量消息路由

全量消息路由服务支持将单聊、群组、超级群、聊天室、讨论组（废弃）、客服（废弃）的消息数据同步到指定的应用服务器。当接收到的消息为图片、视频类消息时，如果需要获取图片、视频等文件信息，可通过地址进行下载，文件存储有效期为 6 个月。

适用场景举例：

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

开通服务​

使用全量消息路由功能前，请确认已为当前 App Key 开通相关服务。详见消息管理服务配置。

开通服务时，请配置可正常访问的回调接收地址。如果您的网络有 IP 访问限制，请务必配置 IP 白名单，否则无法正常接收服务端回调。

限制与注意事项说明​

  • 消息中包含敏感词：

    • 通过内置敏感词服务、第三方审核服务（如数美）与消息回调服务，您可设置用于屏蔽消息的敏感词。如果消息因包含此类敏感词导致不下发给收件人，服务端默认也不会将该消息同步到应用服务器。如需将含有屏蔽敏感词的消息也路由到应用服务器，可在融云控制台的免费基础功能界面开通含敏感词消息开启路由功能。
    • 如果在内置敏感词服务的配置中设置了替换敏感词，会将消息中的敏感词替换成设置的内容再同步到应用服务器。如需获取原始内容，可参考知识库使用内置敏感词、IM 内容审核、消息回调服务时，如何获取消息原始内容？。

  • Server API 发送的消息默认不进行消息路由：

    • 通过调用 Server API 接口发送的消息，默认不会通过消息路由服务。如需修改默认行为，请在控制台免费基础功能页面开通 Server API 发送消息实时路由服务。

  • 单聊状态消息默认不进行消息路由：单聊会话中的状态类消息，默认不会被同步到应用服务器。包含以下情况：

    • 客户端自动往单聊会话中发送即时通讯服务预定义的状态类消息，例如“正在输入状态”消息，详见消息类型概述。
    • 客户端主动调用发送消息接口发送状态类消息，包括即时通讯服务预定义的状态类消息或客户自定义的状态消息。
    • 通过调用 Server API 接口发送单聊状态消息发送的任何消息。
    • 如果需要上述状态类消息启用消息路由，可在融云控制台，通过应用配置>IM 服务>免费基础功能>单群聊，开通单聊状态消息消息路由功能。注意，如果客户端使用了单聊会话「正在输入的状态」功能，该正在输入的状态消息也会进行路由和消息日志存储，消息量较大请谨慎开通。如果未开通 Server API 发送消息实时路由服务，则仅对客户端发送的状态类消息启用全量消息路由。

  • 始终不支持进行消息路由的情况：无论是否开通 Server API 发送消息实时路由服务，以下接口发送的消息始终不支持进行消息路由：

  • 单群聊消息扩展变更会进行全量消息路由：

    • 如果变更单群聊消息扩展，服务端会生成一条类型为 RC:MsgExMsg 的消息。新消息仅用于消息路由同步，不会同步给客户端 SDK。新消息 ID 由服务端生成，originalMsgUID 字段中会携带原消息的 MsgUID。
    • 注意，在发消息时即携带的扩展数据无法通过全量消息路由获取。

  • 超级群消息扩展变更默认不支持全量消息路由：

    • 2022.08.11 之后，超级群业务中对消息扩展的变更操作可以同步到您指定的应用服务器。考虑到消息扩展频率较大，可能产生大量消息，因此即时通讯服务端默认不进行全量消息路由。如有需要，请提交工单申请调整超级群消息扩展是否进行路由。开通服务后，如果变更超级群消息扩展，服务端会生成一条类型为 RC:MsgExMsg 的消息。新消息仅用于消息路由同步，不会同步给客户端 SDK。新消息 ID 由服务端生成，originalMsgUID 字段中会携带原消息的 MsgUID。
    • 注意，在发消息时即携带的扩展数据无法通过全量消息路由获取。

  • 超级群消息内容修改会进行全量消息路由：2022.08.11 之后，超级群业务中 App 用户修改的消息内容将会自动同步到应用服务器。用户在超级群中对指定消息进行修改后，服务端会生成一条新消息，同时保留原消息内容与原消息 ID。新消息用于消息路由同步，消息类型同原消息相同。新消息 ID 由服务端生成，不会同步给客户端 SDK。新消息的 originalMsgUID 字段中会携带原消息的 MsgUID。

回调方法​

请求方法： POST

数据格式： application/x-www-form-urlencoded

即时通讯服务端会在 POST 请求 URL 中添加签名参数，您可通过签名验证调用者身份和数据有效性，详细参见 服务端回调签名。注意，全量消息路由的回调请求路径中同时包含 timestamp 与 signTimestamp 路径参数。两者值相同，建议仅解析 signTimestamp 参数。signTimestamp 格式为 Unix 时间戳。

回调正文参数​

该回调服务的 HTTP 请求正文数据格式为 application/x-www-form-urlencoded，包含以下 HTTP 表单参数：

参数类型说明
fromUserIdString发送用户 ID。
toUserIdString目标 ID，即为客户端 targetId，根据会话类型 channelType 的不同，可能为二人目标 ID、群聊 Id、聊天室 ID、客服 Id 等。
objectNameString消息类型，例如文本消息 RC:TxtMsg、图片消息 RC:ImgMsg。参见消息类型概述。
contentString发送的消息内容。消息内容结构参考用户内容类消息格式或其他内置消息类型的消息内容格式。
channelTypeString会话类型。PERSON（二人会话）、PERSONS（讨论组会话）、GROUP（群组会话）、TEMPGROUP（聊天室会话）、CUSTOMERSERVICE（客服会话）、NOTIFY（系统通知）、MC（应用公众服务）、MP（公众服务）、 ULTRAGROUP（超级群服务）。

该字段对应客户端 SDK 中 ConversationType 类型：1（二人会话）、2（讨论组会话）、3（群组会话）、4（聊天室会话）、5（客服会话）、6（系统通知）、7（应用公众服务）、8（公众服务）、10（超级群服务）。
msgTimestampString服务端收到客户端发送消息时的服务器时间（1970年到现在的毫秒数）。
msgUIDString可通过 msgUID 确定消息唯一。
originalMsgUIDString原始消息 ID，仅针对超级群会话有效。在修改消息、扩展消息、删除消息时，此字段携带有效值。可通过此字段查询原始消息内容。修改超级群消息后，如果需要在服务端撤回消息，必须使用该 ID。
sensitiveTypeInt消息中是否含有敏感信息。0 为不包含，1 为含有屏蔽敏感词，2 为含有替换敏感词。

注意：含有屏蔽敏感词的消息默认不进行路由，可在控制台，通过免费基础功能>安全>含敏感词消息开启路由开通。
  • 如果未开通（默认）， sensitiveType 值默认为 0，不代表任何意义。
  • 如果已开通，可通过该属性判断文本消息中是否含有敏感词。图片、语言消息审核不通过时标识为 1。支持单聊、群聊、聊天室会话类型，其他会话类型默认为 0，开通后含有屏蔽敏感词的消息也不会进行下发，只会进行消息路由。
sourceString标识消息的发送源头，包括：iOS、Android、HarmonyOS、Websocket、MiniProgram（小程序）、PC、Server（通过 Server API 发送，需要开通 Server API 发送消息进行消息路由功能）。
busChannelString会话频道 ID，使用超级群频道功能时，可通过 buschannel 获取频道 ID，未使用时该内容为空。
groupUserIdsString[]接收群定向消息的群组成员用户 ID 数组。仅群组会话（channelType 为 GROUP）支持群定向消息，如果指定的用户不在群组中，该字段为空。非群定向消息时，该字段为空。

回调请求示例​

假设您在开通服务页面配置的接收地址：http://example.com/receive_message.php

HTTP
POST /receive_message.php?appKey=someappKey&timestamp=1681202504348&signTimestamp=1681202504348&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"]

响应回调请求​

提示
  • 只要有 HTTP 200 OK 成功响应，服务端会认为状态已经同步。
  • 如果应答超时 5 秒，服务端会再尝试推送 2 次，如果仍然失败，将不再同步此条状态。
  • 如短时间内有大面积超时，将暂时停止请求您的服务器，1 分钟后会继续发送回调请求。异常断网情况下的会延迟 5 分钟同步。
最后于 更新