logo

Callback API

อัพเดทล่าสุด :2023-02-27

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

        
โค้ดนี้โชว์เป็นหน้าต่างลอย

Response Body:

12345678
          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
          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)
          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 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"
}

        
โค้ดนี้โชว์เป็นหน้าต่างลอย
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

        
โค้ดนี้โชว์เป็นหน้าต่างลอย
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
            }
        }
    ]
}

        
โค้ดนี้โชว์เป็นหน้าต่างลอย

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

  1. Plan objectives → Effective objectives
  2. Number of valid targets sent
  3. Number of deliveries → Number of delivered messages
  4. Delivery quantity → Number of clicks
在文档中心打开
icon
ติดต่อฝ่ายขาย