Webhooks

Overview

This section explains how to set up webhook endpoints to receive:

• Inbound Messages (text, media, interactive, etc.)

• Optional Message Status Updates (e.g., delivered, read, failed)

Having both webhooks enabled ensures you can process incoming customer messages and track the lifecycle of messages you send.

Inbound Message Webhooks

Configuring the Inbound Webhook

1

Navigate to Settings

In your application or developer dashboard, set the Inbound Webhook URL (e.g., https://example.com/webhook/whatsapp/inbound).

2

Receive Webhooks

All incoming WhatsApp messages (new messages and replies) will trigger a POST to your inbound webhook URL.

Supported Inbound Message Types

Inbound messages can contain various content types:

• Text

• Media (image, video, audio, document)

• Sticker

• Location

• Contact

• Interactive

  • List response

  • Button response

Check the type field in the webhook payload to determine what the user has sent.

Sample Webhooks Incoming Messages

Text

{
     "messageId": "c94ced08-5f40-46b7-a88d-7d4fbe113fe9",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "TEXT",
     "text": "Text Content"
}

Image

{
     "messageId": "c94ced08-5f40-46b7-a88d-7d4fbe113fe9",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "IMAGE",
     "image": {
          "caption": null,
          "url": "HTTPS URL"
     }
}

Video

{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "VIDEO",
     "video": {
          "caption": null,
          "url": "HTTPS URL"
     }
}

Audio

{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "AUDIO",
     "audio": {
          "caption": null,
          "url": "HTTPS URL"
     }
}

Document

{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "DOCUMENT",
     "document": {
          "caption": null,
          "url": "HTTPS URL"
     }
}

Location

{
     "to": "",
     "from": "",
     "type": "LOCATION",
     "location": {
          "name": "",
          "address": "Kiambu Road",
          "latitude": "",
          "longitude": ""
     },
     "messageId": "WA_MESSAGE_ID",
     "profileName": "CUSTOMER_NAME"
}

Contact

{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "CONTACTS",
     "contacts": [
          {
               "addresses": null,
               "birthday": null,
               "emails": null,
               "name": {
                    "suffix": null,
                    "prefix": null,
                    "formatted_name": "",
                    "first_name": "",
                    "last_name": "",
                    "middle_name": null
               },
               "org": null,
               "phones": [
                    {
                         "phone": "PHONE NUMBER",
                         "type": "MOBILE",
                         "wa_id": "PHONE NUMBER"
                    }
               ],
               "urls": null
          }
     ]
}

Sticker

{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "STICKER",
     "sticker": {
          "caption": null,
          "url": "HTTPS URL"
     }
}

Interactive List

{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "INTERACTIVE",
     "interactive": {
          "type": "list_reply",
          "list_reply": {
               "id": "NAIROBI_WATER",
               "title": "Nairobi Water"
          }
     }
}

Interactive Buttons

{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "INTERACTIVE",
     "interactive": {
          "type": "button_reply",
          "button_reply": {
               "id": "1",
               "title": "YES"
          }
     }
}

Message Status Callbacks

What Are Status Callbacks?

When you send a message or manage a template, our service can notify your application of changes via HTTP POST requests to a separate webhook URL. There are two main categories:

• Message Delivery Status: Track whether your outbound message was sent, delivered, read, or failed.

• Template Status: Track changes in your message template approval status (e.g., approved, rejected, paused).

Configuring Status Callbacks

Navigate to Settings: Set the Status Callback URL (e.g.,https://example.com/webhook/whatsapp/status).

Possible status values include:

• SENT

• DELIVERED

• READ

• DELETED

• FAILED

Sample JSON: Message Delivery Status

{
     "event": "MESSAGE_STATUS",
     "messageStatus": {
          "waId": "",
          "messageId": "",
          "conversationId": "",
          "status": "DELIVERED",
          "statusDesc": ""
     }
}

For outbound messages, the messageId corresponds to the ID included in the request

Template Status Updates

We also send callbacks when your WhatsApp message templates change status. Possible status values include:

• APPROVED: The template is approved and ready for use.

• REJECTED: The template has been denied—check for policy violations.

• PAUSED: The template is temporarily suspended, often pending manual review.

statusDescription will contain the reason why a template has been rejected or paused.

Sample JSON: Template Status Update

{
     "event": "TEMPLATE_STATUS",
     "templateStatus": {
          "status": "APPROVED",
          "templateId": "",
          "templateName": "",
          "statusDescription": ""
     }
}