跳到主要内容

消息回调服务

消息回调服务支持对 App 中发送的消息进行拦截、内容过滤、内容替换，适用于对接您自己或其他第三方内容审核服务的应用场景。

目前已支持单聊、群组、聊天室、超级群业务。

消息回调服务概述​

消息回调服务会根据您在控制台配置的路由规则拦截发送中的消息。被拦截的消息副本会先行发送至您指定的应用服务器（App 后端），而不是直接发送给目标用户。

App 后端可通过对回调请求的响应，实现对消息的以下处理：

  • 决定是否需要继续下发消息（如超时未回复，即时通讯服务端默认自动下发消息）
  • 决定是否需要继续下发消息扩展（仅针对超级群会话类型，如超时未回复，即时通讯服务端默认自动下发）
  • 决定是否需要继续下发消息修改（仅针对超级群会话类型，如超时未回复，即时通讯服务端默认自动下发）
  • 使用响应正文中指定字段，直接修改消息内容
  • 使用响应正文中指定字段，直接修改消息的推送内容（展示在推送通知栏的内容）
  • 使用响应正文中指定字段，直接修改消息扩展 KV。

即时通讯服务端会根据 App 后端返回的响应结果，决定是否将消息下发、是否替换消息中的内容，以及如何进行内容替换。

开通服务​

前往控制台的消息回调服务页面开通服务。生产环境下需要预存费用才能开通。

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

消息回调默认不会对 Server API 接口发送的消息生效。如果需要将 IM Server API 发送的消息按照您配置的路由规则过滤并发送到应用服务器，需要在控制台的免费基础功能页面启用 Server API 发送消息过滤敏感词。

提示
  • 2021.5.10 号之后开通消息回调服务，默认支持在响应正文中使用 replaceContent 字段消息内容替换。2021.5.10 号之前开通的客户需要此功能，必须提交工单申请。
  • 2022.8.18 号之后开通消息回调服务，默认支持响应正文中使用 replaceDisablePush、replacePushExt、replaceExtraContent 字段对消息内容进行替换。2022.8.18 号之前开通的客户需要此功能，必须提交工单申请。

创建路由规则​

使用消息回调服务需要在控制台创建消息回调服务规则（即路由规则）。

服务开通后，可在消息回调服务页面创建路由规则。一条路由规则包含以下字段：

  • 规则名称：填写规则名称。
  • 会话类型：选择规则适用的会话类型类型，支持单聊、群聊、聊天室、超级群。
  • 消息标识：填写消息类型的唯一标识，一条规则仅支持填写一个标识。例如内置的文字消息类型的标识是 RC:TxtMsg。详见消息类型概述。支持自定义消息类型的标识。
  • 发送 ID：填写发送者的用户 ID，也可以指定规则匹配用户 ID。配置成功后，本条规则仅针对匹配的用户生效。
  • 接收 ID：填写会话 ID，也可以指定规则匹配会话 ID。配置成功后，本条规则仅针对匹配的会话生效。单聊会话 ID 为接收用户 ID。群组、超级群的会话 ID 为群 ID。聊天室会话 ID 为聊天室房间 ID。
  • 回调地址：填写接收回调的地址，请保证公网可访问。

注意事项说明​

  • 单群聊消息扩展支持消息回调

    • 在发消息时即携带的扩展数据，可通过回调参数 extraContent 获取。
    • 2022.08.11 之后，支持将超级群业务中的消息扩展变更发送到应用服务器。超级群消息进行扩展后，服务端会生成一条类型为 RC:MsgExMsg 的消息。新消息仅用于消息路由同步，不会同步给客户端 SDK。新消息 ID 由服务端生成，originalMsgUID 字段中会携带原消息的 messageId，content 字段中为当次变更的扩展数据（结构参见消息扩展功能消息）。如需对消息扩展启用消息回调服务，您需要在控制台添加针对 RC:MsgExMsg 类型的路由规则。

  • 超级群消息扩展支持消息回调：

    • 在发消息时即携带的扩展数据，可通过回调参数 extraContent 获取。
    • 2022.08.11 之后，支持将超级群业务中对消息扩展的后续变更操作也同步到应用服务器。变更超级群消息扩展后，服务端会生成一条类型为 RC:MsgExMsg 的消息。新消息仅用于消息路由同步，不会同步给客户端 SDK。新消息 ID 由服务端生成，originalMsgUID 字段中会携带原消息的 messageId，content 字段中为当次变更的扩展数据（结构参见消息扩展功能消息）。如需对消息扩展启用消息回调服务，您需要在控制台添加针对 RC:MsgExMsg 类型的路由规则。

  • 超级群消息内容修改支持消息回调：超级群消息发送之后支持对其进行修改（不可修改消息类型）。2022.08.11 之后，支持将超级群业务中 App 用户修改的消息内容发送到应用服务器。用户修改消息后，服务端会生成一条新消息，同时保留原消息内容与原消息 ID。新消息仅用于同步，消息类型同原消息相同，因此无需额外创建路由规则。新消息 ID 由服务端生成，不会同步给客户端 SDK。新消息的 originalMsgUID 字段中会携带原消息的 messageId。

  • 媒体消息中的文件需要自行获取：消息为图片、视频类消息时，如果需要获取图片、视频等文件信息，可通过消息中携带的地址进行下载，文件存储有效期为 6 个月。

  • 与全量消息路由服务可以同时使用：消息回调、内容审核与敏感词过滤服务可以与全量消息路由服务同时使用，这些服务中被拒绝下发的消息，默认不执行全量消息路由同步操作。如需修改默认行为，您可以在融云控制台，通过应用配置>IM 服务>免费基础功能>安全，开通含敏感词消息开启路由功能。开通此功能后，含有屏蔽敏感词的消息也会同步到应用服务器。

回调方法​

请求方法： POST

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

即时通讯服务端会在 POST 请求 URL 中添加签名参数，您可通过签名验证调用者身份和数据有效性，详细参见 服务端回调签名。

回调正文参数​

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

名称类型说明
appKeyString应用 App Key。
fromUserIdString发送用户 ID。
targetIdString目标会话 ID，根据会话类型可能为单聊 ID、群聊 ID、聊天室 ID、超级群 ID。
toUserIdsString群成员 ID 列表（以英文逗号分隔）。发送群聊定向消息时，接收消息的群成员用户 ID 列表。非群定向消息时为空。
msgTypeString配置好回调的消息类型（包括自定义消息），详见消息类型概述。
contentObjectJSON 结构的消息内容。如果 msgType 为内置消息类型，消息内容结构参考用户内容类消息格式或其他内置消息类型的消息内容格式。如果 msgType 是您自定义的消息类型，请参考该自定义消息的消息结构。

该字段支持通过回调响应进行修改。
pushContentString发送消息时设置的推送通知栏显示内容。离线推送通知中显示该内容。

该字段支持通过回调响应进行修改。
disablePushBoolean是否为静默消息，默认为 false，设为 true 时终端用户离线情况下不会收到通知提醒。

该字段支持通过回调响应进行修改。
pushExtString配置消息的推送通知，如推送通知的标题等。详见服务端文档发送消息中对 pushExt 的说明。disablePush 属性为 true 时此属性无效。

该字段支持通过回调响应进行修改。
expansionBoolean是否为可扩展消息，默认为 false，设为 true 时终端在收到该条消息后，可对该条消息设置扩展信息。
移动端 SDK 4.0.3 版本、Web 端 3.0.7 版本支持此功能
extraContentObject消息扩展的内容，JSON 结构的 Key、Value 对，如：{"type":"3"}。Key 最大 32 个字符，支持大小写英文字母、数字、 特殊字符+ = - _ 的组合方式，不支持汉字。Value 最大 4096 个字符。该字段仅在 expansion 为 true 时生效。

该字段支持通过回调响应进行修改。
channelTypeString会话类型。支持的会话类型包括：PERSON（二人会话）、PERSONS（讨论组会话）、GROUP（群组会话）、TEMPGROUP（聊天室会话）、ULTRAGROUP（超级群会话）。
msgTimeStampString服务端收到客户端发送消息时的服务器时间（1970年到现在的毫秒数）。
messageIdString消息唯一标识。
originalMsgUIDString原始消息 ID，仅针对超级群会话有效。在修改消息、扩展消息、删除消息时，此字段携带有效值。可通过此字段查询原始消息内容。修改超级群消息后，如果需要在服务端撤回消息，必须使用该 ID。
osString消息来源，包括：iOS、Android、HarmonyOS、Websocket、MiniProgram（小程序）、PC、Server。
busChannelString会话频道 ID。如果消息为超级群频道中的消息，您可通过 busChannel 获取频道 ID。未使用时该内容为空。
clientIpString用户当前的 IP 地址及端口，格式：192.168.6.124:80。

回调请求示例​

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

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

appKey=123&content={"content":"123"}&fromUserId=fid123&targetId=tid123&msgType=RC:TxtMsg&messageId=596E-P5PG-4FS2-7OJK&msgTimeStamp=1408710653491&channelType=ULTRAGROUP&os=Server&busChannel=basketball

响应回调请求​

消息发送到应用服务器后，应用服务器需要返回 HTTP 应答码 200，同时指定 pass 属性值。即时通讯服务端将根据 pass 状态决定是否下发消息。

响应的 HTTP 请求正文数据格式为 application/json，包含具有以下结构的 JSON 对象：

返回参数名称类型说明
passInt
  • 2021.5.10 号前开通服务返回状态说明：

    1 表示正常下发此条消息；其他表示拒绝。

  • 2021.5.10 号后开通服务返回状态说明：
    • 0 表示拒绝，不下发此条消息。
    • 1 表示正常下发此条消息，如满足其他消息回调条件继续执行。
    • 2 表示正常下发此条消息，如满足其他消息回调条件不继续执行；
注意：2021.5.10 号前开通服务的客户如需使用最新返回状态定义，可提交工单申请。
replaceContentString非必传，JSON 结构，需要替换的消息内容，例如需要替换文本消息内容传入 {\"content\":\"替换后的内容\"} ；针对自定义消息支持标准 JSON 结构的内容替换，例如需要替换自定义消息 msg 中 content 的内容，传入 \"msg\":{\"content\":\"替换后内容\"} 即可，自定义消息最多支持替换到第六层级的结构内容，如不传则不进行替换。
replacePushContentString非必传，替换后的 pushContent 字段内容。如果此字段不填或填写了空字符串，则默认使用原值。
replaceDisablePushBoolean是否为静默消息，默认为 false，设为 true 时终端用户离线情况下不会收到通知提醒。
replacePushExtString非必传，替换后的 pushExt 字段内容。详见服务端文档发送消息中对 pushExt 的说明。如果此字段不填或填写了空字符串，则默认使用原值。
replaceExtraContentString非必传，有值则替换 extraContent 的内容。

数据格式如：{\"key1\":{\"v\":\"value1\"},\"key2\":{\"v\":\"value2\"}}。详见服务端文档发送消息中对 extraContent 的说明。

数据集大小限制如下：Key 支持大小写英文字母、数字、特殊字符 + = - _ 的组合方式，不支持汉字，最大 32 个字符，Value 最大 4096 个字符。
extraString消息不下发时（即 pass 为 0 时）用于通知消息发送方的通知数据，例如无法下发消息的具体原因。该字段携带的数据将通过客户端的「敏感消息拦截回调」返回发送方，放入被拦截消息详细信息的 extra 字段。目前支持单聊、群聊、 聊天室、超级群会话类型。长度不可超过 1024 个字符。客户端 SDK 版本要求：Web IMLib SDK ≧ 5.3.3，Android IM SDK 版本 ≧ 5.2.5（或 5.2.3.2 及以上的 5.2.3.x 系列的维护版本）。
重要
  • 响应正文中是否可使用的 replaceContent、replaceDisablePush、replacePushExt、replaceExtraContent 字段与开通服务日期相关。请仔细阅读开通服务。
  • 字段中如数据大小超出限制、数据格式错误会导致消息下发失败。建议 replacePushExt 控制在 1.5 KB 以内。推送相关字段总体长度不可超过 3.8 KB，如超限制可能导致部分第三方厂商通道推送消息失败。推送相关字段具体指 replacePushContent、 replacePushExt，或未经替换字段的原值。
  • 如果应答超时 5 秒，服务端会再尝试推送 3 次，如果仍然失败，即时通讯服务默认将下发此条消息。
  • 如短时间内有大面积超时，将暂时停止请求您的服务器，1 分钟后会继续发送回调请求。

响应示例​

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

{ "pass": 1 }

关于替换消息内容的提示​

替换消息内容对发送端、接收端的本地与服务端的历史消息记录有不同的影响。请谨慎使用此功能。

提示
  • 单聊和群聊消息替换后，发送方的本地和服务端历史消息中存储的是替换前的内容，而接收方本地和服务端存储的是经过替换后的内容。
  • 聊天室消息替换后，发送方本地为替换前的内容，接收方本地是经过替换后的内容；发送方和接收方服务端存储的都为替换后的内容。
  • 超级群消息替换后，发送方本地为替换前的内容，服务端历史消息中存储的是替换后的内容（因此换端登录后拉取历史消息时为替换后的内容），接收方本地和服务端为替换后的内容。
最后于 更新