Callback API

Overview

The message status data is called back to the business system of the enterprise, and statistical analysis can be performed based on the information.

Callback Address

The enterprise needs to set the callback address for receiving the message status change. Currently, there is no web interface. Please contact Engagelab technical personnel to set the callback address.

Callback Address Validity Verification

When configuring the callback address in the Push backend management under Application Settings, a POST request will be sent with a randomly generated 8-character string as the echostr request body parameter. You need to return the value of echostr in the Response Body, following the format below:

Request Body:

{ "echostr": "12345678" }

          {
    "echostr": "12345678"
}

This code block in the floating window

Response Body:

12345678

12345678

This code block in the floating window

Security Mechanism

Used for client authentication, optional.

To ensure that the source of the messages is Engagelab, you can choose to authenticate the source of the POST data. Alternatively, you can directly parse the POST data without authentication.

The authentication method is as follows:

Configure a callback username (username) and callback secret (secret) in the Engagelab console for the callback address.

Retrieve X-CALLBACK-ID from the request header, as shown in the example below:

X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

          X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

This code block in the floating window

Here:

timestamp is the timestamp of the callback message (in standard format),
nonce is a random number,
signature is the signature information.

The signature method is as follows:

signature=HMAC-SHA256(secret, timestamp+nonce+username)

          signature=HMAC-SHA256(secret, timestamp+nonce+username)

This code block in the floating window

Response Mechanism

After the developer service receives the callback from Engagelab, it needs to respond within 3 seconds according to the following requirements:

Received successfully: The HTTP response status code must return 200 or 204, and no response message is required.
Failed to receive: The HTTP response status code must return 5XX or 4XX and a response message. The format is as follows:

{ "code": 2002, "message": "error" }

          {
    "code": 2002,
    "message": "error"
}

This code block in the floating window

Field	Type	Required/Optional	Description
`code`	int	Optional	Error codes
`message`	string	Optional	Error details

Callback Field Explanation

Message Body

Field Name	Type	Required/Optional	Description
`total`	int	Required	The number of messages included in this callback
`rows`	array	Required	A list of detailed information about the message status change, containing the fields below:

`rows` Array Fields

Field Name	Type	Required/Optional	Description
`message_id`	string	Required	Unique identifier of the message
`from`	string	Optional	Sender, default is appkey
`to`	string	Optional	Receiver's identifier (e.g., `registrationID`)
`server`	string	Required	The message service name, possible values: `AppPush`, `WebPush`
`channel`	string	Required	Message channel, possible values: `EngageLab`, `HuaWei`, `XiaoMi`, `MeiZu`, `OPPO`, `VIVO`, `HONOR`, `FCM`, `APNs`
`custom_args`	object	Optional	Custom parameters submitted during message creation, returned as is
`itime`	int	Required	The actual timestamp when the message status occurred, can be used with `message_status` to get the timestamp of each message status
`status`	object	Required	Message status information, containing the fields below:

`status` Object Fields

Field Name	Type	Required/Optional	Description
`message_status`	string	Required	Message status, possible values: `target_valid`, `sent`, `delivered`, `click`, `target_invalid`, `sent_failed`, `delivered_failed`, `no_click`
`status_data`	object	Optional	Custom status data, containing the fields below:
`channel_message_id`	string	Optional	Message ID from third-party channels
`ntf_msg`	int	Required	Message type, possible values: `1: Notification`, `2: Custom Message`, `5: iOS Real-Time Activity`, `6: iOS VOIP Message`, `7: In-App Message`
`platform`	string	Required	Push platform, possible values: `a: Android`, `i: iOS`, `b: Web`
`uid`	int	Required	UID of the recipient of the push message
`app_version`	string	Required	SDK-integrated app version, obtained through SDK reporting data
`channel`	string	Required	SDK-integrated app channel, obtained through SDK reporting data
`msg_time`	int	Required	Message delivery time, the time when the API request to send the message is successful
`time_zone`	string	Required	The time zone of the organization
`loss_valid_type`	int	Optional	This field has no actual significance and does not need to be processed
`plan_user_total`	int	Optional	This field has no actual significance and does not need to be processed
`callback_type`	int	Optional	This field has no actual significance and does not need to be processed
`error_code`	int	Optional	Error code, provided only in case of failure
`error_detail`	object	Optional	Detailed error information, provided only in case of failure, containing the fields below:
`message`	string	Optional	Describes the detailed error reason, only applicable for FCM channel
`loss`	object	Optional	Loss information, containing the fields below:
`loss_source`	string	Optional	Source of loss, possible values: `EngageLab`, `HuaWei`, `XiaoMi`, `MeiZu`, `OPPO`, `VIVO`, `HONOR`, `FCM`, `APNs`
`loss_step`	int	Optional	Loss stage, possible values: `1: Plan Target → Valid Target`, `2: Valid Target → Sent Quantity`, `3: Sent Quantity → Delivered Quantity`, `4: Delivered Quantity → Click Quantity`

Message Status Values

Status Value	Meaning	Description
`target_valid`	Valid Target	Considered valid if active in the past 365 days
`sent`	Sent Successfully	Successfully sent to the server
`delivered`	Delivered Successfully	For `EngageLab`, `XiaoMi`, `OPPO`, `VIVO` — delivered based on real callback; For `FCM` and `APNs` — delivered when successfully sent to the vendor's server; For `HuaWei`, `MeiZu`, `HONOR`, if vendor callback is not configured, it's delivered when sent to the vendor's server; if configured, it's delivered based on vendor's real callback
`click`	User Clicked	User clicked as reported by the SDK
`target_invalid`	Invalid Target	Considered invalid based on loss stage 1 as defined in the loss table
`sent_failed`	Sent Failed	Considered invalid based on loss stage 2 as defined in the loss table
`delivered_failed`	Delivered Failed	Considered failed based on loss stage 3 as defined in the loss table
`no_click`	Click Failed	Considered failed based on loss stage 4 as defined in the loss table, applies only to in-app messages

Callback Content

Callback method: POST
Content-Type: application/json

Example

Request Header

POST /developer_define_url HTTP/1.1 Content-Type: application/json

          POST /developer_define_url HTTP/1.1
Content-Type: application/json

This code block in the floating window

Request Body

{ "total": 1, "rows": [ { "message_id": "1666165485030094861", // Message ID on EngageLab's side "from": "", // Sender "to": "", // Receiver, registrationID "server": "AppPush", "channel": "FCM", "custom_args": {}, // The parameters submitted when creating this message "itime": 1640707579, // e.g., the time when the message was delivered "status": { // Fields returned on success "message_status": "delivered", // Message status "status_data": { // Custom data "channel_message_id": "wamid.123321abcdefed==", // Optional, third-party channel's message ID "ntf_msg": 1, // Message type "platform": "a", // Push platform "uid": 100, // User ID for the push notification "app_version": "", // App version integrated with SDK "channel": "", // App channel integrated with SDK "msg_time": 1640707579, // Message delivery time "time_zone": "+8", // Organization's time zone "loss_valid_type": 0, // This field is not important "plan_user_total": 0, // This field is not important "callback_type": 0 // This field is not important }, // Fields returned on failure "error_code": 0, // Error code - corresponding to lifecycle error code "error_detail": { "message": "" // Error reason }, "loss": { "loss_source": "vivo", "loss_step": 1 } // Loss phase and loss source } } ] }

          {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861", // Message ID on EngageLab's side
            "from": "", // Sender
            "to": "", // Receiver, registrationID
            "server": "AppPush",
            "channel": "FCM",
            "custom_args": {}, // The parameters submitted when creating this message
            "itime": 1640707579, // e.g., the time when the message was delivered
            "status": {
                // Fields returned on success
                "message_status": "delivered", // Message status    
                "status_data": { // Custom data
                    "channel_message_id": "wamid.123321abcdefed==", // Optional, third-party channel's message ID
                    "ntf_msg": 1, // Message type
                    "platform": "a", // Push platform
                    "uid": 100, // User ID for the push notification    
                    "app_version": "", // App version integrated with SDK 
                    "channel": "", // App channel integrated with SDK   
                    "msg_time": 1640707579, // Message delivery time
                    "time_zone": "+8", // Organization's time zone 
                    "loss_valid_type": 0, // This field is not important
                    "plan_user_total": 0, // This field is not important 
                    "callback_type": 0 // This field is not important
                },
                // Fields returned on failure
                "error_code": 0, // Error code - corresponding to lifecycle error code
                "error_detail": {
                    "message": "" // Error reason
                },
                "loss": {
                    "loss_source": "vivo",
                    "loss_step": 1
                } // Loss phase and loss source
            }
        }
    ]
}

This code block in the floating window

Parameter Description

Value	Meaning
`target_valid`	Effective target
`sent`	Sent successfully
`delivered`	Delivered successfully
`click`	User clicked
`target_invalid`	Invalid target
`sent_failed`	Failed to send
`delivered_failed`	Delivery failed

Loss Phase

Plan targets → Valid targets
Valid targets → Sent
Sent → Delivered
Delivered → Clicks

Note:
1. Clicks and deliveries on some channels may be duplicated, you can perform deduplication by yourselves.
2. The delivery quantity and display quantity will not be adjusted back 5 days after the delivery is successful.

Callback API

Overview

Callback Address

Callback Address Validity Verification

Security Mechanism

Response Mechanism

Callback Field Explanation

Message Body

rows Array Fields

status Object Fields

Message Status Values

Callback Content

Example

Request Header

Request Body

Parameter Description

Loss Phase

`rows` Array Fields

`status` Object Fields