发送前回调

概述

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

• 发送前回调只对客户端发送的消息有效，不包含通过 RESTful API 发送的消息。

• 发送前回调支持文本、图片、位置、音频、视频、文件和自定义消息，不支持命令消息。

实现步骤

1. 开通回调服务：在环信即时通讯云控制台开通消息回调服务。
2. 配置发送前回调规则：详见环信即时通讯云控制台规则配置说明。
3. 环信服务器向你的应用服务器发送 HTTP/HTTPS POST 请求。

回调规则

要使用发送前回调，你需要在环信即时通讯云控制台配置回调规则，详见规则配置说明。

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

与发送后回调的关系

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

回调示例

请求采用 POST 方式，支持 HTTP/HTTPS，正文部分为 JSON 格式的字符串，字符集为 UTF-8。

请求 header

字段名	值
Content-Type	内容类型，请填 application/json。

请求 body

参数	类型
callId	callId 为 {appkey}_{uuid}，其中 uuid 为随机生成，作为每条回调的唯一标识。
timestamp	环信 IM 服务器接收到此消息的时间戳。
chat_type	聊天类型：chat 为单聊，group 为群组聊天，chatroom 为聊天室。
group_id	回调消息所在的群组或聊天室。该参数仅对群组聊天或聊天室中的消息回调生效。
from	消息的发送方。
to	消息的接收方。单聊为消息接收方，群组聊天和聊天室为群组 ID 和聊天室 ID。
msg_id	消息的 ID。
payload	消息内容，与通过 REST API 发送过来的一致，查看 消息格式文档。
securityVersion	安全校验版本，目前为 1.0.0。请忽略此参数。
security	签名，格式如下: MD5（callId+Secret+timestamp）。Secret 见 环信即时通讯云控制台回调规则。

响应 body

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

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

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

示例

请求示例

{
    "callId":"XXXX-XXXX#test_0990a64f-XXXX-XXXX-8696-cf3b48b20e7e",
    "timestamp":1600060847294,
    "chat_type":"groupchat",
    "group_id":"16934809238921545",
    "from":"user1",
    "to":"user2",
    "msg_id":"8924312242322",
    "payload": {
    // 具体的消息内容
    },
    "securityVersion":"1.0.0",
    "security":"2ca02c394bef9e7abc83958bcc3156d3"
}

响应示例

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

常见问题

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

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