发送前回调

大约 8 分钟

发送前回调

概述

IM 服务器收到用户发送的上行单聊、群组或聊天室消息之后、将该消息下发给目标用户之前，IM 服务器会通过 HTTP/HTTPS POST 请求通知给你的应用服务器。应用服务器可以通过发送前回调实时处理用户的聊天消息，例如，拦截包含文本、图片、自定义消息等类型的消息。

  • 发送前回调只对客户端发送的消息有效，不包含通过 RESTful API 发送的消息。
  • 发送前回调支持文本、图片、位置、音频、视频、文件、透传、自定义消息和合并消息。
  • 发送前回调不支持群组/聊天室的定向消息。

实现步骤

  1. 开通回调服务。
  2. 配置回调规则。
  3. IM 服务器向你的应用服务器发送 HTTP/HTTPS POST 请求。

回调规则

开通发送前回调服务后，你需要在 声网控制台open in new window 配置回调规则才能使用该服务。

你可以按照以下步骤添加回调规则，最多可以配置 4 条发送前和发送后回调规则。

  1. 登录 声网控制台open in new window。

  2. 在左上角下拉框中选择想要开通消息回调服务的项目，然后点击左侧导航栏的全部产品，点击基础能力分组下的即时通讯 IM，进入功能配置标签页。

  3. 在消息与会话页签中，点击消息回调区域下的添加规则按钮。

  4. 在弹出的对话框中的发送前回调页签中，配置发送前回调相关信息，点击 保存 按钮，完成回调配置。

参数是否必填描述
规则名称是填写文字，支持中英文，长度限制为 32 字符。每个规则的名称必须唯一 。
会话类型是会话类型：
- 单聊
- 群组
- 聊天室
- 消息编辑
消息类型是支持发送前回调的消息类型包括文本、图片、视频、位置、语音、文件和自定义消息。
对同一 app，可针对文本、图片、自定义消息等类型的消息配置不同的规则，也支持通过同一规则选择两种以上消息类型同时回调至一个指定服务器地址。接收到消息后，你可以根据消息类型进行分类处理。
等待响应时间是后台判断超时时间，默认 200，单位为毫秒。如果回调超时无应答，消息默认会正常下发，支持修改消息处理逻辑。
调用失败时默认策略是当你的服务器返回结果异常或等待时间内未返回结果时，消息放行或不放行。
消息拦截报错时显示是当消息被拦截时，是否通知发送者 SDK 消息发送失败：
- 报错：通知发送者 SDK 消息发送失败，发送者会感知到消息发送失败；
- 不报错：不通知发送者 SDK 消息发送失败，发送者无感知。
启用状态是回调规则是否立即生效：
- 启用：立即生效；
- 关闭：暂不生效。(建议首次创建配置为关闭，等你的服务器配置好验证信息后再修改为启用)。
回调地址是回调 URL，即时通讯 IM 对 HTTP 和 HTTPS 的回调地址均支持。

配置回调规则后，声网服务器会自动为该规则生成 secret，向你的 app server 发送数据时会基于该 secret 生成签名（即请求中的 security 参数），作为你的服务器识别声网服务器的依据。若要使用自定义密钥，可以联系声网商务。

对同一 app，可针对不同消息类型配置不同的规则，也支持通过同一规则选择两种以上消息类型同时回调至一个指定服务器地址。接收到消息后，你可以根据消息类型进行分类处理。

img

与发送后回调的关系

若同时设置了消息发送前和发送后两种回调，且消息发送前回调返回拒绝，则消息发送后回调将不会被触发。

回调示例

消息发送给接收方之前，IM 服务器会向你的应用服务器发送 HTTP/HTTPS POST 请求，正文部分为 JSON 格式的字符串，字符集为 UTF-8。

请求示例

以下示例为在聊天室中发送消息：

{
    "callId":"XXXX-XXXX#test_0990a64f-XXXX-XXXX-8696-cf3b48b20e7e",
    "timestamp":1600060847294,
    "chat_type":"chatroom",
    "group_id":"16934809238921545",
    "from":"user1",
    "to":"user2",
    "msg_id":"8924312242322",
    "payload": {
      // 具体的消息内容。
    },
    "security":"2ca02c394bef9e7abc83958bcc3156d3"
}
参数类型
callId回调请求的唯一标识。
timestamp即时通讯 IM 服务器接收到此消息的时间戳。
chat_type聊天类型：chat 为单聊，group 为群组聊天，chatroom 为聊天室。
group_id回调消息所在的群组或聊天室。该参数仅对群组聊天或聊天室中的消息回调生效。
from消息的发送方。
to消息的接收方。单聊为消息接收方，群组聊天和聊天室为群组 ID 和聊天室 ID。
msg_id消息的 ID。
payload消息内容，与通过 RESTful API 发送过来的一致，查看 消息格式文档。
security签名，格式如下: MD5（callId+Secret+timestamp）。

请求字段说明

响应示例

{
  "valid": true,
  "code": "HX:10000",
  "chatroom_msg_level": "high",
  "payload": {
    // 具体的消息内容。
    // 仅支持文本类型消息。
  }
}

响应字段说明

消息发送到你的应用服务器后，应用服务器需返回 HTTP 响应码 200 和 valid 属性，根据 valid 状态决定是否进行下发。IM 服务器若未收到响应或你的应用服务器没有返回 valid 状态，该条消息会根据默认设置（规则中的调用失败时默认策略）处理，不会重试；后续消息依然正常执行回调。

响应内容不能超过 1,000 个字符，否则 IM 服务器会认为是攻击，导致回调失败。

参数类型是否必需描述
validbool是根据你的服务器设定的规则判断消息是否合法：
- true ：消息合法，IM 服务器应下发该消息；false ：消息非法，IM 服务器应拦截该消息。
chatroom_msg_levelString否聊天室消息的优先级：
- high：高
- normal：普通
- low：低
codeString否客户端上报的自定义发送前回调错误。声网控制台上的发送前回调页面中的消息拦截报错时显示设置为报错 时，该 code 的内容为客户端提示的错误。错误分为以下几种情况：
- 若 code 的内容为字符串类型，客户端上的错误为该参数的内容；
- 响应中不包含 code 字段， 客户端提示 custom logic denied；
- 若 code 为空字符串，移动客户端提示 Message blocked by external logic 错误；
- 若在指定时间内未收到应答包，则按默认配置处理，客户端提示 custom internal error 错误；
- 如果返回的应答包出现错误，包括缺少必填字段 valid 或字段类型不符合约定类型，客户端提示 custom internal error 错误。
payloadObject否修改后的消息内容。若无需修改消息内容，请勿传该参数。若需修改消息内容，可以回传修改后的内容，格式需与传入的消息内容一致。
- 目前，默认仅支持文本消息的消息内容和扩展信息，并且消息大小不能超过 1 KB。
- 若要支持修改图片、音频、视频、位置和自定义类型的相关内容和扩展信息（消息大小不能超过 5 KB），需要联系商务。注意，对于附件类型的消息，若要修改 url 字段，需关闭访问限制开关，否则端上可能因访问密钥（secret）验证失败，导致下载附件失败。
- 不支持修改透传消息。

常见问题

  1. Q: 发送前回调响应中的 valid 为 false，但为什么消息还是下发了？

    A：可能是你的服务器在发送前回调规则中配置的等待时间内未返回响应。这种情况下，如果你在 声网控制台open in new window 的发送前回调规则页面配置的调用失败时默认策略为放行，消息则会下发。为了避免这种情况，建议将等待响应时间（即时通讯 IM > 功能配置 > 消息与会话 > 消息回调 >添加规则 > 发送前回调，默认为 200 毫秒）参数的值提升，例如，增加至 3000 毫秒。

上次编辑于:
声网 IM 文档
© 声网 2026