Callback on message not sent yet

Description

After setting this callback, when a user sends a message to a one-on-one chat, group chat or room chat, In-app Chat will initiate a request to your business server, and you can perform real-time operations on the message through the response, such as:

Recording chat messages and intercepting requests for inappropriate speech;
Implementing black and white list functions to determine which messages can be sent normally.

Warning

The supported message types for this callback are text messages, image messages, file messages, audio messages, video messages, and custom messages. command messages and barrage messages are not supported.
This callback only supports messages sent via the client SDK. If messages are sent through the server, your business backend will not receive this callback.

Based on the value of the response from your business server, you can make one of the following four judgments on whether to send the message:

Value	Judgment	Whether to send the message	Result returned to the message sender	Whether the message recipient can receive the message
0	Neutral (not judged whether to send)	Send	Sent	Receivable
1	Send	Send	Sent	Receivable
2	Silently send	Send	Sent	Not receivable
3	Do not send	Do not send	Not sent	Not receivable

Callback request

Request method: POST/JSON
Note
The callback data format is JSON, and you need to perform UrlDecode decoding on it.
Request URL: Contact ZEGOCLOUD Technical Support to configure the corresponding callback endpoint.
Transmission protocol: HTTPS/HTTP (HTTPS is recommended.)

Request parameters

Common parameters	Type	Description
appid	String	A unique identifier for the App.
event	String	Callback event, the return value of this callback is `before_send_msg`.
nonce	String	Random number, used to calculate signature.
signature	String	The verification string, see Authenticating server-to-server callbacks for details.
timestamp	Int	The current server time in Unix timestamp format, in seconds, used to calculate the signature.
request_id	String	Request ID.
Business parameters	Type	Description
from_user_id	String	Message sender ID.
conv_id	String	Target session ID.
conv_type	Int	Target session type: 0: One-on-one chat. 1: Room chat. 2: Group chat.
msg_id	String	Message ID, which can be used to determine the uniqueness of the message.
payload	String	Extra field.
msg_type	Int	Message type： 1: Text. 10: Multi-item. 11: Images. 12: File. 13: Audio. 14: Video. 100: Combined. 200: Custom.
sub_msg_type	Int	The specific custom type. The value is filled in when the user sends a custom message, and the value range is [0,200]. This parameter is meaningful only when msg_type is 200 (custom type).
msg_body	String	Message content: When msg_type is 1 (text) or 200 (custom), msg_body contains the message content passed during the message sending, and developers can directly read the message content. When msg_type is one of the following types, msg_body is a JSON string. Please use URLDecode to decode the JSON string, and then parse it according to the corresponding structure to obtain the field data in the message: When msg_type is 11, 12, 13, or 14 (multimedia messages): msg_body JSON String Parsing Result Parameters - Multimedia messages. When msg_type is 10 (multi-item messages): msg_body JSON String Parsing Result Parameters - Multi-item messages. When msg_type is 100 (combined messages): msg_body JSON String Parsing Result Parameters - Combined messages.

Note

We recommend that you convert some parameters to Int for logical processing. The relevant fields include appid and nonce.

msg_body JSON String Parsing Result Parameters

Multimedia messages

Click to see details

Basic Parameters

Parameter	Type	Description
md5	String	MD5 value of the file.
file_name	String	Name of the file.
file_size	String	File size, in bytes (B).
download_url	String	Download URL.
media_duration	String	Duration of audio/video, in seconds (s).

Extended Parameters for Image Messages

For image messages, the following additional parameters are provided on top of the basic parameters.

Parameter	Type	Description
origin_image_width	Int	Width of the original image, in pixels (px).
origin_image_height	Int	Height of the original image, in pixels (px).
large_image_download_url	String	URL for downloading the large image.
large_image_width	Int	Width of the large image, in pixels (px).
large_image_height	Int	Height of the large image, in pixels (px).
thumbnail_download_url	String	URL for downloading the thumbnail image.
thumbnail_width	Int	Width of the thumbnail, in pixels (px).
thumbnail_height	Int	Height of the thumbnail, in pixels (px).

Extended Parameters for Video Messages

For video messages, the following additional parameters are provided on top of the basic parameters.

Parameter	Type	Description
video_first_frame_download_url	String	URL for downloading the first frame image of the video.
video_first_frame_width	Int	Width of the video first frame image, in pixels (px).
video_first_frame_height	Int	Height of the video first frame image, in pixels (px).

Multi-Item messages

Click to see details

Parameter	Type	Description
multi_msg	Array of Object	Array of items for the multi-item message.
└ msg_type	Int	Item type: 1: Text. 11: Image. 12: File. 13: Audio. 14: Video. 200: Custom message.
└ sub_msg_type	Int	This parameter is returned only when msg_type is 200.
└ callback_content	Object	Item content. When msg_type is 1 or 200, the message content can be read directly from this parameter. For items with msg_type 11, 12, 13, or 14, refer to the section on Multimedia Message Structure for details on the fields in the message.

Combined messages

Click to see details

Parameter	Type	Description
Title	String	Title.
Summary	String	Summary.

Callback example

{
    "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"
}

{
    "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"
}

Response parameters

Parameters	Type	Description
result	Int	The value of your business server response to determine whether In-app Chat server to send the message. 0: neutral (do not judge whether to send). 1: Send. 2: Push silently. 3: Do not send. Others: default to be neutral.
reason	String	When result is 3, you can fill in the reason for refusing to send the message here.

The message sender's client can obtain the reason why the message was rejected through the callback interface of the ZIM SDK. For detailed steps, please refer to Send and receive messages.

Note

When the ZEGOCLOUD client initiates a request to you, if an exception occurs on your business server, no message will be sent by default. If you want to send messages by default, contact ZEGOCLOUD Technical Support.

iOS	Android	macOS
messageSentStatusChanged	onMessageSentStatusChanged	messageSentStatusChanged

Windows	Web	React Native
onMessageSentStatusChanged	messageSentStatusChanged	messageSentStatusChanged

Flutter	Unity3D
onMessageSentStatusChanged	OnMessageSentStatusChanged

Sample response

{
    "result": 0
}

{
    "result": 0
}

Return response

Returning an HTTP status code of 2XX (e.g., 200) indicates success, and other responses indicate failure.

Retry mechanism

If the ZEGOCLOUD server does not receive a response, it will retry after 3 seconds. If the callback fails after the second retry, it will no longer be retried and an exception is judged.