Webhook

Push WhatsApp business events to the configured webhook URL (currently supports status callbacks and template button click callbacks).

• URL: webhook_url
• Method: POST
• Content-Type: application/json

Status Callback

Delivery status for messages sent via WhatsApp API.

Response Parameters

Body parameters:

Parameter	Type	Description
statuses	array[status JsonObject]	Status list
business_phone	String	Business phone
messaging_product	String	Message type, fixed value "whatsapp"

• status object parameters:

Parameter	Type	Description
conversation	JsonObject	Conversation info
errors	array[error JsonObject]	Error info
recipient_id	String	Recipient WhatsApp ID
timestamp	String	Callback timestamp
status	String	Message status: sent, delivered, read, failed, deleted
id	String	Message ID

• conversation object parameters:

Parameter	Type	Description
id	String	Conversation ID
expiration_timestamp	String	Conversation expiration timestamp
origin	JsonObject	Conversation type info

• origin object parameters:

Parameter	Type	Description
type	String	Conversation type

• cost object parameters:

Parameter	Type	Description
currency	String	Currency
foreign_price	number	Customer price (customer currency)
cdr_type	Integer	cdr type: 1 message, 4 marketing session, 5 notification session, 6 verification session, 7 service session, 8 free session, 9 international verification, 10 MM Lite Api
message_id	String	WA message id
direction	Integer	Direction: 1 downlink, 2 uplink

• error object parameters:

Parameter	Type	Description
code	Integer	Error code
title	String	Error message

Response Examples

Message Sent

{
  "statuses": [
    {
      "id": "wamid.edcf691d49c04b939c8e3331f07f9cd1",
      "status": "sent",
      "timestamp": "1660019986",
      "recipient_id": "86176xxxx0819",
      "conversation": {
        "id": "72569257438b471cae074da84bed1b83",
        "expiration_timestamp": "1660106400",
        "origin": {
          "type": "business_initiated"
        }
      },
      "costs": [
        {
          "cdr_type": 5,
          "currency": "CNY",
          "direction": 1,
          "foreign_price": 0.1713
        }
      ]
    }
  ]
}

Message Delivered

{
  "statuses": [
    {
      "id": "wamid.edcf691d49c04b939c8e3331f07f9cd1",
      "status": "delivered",
      "timestamp": "1660019987",
      "recipient_id": "86176xxxx0819",
      "conversation": {
        "id": "72569257438b471cae074da84bed1b83",
        "origin": {
          "type": "business_initiated"
        }
      }
    }
  ]
}

Message Read

{
  "statuses": [
    {
      "id": "wamid.edcf691d49c04b939c8e3331f07f9cd1",
      "status": "read",
      "timestamp": "1660019990",
      "recipient_id": "86176xxxx0819"
    }
  ]
}

Message Failed

{
  "statuses": [
    {
      "errors": [
        {
          "code": 470,
          "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider."
        }
      ],
      "id": "ID",
      "recipient_id": "WHATSAPP_ID",
      "status": "failed",
      "timestamp": "TIMESTAMP"
    }
  ]
}

Message Deleted

{
  "statuses": [
    {
      "id": "ID",
      "recipient_id": "WHATSAPP_ID",
      "status": "deleted",
      "timestamp": "TIMESTAMP",
      "type": "message",
      "message": {
        "recipient_id": "WHATSAPP_ID"
      }
    }
  ]
}

Template Button Click Callback

Button click callbacks for template messages (only quick-reply buttons are supported).

Response Parameters

Body parameters:

Parameter	Type	Description
contacts	array[contact JsonObject]	Contact info
messages	array[message JsonObject]	Callback info
business_phone	String	Business phone
messaging_product	String	Message type, fixed value "whatsapp"

• contact object parameters:

Parameter	Type	Description
profile	object	Contact profile
wa_id	String	WhatsApp ID

• profile object parameters:

Parameter	Type	Description
name	String	Name

• message object parameters:

Parameter	Type	Description
context	JsonObject	Context
from	String	Sender WhatsApp ID
id	String	Message ID
timestamp	String	Timestamp
type	String	Message type (button)
button	JsonObject	Button info

• context object parameters:

Parameter	Type	Description
from	String	Sender WhatsApp ID
id	String	Original message ID

• button object parameters:

Parameter	Type	Description
text	String	Button text
payload	String	Button payload

Response Example

{
  "contacts": [
    {
      "profile": {
        "name": "Uxxxxx"
      },
      "wa_id": "86186xxxxx"
    }
  ],
  "messages": [
    {
      "context": {
        "from": "86186xxxxx",
        "id": "wamid.HBgNNjg2xxxxx"
      },
      "from": "86186xxxxx",
      "id": "wamid.HBgNNjg2xxxxx",
      "timestamp": "1669686240",
      "type": "button",
      "button": {
        "payload": "Quick reply button payload",
        "text": "Quick reply button text"
      }
    }
  ],
  "business_phone": "86158xxxxx",
  "messaging_product": "whatsapp"
}