WhatsApp Webhooks

Webhooks or Callback can be used to receive data from Cunnekt for every new message and delivery statuses.
You can set Callback URL on Cunnekt’s API Setting page and start receiving your webhook data.

You’re advised to handle the webhook requests Asynchronously. Please read our Webhook endpoint implementation guideline.

Types of Webhooks:

  • Incoming Message Webhook
  • Delivery Report Webhook

Incoming Message Webhook Sample:

Generic Webhook Layout
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "WHATSAPP_BUSINESS_PHONE_NUMBER",
              "phone_number_id": "WHATSAPP_BUSINESS_PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "CUSTOMER_DISPLAY_NAME"
                },
                "wa_id": "CUSTOMER_PHONE_NUMBER",
                "user_id": "CUSTOMER_PHONE_NUMBER_SCOPED_ID"
              }
            ],
            "messages": [
              {
                "from": "CUSTOMER_PHONE_NUMBER",
                "from_user_id": "CUSTOMER_PHONE_NUMBER_SCOPED_ID",
                "id": "UNIQUE_MESSAGE_ID",
                "timestamp": "1785004197",
                "text": {
                  "body": "Hi"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}'

Delivery Report Webhook Sample

Generic Webhook Layout
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "WHATSAPP_BUSINESS_PHONE_NUMBER",
              "phone_number_id": "WHATSAPP_BUSINESS_PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "wa_id": "CUSTOMER_PHONE_NUMBER",
                "user_id": "CUSTOMER_PHONE_NUMBER_SCOPED_ID"
              }
            ],
            "statuses": [
              {
                "id": "UNIQUE_MESSAGE_ID",
                "status": "read/delivered/failed",
                "timestamp": "1785004200",
                "recipient_id": "CUSTOMER_PHONE_NUMBER",
                "recipient_user_id": "CUSTOMER_PHONE_NUMBER_SCOPED_ID",
                "conversation": {
                  "id": "CONVERSATION_ID",
                  "origin": {
                    "type": "utility"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "category": "utility",
                  "type": "regular"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}'

Webhook Parameters

Parameter Description Value Example
WHATSAPP_BUSINESS_PHONE_NUMBER Business Number receiving the Webhook 919999999999
WHATSAPP_BUSINESS_PHONE_NUMBER_ID Business Phone Number Identifier 544988974645465
CUSTOMER_DISPLAY_NAME Display Name set by the customer on WhatsApp Vivek 🙂
CUSTOMER_PHONE_NUMBER Mobile Phone number of the Customer 918888888888
CUSTOMER_PHONE_NUMBER_SCOPED_ID IN.1099999541555562 text/plain
UNIQUE_MESSAGE_ID Unique identifier of the message received or the Message for which delivery report has been sent. wamid.asdasdDSH2323knasdhasdnfhjUGAHSD233A==