Callback API
Overview
The data of "message status" and "message response" is called back to the business system of the enterprise, and the information can be used to perform actions such as statistics and reply to users.
Callback address
enterprises need to set callback addresses for receiving message status and message response. For more information, see callback settings .
Callback format
the request method is POST, the request body is JSON, and the data Type is "Content-Type: application/json"
multiple data records are returned at a time.
Security Mechanism
to be online. Currently, the callback does not contain authentication information, so do not set permission verification for the API that the developer receives the callback.
Response Mechanism
after receiving Engagelab callback, the developer service needs to respond within 3 seconds as follows:
received successfully: the HTTP response status code must return 200 and no response message is required.
Retry mechanism
to be online.
Request parameters
EngageLab request parameters to the callback address of the business system are as follows:
Field | Type | Option | Description |
---|---|---|---|
total | int | required | callback data volume |
rows | JSON Array | required | callback details |
The parameters in rows are as follows:
Field | Type | Option | Description |
---|---|---|---|
message_id | string | optional | the status of the message and the response. |
from | string | optional | The sender, message status, and returned when the upstream message is sent. |
to | string | optional | The recipient, the message status, and the upstream message. |
server | string | required | The product service to which the callback information belongs. The fixed value is whatsapp. |
channel | string | optional | The channel to which the status or response belongs. The fixed value whatsapp |
itime | int | required | the timestamp generated by the callback data. You can use the message_status field to obtain the request timestamp, sending timestamp, delivery timestamp, and read timestamp. |
custom_args | JSON Object | optional | Optional fields that are customized when the message is sent, and are returned as follows in the message status callback. |
status | JSON Object | optional | Message status field |
response | JSON Object | optional | message Response fields |
Message status-status
callback parameters
Field | Type | Option | Description |
---|---|---|---|
message_status | string | required | the status of the message. |
status_data | JSON Object | optional | detailed data in this state |
error_code | int | optional | the error code. If the error fails, the error code is returned. |
error_detail | JSON Object | optional | the error details. The error message is returned if the error fails. |
loss | JSON Object | optional | loss stage and loss source |
message_status
Value | Description | Definition |
---|---|---|
plan | scheduled sending | the number is within the "recipient number" to record the status of one planned sending target. |
target_valid | valid target | Pass validity verification 1. The number is determined to be legal by EngageLab. 2. The number is determined to be legal by the Meta WhatsApp service. |
sent | sent successfully | The error message returned after the EngageLab submitted the number to the Meta WhatsApp service. |
delivered | delivered successfully | The Meta WhatsApp Service confirms that the message has been delivered to the user. |
read | read | The Meta WhatsApp Service confirms that the user has read the message. |
target_invalid | the target is invalid. | 1. The number is judged invalid by the EngageLab. 2. The number is deemed invalid by Meta WhatsApp service. |
sent_failed | Failed to send | The error message returned after the number is submitted to the Meta WhatsApp service. |
delivered_failed | delivery failed | The number was submitted to the Meta WhatsApp service, but the Meta callback failed. |
delivered_timeout | Not delivered after timeout | The number was successfully submitted to the Meta WhatsApp service, but Meta did not call back within 5 minutes to inform whether the success/failure was successful or not, and it counted as a timeout. |
status_data
Field | Type | Option | Description |
---|---|---|---|
msg_time | int | required | the time when the message was sent. |
channel_message_id | String | required | the ID of the message returned by the WhatsApp. |
whatsapp_business_account_id | String | required | the ID of the WhatsApp business account to which the sending number belongs. |
timezone | String | required | organization time zone |
plan_user_total | int | optional | the total number of planned targets. This value is available only when message_status = plan. |
country_code | String | required | the country code of the recipient's mobile phone number. |
from_phone_id | String | required | ID of the sending number (from) |
conversation | JSON Object | optional | session Information |
pricing | JSON Object | optional | Price Information |
conversation
Field | Type | Option | Description |
---|---|---|---|
id | String | optional | the ID of the Meta conversation to which the message belongs. |
origin | JSON Object | optional | Indicates who initiated the conversation. Specified by type. Example: "origin":{"type":"business_initiated"}. Valid values: |
pricing
Field | Type | Option | Description |
---|---|---|---|
pricing_model | String | optional | fixed value: CBP |
category | String | optional | the dialog pricing category. Valid values: |
error_detail
Field | Type | Option | Description |
---|---|---|---|
message | String | required | cause |
loss
Field | Type | Option | Description |
---|---|---|---|
loss_step | int | required | loss phase 1: Plan target to effective target, that is, invalid target 2: Valid target ~ sending, that is, sending failed 3: Send to deliver. Delivery failed |
loss_source | String | required | the source of the loss. Valid values: engagelab:EngageLab WhatsApp loss caused by service verification meta: the error returned by Meta. |
Callback example
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // EngageLab's message id
"from": "", // sender
"to": "", // receiver
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // The timestamp generated by the message status, such as the time when the message was delivered
"custom_args": {}, // The parameters submitted when this message was created will be returned as-is when this callback is made
"status": {
// Respond with these fields on success
"message_status": "delivered" // message status
"status_data": { // custom
"msg_time": 1663432355, // The time when the message was sent, the time when the message was sent in the history record, that is, the time when the user calls the API to send the message - the call to the API is successful
"channel_message_id": "wamid.123321abcdefed==", // optional, the msgid returned by Meta
"whatsapp_business_account_id": "", //Send number from corresponding Whatsapp business account code
"timezone": "", //Organization time zone
"plan_user_total": 2007, //The total number of planned goals, this will only have a value when message_status=plan
"country_code": "CN", //The country/region code of the receiver's mobile phone number
"from_phone_id": "111111" // ID of the sending number (from)
"conversation": { // optional, conversation information
"id": "ebe2398cdaa37a0899ca5268b987b0c8",
"origin": {
"type": "business_initiated"
}
},
"pricing": { // optional, price information
"pricing_model": "CBP",
"category": "business_initiated"
}
},
// Return these fields in failure status (invalid destination, failed to send, failed to deliver, unread)
"error_code": 0, //error code
"error_detail": {
"message": "" //error reason
},
"loss": {
"loss_step": 1,
"loss_source": "aa"
}
}
}
]
}
Message Response
callback parameters
Field | Type | Option | Description |
---|---|---|---|
event | string | optional | response event |
response_data | JSON Object | optional | upstream reply/interaction message content |
event
Value | Description | Details |
---|---|---|
received | received user messages | the user sent a message directly. |
reply | the user replied to your message. | The enterprise sends a message to the user first, and the user chooses to reply to the message. |
order | user orders | - |
deleted | the user deleted his message. | The user deleted the message sent by himself (to be launched) |
response_data
Field | Type | Option | Description |
---|---|---|---|
channel_message_id | String | required | the ID of the message returned by the WhatsApp. |
whatsapp_business_account_id | String | required | the ID of the WhatsApp business account to which the sending number belongs. |
contact | JSON Object | optional | sender information |
message | JSON Object | required | message content |
contact
Field | Type | Option | Description |
---|---|---|---|
profile | JSON Object | optional | the information of the sender (customer). Currently, only the name field indicates the customer's name. Example: "profile": {"name": "bob"} |
wa_id | String | optional | the number of the sender. |
message
Field | Type | Option | Description |
---|---|---|---|
type | String | required | valid values: text, image, audio, video, document, sticker, button, interactive, unknown, and order. |
text | JSON Object | optional | For more information, see text object description |
image | JSON Object | optional | for more information, see image object description |
audio | JSON Object | optional | for more information, see audio object description |
video | JSON Object | optional | for more information, see video object description |
document | JSON Object | optional | for more information, see document object description |
sticker | JSON Object | optional | for more information, see sticker object description |
Callback example
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // the message id of Jiguang side
"from": "", // sender, that is, the customer's mobile phone number
"to": "", // Receiver, that is, the sender number of the developer
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // time stamp
"response": {
"event": "", // response event
"response_data": { // specific message content
"channel_message_id": "wamid.123321abcdefed==", // optional, the msgid returned by Meta
"whatsapp_business_account_id": "123321", //The developer's sending number to the corresponding Whatsapp business account code
"contact": { // optional, sender information
"profile": {
"name": "bob" // nickname of the sender
},
"wa_id": "8613800138000" // sender's number
},
"message": { // specific message content
"type": "text", // The type of the message, you can identify the specific message field according to this value, such as text, the content is the text field
"text": { // message content
"body": "here is the message content text"
}
}
}
}
}
]
}