文档中心
即时通讯
服务端 API
回调说明
消息发送前回调

消息发送前回调

更新时间：2024-10-15 23:28

描述

此回调支持的消息类型为文本消息、图片消息、文件消息、音频消息、视频消息、自定义消息，不支持信令消息、弹幕消息。
此回调仅支持通过 SDK 发送的消息。若通过服务端发送消息，则您的业务后台不会收到此回调。

设置此回调后，当用户发送单聊、群聊或房间聊天消息时，ZIM 会向您的业务后台发起请求，您可以通过应答，对消息进行实时操作，如：

记录聊天消息，拦截违规发言请求；
实现黑白名单功能，由您判断哪些消息可以正常发出。

ZIM 会根据您的应答和 ZIM 内容服务的开通情况，决定消息是否发送，详情请参考本文档应答参数。

回调说明

请求方法：POST。
- 回调数据需要 UrlDecode 解码。
- 使用 POST 请求方法传递参数时：
  - Body 中的参数直接传 JsonObject 格式即可，无需序列化为 String 格式。
  - Headers 中，设置 “Content-type” 为 “application/json”。

请求地址：请在 ZEGO 控制台上配置回调地址，配置流程请参考控制台文档 ZIM 相关回调配置。
传输协议：HTTPS/HTTP，建议使用 HTTPS。

回调参数

公共参数	类型	描述
appid	String	App 的唯一标识。
event	String	回调事件，此回调返回值为 `before_send_msg`。
nonce	String	随机数，用于计算 signature。
signature	String	检验串，详情见检验说明。
timestamp	Int	服务器当前时间，Unix 时间戳，单位为秒（s），用于计算 signature。
request_id	String	请求 ID。
业务参数	类型	描述
from_user_id	String	消息发送者 ID。
conv_id	String	目标会话 ID。
conv_type	Int	目标会话类型： 0：单聊。 1：房间。 2：群聊。
msg_id	String	消息 ID，可借此确定消息的唯一性。
payload	String	消息扩展字段。
msg_type	Int	消息类型： 1：文本。 11：图片。 12：文档。 13：音频。 14：视频。 200：自定义。
sub_msg_type	Int	具体的自定义类型。值由用户发送自定义消息时填写，取值范围为 [0,200]。只有当 msg_type 为 200（自定义类型）时，此参数才有意义。
msg_body	String	消息内容。消息由客户端发送时：当 msg_type 为 1（文本类型）或 200（自定义类型），msg_body 为发送消息时传入的消息内容，开发者可直接阅读消息内容。当 msg_type 为 11、12、13、14，即消息为媒体类型时，msg_body 为 JSON 字符串。请使用 URLDecode 对此 JSON 字符串解码，并按照多媒体消息结构解析这个 JSON 字符串，进而获取消息中的各个字段数据。消息由服务端发送时，不论消息类型，本回调会直接透传发送消息时传入的内容。

建议您将部分参数转换为 Int 进行逻辑处理，相关字段包括 appid 和 nonce。

msg_body JSON 字符串解析结果参数说明

参数	类型	描述
md5	String	文件的 MD5 值。
file_name	String	文件名称。
file_size	String	文件大小，单位为字节（B）。
download_url	String	下载地址。
media_duration	String	音视频时长，单位为秒（s）。

回调示例

{
    "appid": "1",
    "event": "before_send_msg",
    "from_user_id": "sender",
    "conv_id": "receiver",
    "request_id": "3501907290370176",
    "msg_id": "1234232421343",
    "conv_type": 0,
    "timestamp": 1499676968,
    "msg_body": "msg_body",
    "msg_type": 1,
    "signature": "abc",
    "nonce": "321",
    "sub_msg_type": 0,
    "payload": "payload"
}

应答参数

参数	类型	描述
result	Int	您的业务后台应答的值，ZIM 会判断是否向发送该消息。 0：中立（不判断是否发送）。 1：发送。 2：静默推送。 3：不发送。其他：默认按中立处理。

基于您的应答以及 ZIM 内容审核服务开通与否，ZIM 会决定是否向消息接受端发送消息。ZIM 操作如下表所示：

有开通 ZIM 内容审核服务无开通 ZIM 内容审核服务

您的应答		ZIM 审核结果	ZIM 是否发送该消息	ZIM 返回给消息发送端的发送结果	消息接收端是否可接收该消息
值	含义	ZIM 审核结果	ZIM 是否发送该消息	ZIM 返回给消息发送端的发送结果	消息接收端是否可接收该消息
0	中立（不判断是否发送）	通过	发送	已发送	可接收
0	中立（不判断是否发送）	不通过	不发送	不发送	不可接收
1	发送	通过	发送	已发送	可接收
1	发送	不通过	发送	已发送	可接收
2	静默发送	通过	发送	已发送	不可接收
2	静默发送	不通过	不发送	不发送	不可接收
3	不发送	通过	不发送	不发送	不可接收
3	不发送	不通过	不发送	不发送	不可接收

您的应答		ZIM 是否发送该消息	ZIM 返回给消息发送端的发送结果	消息接收端是否可接收该消息
值	含义	ZIM 是否发送该消息	ZIM 返回给消息发送端的发送结果	消息接收端是否可接收该消息
0	中立（不判断是否发送）	发送	已发送	可接收
1	发送	发送	已发送	可接收
2	静默发送	发送	已发送	不可接收
3	不发送	不发送	不发送	不可接收

根据您的业务后台应答的值，消息发送方的客户端可能会收到以下错误码：

错误码	说明
111101	您的业务后台不同意发送此消息，ZIM 服务端拒绝发送此消息。

应答示例

{
    "result": 0
}

返回响应

收到回调后，如果您的服务器返回的 HTTP status code 为 2XX （例如 200），表示成功；返回其他，表示失败。

回调重试策略

如果 ZEGO 服务器在 2.5 秒内没有收到响应，判定为本次请求失败；随后会立即进行重试，若此次请求发起后 2.5 秒内仍未收到相应，则不再重试。

说明

当 ZEGO 客户端向您发起请求时，如果您的业务侧发生异常，则默认不发送消息。如需默认发送消息，请联系 ZEGO 技术支持。