Receiving messages

Get every new WhatsApp message delivered to your own endpoint.

Tell the Inbox where to send new messages, and it calls that URL every time a customer writes to your number.

You need an HTTPS endpoint that accepts POST requests with a JSON body.

1

Register your webhook

curl -X POST $INBOX/api/v1/webhooks/waba/ \
  -H "Authorization: Token $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-endpoint.example.com/whatsapp", "on_incoming_message": true}'

The webhook belongs to the user whose token you use. Register it with your service's own token — see Authentication.

Reference: Create webhook

2

Send a message to your number

From your phone, send a WhatsApp message to your business number.

3

Read what arrives

Your endpoint receives the message in the standard WhatsApp webhook format. Trimmed down:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "changes": [
        {
          "value": {
            "contacts": [
              {
                "profile": { "name": "Anna" },
                "wa_id": "4915112345678",
                "user_id": "DE.13491208655302741918"
              }
            ],
            "messages": [
              {
                "from": "4915112345678",
                "from_user_id": "DE.13491208655302741918",
                "id": "wamid.ID",
                "timestamp": "1759150800",
                "type": "text",
                "text": { "body": "Hi" }
              }
            ]
          }
        }
      ]
    }
  ]
}

The message is in messages[], and who sent it is in contacts[]. The phone number fields can be missing when WhatsApp does not share the number; the BSUID (user_id, from_user_id) is always there. See Contacts.

Respond with 200 as soon as you have received the request, and do any slow work afterwards.

To answer the message, see Sending messages.