Callback API

Last updated:2023-03-09

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:
  • business_initiated: Indicates that the conversation starts when the Enterprise sends the first message to the customer. This applies to any time more than 24 hours from the last customer message.
  • customer_initiated: Indicates that the conversation starts with the enterprise replying to the customer message. This applies only when the business response is within 24 hours from the last customer message.
  • referral_conversion : Indicates that the conversation originates from a free entrance point . These conversations are always initiated by customers.
  • pricing
    Field Type Option Description
    pricing_model String optional fixed value: CBP
    category String optional the dialog pricing category. Valid values:
  • business_initiated: Merchant conversation.
  • customer_initiated: User conversation.
  • referral_conversion: Free access point conversation.
  • 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" } } } ] }
              {
        "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"
                    }
                }
            }
        ]
    }
    
            
    This code block in the floating window

    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" } } } } } ] }
              {
        "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"
                            }
                        }
                    }
                }
            }
        ]
    }
    
            
    This code block in the floating window
    在文档中心打开
    icon
    Contact Sales