Callback API

Last updated: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"
}

        
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 (described as username below) and callback secret (described as secret below) 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, and 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

Please translate the above content from Simplified Chinese to English and return it in Markdown code block format.

Response Mechanism

After the developer service receives the callback of the Engagelab, it needs 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 content

Callback method: POST content-Type:application/json

Message status change

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 of the Aurora side "from":"", // sender "to":"", // Receiver, registrationID "server": "AppPush", "channel": "FCM", "custom_args": {}, // The parameters submitted at the creation of this message, which will be returned as is in this callback "itime":1640707579, // the timestamp of when the message status changed, such as when the message was delivered "status": { // Respond to these fields on success "message_status": "delivered", // message status "status_data": { // custom "channel_message_id": "wamid.123321abcdefed==" // optional, the msgid of the third-party channel }, // respond to these fields on failure "error_code":0, // error_code - corresponds to the lifecycle error code "error_detail":{ "message":""// reason for error }, "loss":{ "loss_source": "vivo", "loss_step":1} // stage and source of the loss } }] }
          {
    "total": 1,
    "rows": [{
      "message_id": "1666165485030094861", // message id of the Aurora side
    "from":"", // sender
    "to":"", // Receiver, registrationID
      "server": "AppPush",
      "channel": "FCM",
      "custom_args": {}, // The parameters submitted at the creation of this message, which will be returned as is in this callback
    "itime":1640707579, // the timestamp of when the message status changed, such as when the message was delivered
    
      "status": { 
      // Respond to these fields on success
      "message_status": "delivered", // message status    
      "status_data": { // custom
        "channel_message_id": "wamid.123321abcdefed==" // optional, the msgid of the third-party channel
      }, 

      // respond to these fields on failure
      "error_code":0, // error_code - corresponds to the lifecycle error code
      "error_detail":{
        "message":""// reason for error
     }, 
      "loss":{ "loss_source": "vivo", "loss_step":1} // stage and source of the loss
      }
  }]
}

        
This code block in the floating window

Parameter description

Valid values:

Value meaning
target_valid effective target
sent sent successfully
delivered delivered successfully
click user Click
target_invalid invalid target
sent_failed failed to send
delivered_failed delivery failed

**Note: **1. There may be duplication of clicks and deliveries in some channels, and developers can remove duplicates by themselves. 2. The delivery quantity and impression quantity will not be adjusted back 5 days after the delivery is successful.

Loss phase
1: Plan objectives-effective objectives
2: Number of valid targets sent
3: Number of deliveries-number of deliveries
4: delivery quantity-number of clicks

在文档中心打开
icon
Contact Sales