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"
}
Response Body:
12345678
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
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)
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
or204
, and no response message is required. - Failed to receive: The HTTP response status code must return
5XX
or4XX
and a response message. The format is as follows:
{
"code": 2002,
"message": "error"
}
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
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
}
}
]
}
Parameter Description
Valid values:
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 objectives → Effective objectives
- Number of valid targets sent
- Number of deliveries → Number of delivered messages
- Delivery quantity → Number of clicks