Incoming Messages

Incoming messages received from a number are forwarded to you via a WhatsApp webhook.

WhatsApp sends a notification to SendZen, and SendZen forwards that notification to the API endpoint you’ve configured.

A WhatsApp webhook is a way for the WhatsApp Business Platform to send real-time data to an application when specific events occur, such as receiving a new message or a message status change.

Instead of an application constantly "polling" WhatsApp for updates, the platform automatically sends an HTTP notification to a URL, making the process more efficient. This allows for real-time automation, such as instantly storing incoming messages in a database or triggering automated replies.

How SendZen webhooks work

You create a webhook endpoint on your server (for example: https://api.yourapp.com/sendzen/webhook).

You register this URL inside app.sendzen.io in left hand side-bar → Webhooks.

You choose which events you want to receive (for example: incoming_message, delivery_status).

Whenever the event happens, SendZen sends an HTTP POST request with a JSON payload to your URL.

Your server returns a 2xx status code to confirm that the event was processed.

Setting up a webhook in SendZen

Go to Webhooks.

Click Add webhook.

Fill in:

Webhook URL: Your HTTPS endpoint.

Secret: Optional. We will use this to sign webhook requests.

Events: Select one or more events you want to subscribe to.

Click Save.

Request format

All webhooks are HTTP POST requests with a JSON body.

Method: POST

URL: Your configured webhook URL

Content type: application/json

Received Text Message with Show Security Notifications

{
    "object": "whatsapp_business_account",
    "entry": [
        {
            "id": "8856996819413533",
            "changes": [
                {
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "<PHONE_NUMBER>",
                            "phone_number_id": "27681414235104944"
                        },
                        "contacts": [
                            {
                                "profile": {
                                    "name": "<CONTACT_NAME>"
                                },
                                "wa_id": "<WA_ID>"
                            }
                        ],
                        "messages": [
                            {
                                "from": "<FROM_PHONE_NUMBER>",
                                "id": "ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
                                "identity": {
                                    "acknowledged": true,
                                    "created_timestamp": 1602532300000,
                                    "hash": "Sjvjlx8G6Z0="
                                },
                                "text": {
                                    "body": "Hi from new number 3601"
                                },
                                "timestamp": "1602532300",
                                "type": "text"
                            }
                        ]
                    },
                    "field": "messages"
                }
            ]
        }
    ]
}

Received Message with Reaction

{
    "object": "whatsapp_business_account",
    "entry": [
        {
            "id": "8856996819413533",
            "changes": [
                {
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "<PHONE_NUMBER>",
                            "phone_number_id": "27681414235104944"
                        },
                        "contacts": [
                            {
                                "profile": {
                                    "name": "<CONTACT_NAME>"
                                },
                                "wa_id": "<WA_ID>"
                            }
                        ],
                        "messages": [
                            {
                                "from": "sender_wa_id",
                                "id": "message_id",
                                "timestamp": "message_timestamp",
                                "type": "reaction",
                                "reaction": {
                                    "emoji": "<emoji>",
                                    "messsage_id": "<WAMID>"
                                }
                            }
                        ]
                    },
                    "field": "messages"
                }
            ]
        }
    ]
}

Received Media Message with Image

{
    "object": "whatsapp_business_account",
    "entry": [
        {
            "id": "8856996819413533",
            "changes": [
                {
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "16505553333",
                            "phone_number_id": "<PHONE_NUMBER_ID>"
                        },
                        "contacts": [
                            {
                                "profile": {
                                    "name": "<CONTACT_NAME>"
                                },
                                "wa_id": "<WA_ID>"
                            }
                        ],
                        "messages": [
                            {
                                "from": "<FROM_PHONE_NUMBER>",
                                "id": "wamid.id",
                                "timestamp": "<TIMESTAMP>",
                                "type": "image",
                                "image": {
                                    "caption": "This is a caption",
                                    "mime_type": "image/jpeg",
                                    "sha256": "81d3bd8a8db4868c9520ed47186e8b7c5789e61ff79f7f834be6950b808a90d3",
                                    "id": "2754859441498128"
                                }
                            }
                        ]
                    },
                    "field": "messages"
                }
            ]
        }
    ]
}

Received Callback from a Quick Reply Button Click

{
    "object": "whatsapp_business_account",
    "entry": [
        {
            "id": "8856996819413533",
            "changes": [
                {
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "16505553333",
                            "phone_number_id": "27681414235104944"
                        },
                        "contacts": [
                            {
                                "profile": {
                                    "name": "Kerry Fisher"
                                },
                                "wa_id": "16315551234"
                            }
                        ],
                        "messages": [
                            {
                                "context": {
                                    "from": "16505553333",
                                    "id": "wamid.gBGGFlCGg0cvAgkLFm4e9tICiTI"
                                },
                                "from": "16315551234",
                                "id": "wamid.ABGGFlCGg0cvAgo-sHWxBA2VFD_S",
                                "timestamp": "1603087229",
                                "type": "button",
                                "button": {
                                    "text": "No",
                                    "payload": "No-Button-Payload"
                                }
                            }
                        ]
                    },
                    "field": "messages"
                }
            ]
        }
    ]
}

View Complete Webhook documentation

How SendZen webhooks work#

Setting up a webhook in SendZen#

Request format#

Received Text Message with Show Security Notifications#

Received Message with Reaction#

Received Media Message with Image#