Receiving Messages via Webhook

Webhooks is a mechanism which enables applications to communicate with each other programmatically. It allows you to send real-time data from one application to another whenever a given event occurs.

Whenever a specific event occurs, the system sees the event, collects the data, and immediately sends a notification (user-defined HTTP callbacks) to the webhook URL specified.

There are 2 main objects you can receive via webhooks:

message: Used to notify you when you get a new message and what is in the new message.

statuses: Used to notify you when there's a status change in a message you sent.

Note: Only use asynchronous handling of webhooks.
Do not process incoming messages and notifications in the webhook handler. Acknowledge immediately after receiving the webhook (with status 200), then you can process the data.

Recommendations

For stable functioning of webhook it is recommended to make the webhook perform as fast as possible. That means:

Respond with status 200 immediately after receiving a notification (the callbacks payload should NOT be processed before responding, but ack first then process).

Sending one message as opposed to getting one causes up to three callback notifications (sent, delivered and read). It means that the speed of processing concurrent requests should increase in accordance with the load of the number. In addition to a direct increase in the speed of processing notifications, we recommend making your webhook process as many parallel requests as possible. Otherwise, this can lead to the occurrence and overflow of the message queue.

Receiving notifications for incoming messages

When a customer sends you a message, the system will send an HTTP POST request notification to the webhook URL with the details that are described below:

Status callbacks

Sent

{
    "event": "whatsapp:message:status",
    "payload": {
        "messageId": "85d46272-9af0-4943-a193-6f83ce6d23a0:1",
        "timestamp": "1776319153",
        "status": "SENT"
    }
}

Delivered

{
    "event": "whatsapp:message:status",
    "payload": {
        "messageId": "85d46272-9af0-4943-a193-6f83ce6d23a0:1",
        "timestamp": "1776319153",
        "status": "DELIVERED"
    }
}

Read

{
    "event": "whatsapp:message:status",
    "payload": {
        "messageId": "65cb01f2-7217-442b-955c-b69c1bfda496:1",
        "timestamp": "1776319326",
        "status": "READ"
    }
}

Played

{
  "event": "whatsapp:message:status",
  "payload": {
      "messageId": "71022569-cc29-449a-be71-71f04f2b50c3:1",
      "timestamp": "1776503413",
      "status": "PLAYED"
  }
}

Failed

{
    "event": "whatsapp:message:status",
    "payload": {
        "messageId": "5cdf0c66-49b9-4c7c-96c3-aa4dc141a8c7:1",
        "timestamp": "1776319418",
        "status": "FAILED",
        "errors": [
            {
                "code": 131026,
                "title": "Message undeliverable",
                "message": "Message undeliverable",
                "error_data": {
                    "details": "Message Undeliverable."
                }
            }
        ]
    }
}

Messages

Text Message

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "8c935392-6564-4ea9-ac45-9625ae38ee48",
        "type": "text",
        "text": {
            "body": "HELLO"
        },
        "timestamp": "1776316612"
    }
}

Image

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "139427cc-255f-48eb-ae7c-e3ef238e350e",
        "type": "image",
        "image": {
            "mime_type": "image/jpeg",
            "link": "<LINK>"
        },
        "timestamp": "1776316271"
    }
}

Video

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "e4eeacd3-04fd-40ac-b6d4-a29f9f0978d3",
        "type": "video",
        "video": {
            "mime_type": "video/mp4",
            "link": "<LINK>"
        },
        "timestamp": "1776317634"
    }
}

Audio

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "8353993b-69a6-4616-ab4e-bef35e01e060",
        "type": "audio",
        "audio": {
            "mime_type": "audio/mpeg",
            "voice": false,
            "link": "<LINK>"
        },
        "timestamp": "1776313506"
    }
}

Audio [Voice]

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "5bf16420-932d-4e7c-95e3-83d51e068c0f",
        "type": "audio",
        "audio": {
            "mime_type": "audio/ogg; codecs=opus",
            "voice": true,
            "link": "<LINK>"
        },
        "timestamp": "1776313787"
    }
}

Document

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "f902b855-f1d2-4f6e-a791-49ba9bbd2444",
        "type": "document",
        "document": {
            "filename": "Document.pdf",
            "mime_type": "application/pdf",
            "link": "<LINK>"
        },
        "timestamp": "1776315862"
    }
}

Location

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "5277a27f-e211-404a-9a6f-528836cb4c78",
        "type": "location",
        "location": {
            "latitude": 14.4587639,
            "longitude": 79.999542
        },
        "timestamp": "1776316364"
    }
}

Contact

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "2c708ac0-8939-44d0-aa91-fcb4af2f1658",
        "type": "contacts",
        "contacts": [
            {
                "name": {
                    "first_name": "JHON",
                    "last_name": "LESNER",
                    "formatted_name": "JOHN LESNER"
                },
                "phones": [
                    {
                        "phone": "+91 XXXXX X7984",
                        "wa_id": "91XXXXXX7984",
                        "type": "Phone"
                    }
                ]
            }
        ],
        "timestamp": "1776315725"
    }
}

Reaction [Receiving]

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "b70622ea-d24b-4bed-ad22-51699bf5c845",
        "type": "reaction",
        "reaction": {
            "emoji": "😂",
            "messageId": "42417ece-8334-4a09-8e14-cbb1dcb8d301"
        },
        "timestamp": "1776319581"
    }
}

Reaction [Removed by end User]

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "5fab99ef-aff6-4c8e-a0bb-e50651c6206c",
        "type": "reaction",
        "reaction": {
            "messageId": "42417ece-8334-4a09-8e14-cbb1dcb8d301"
        },
        "timestamp": "1776319635"
    }
}

Sticker

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "8d9c6912-7a01-4df1-a5d3-1df27868f8d8",
        "type": "sticker",
        "sticker": {
            "mime_type": "image/webp",
            "animated": true,
            "link": "<LINK>"
        },
        "timestamp": "1776316547"
    }
}

Button

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "41a515bf-7317-4584-96bf-780eaa52de03",
        "type": "button",
        "button": {
            "payload": "learn-blue-echeveria",
            "text": "Learn more"
        },
        "timestamp": "1776318794",
        "context": {
            "messageId": "d856fe04-82de-4418-924a-ec2d7e163bf1:1"
        }
    }

Interactive Button Reply

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "52c9142d-cd70-4980-9d15-81cd3433e606",
        "type": "interactive",
        "interactive": {
            "type": "button_reply",
            "button_reply": {
                "title": "See available sizes"
            }
        },
        "timestamp": "1776316042",
        "context": {
            "messageId": "ba5a2f4b-0d38-423a-8256-a73249cfe50f:1"
        }
    }
}

Interactive List Reply

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "6a3f4b61-b42c-49b1-8938-cd85843072d8",
        "type": "interactive",
        "interactive": {
            "type": "list_reply",
            "list_reply": {
                "title": "Priority Mail Express",
                "description": "Next Day to 2 Days"
            }
        },
        "timestamp": "1776318343",
        "context": {
            "messageId": "84aedaa5-20de-49f3-bbc6-96611fc72777:1"
        }
    }
}

Order Message

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "46ea1f12-1f4e-4353-810d-d104334e51cb",
        "type": "order",
        "order": {
            "catalog_id": "1246197399818456",
            "text": "",
            "product_items": [
                {
                    "product_retailer_id": "fmfsj2759e",
                    "quantity": 1,
                    "item_price": 0.09,
                    "currency": "INR"
                }
            ]
        },
        "timestamp": "1776319178"
    }
}

Unsupported Message

{
    "event": "whatsapp:message:received",
    "payload": {
        "from": "+91XXXXXX4719",
        "messageId": "fa36c309-97a8-421d-8a1d-6a24d941005e",
        "type": "unsupported",
        "unsupported": {
            "type": "poll_creation"
        },
        "timestamp": "1776319248"
    }
}

Receiving Messages via Webhook

Recommendations#

Receiving notifications for incoming messages#

Status callbacks#

Sent#

Delivered#

Read#

Played#

Failed#

Messages#

Text Message#

Image#

Video#

Audio#

Audio [Voice]#

Document#

Location#

Contact#

Reaction [Receiving]#

Reaction [Removed by end User]#

Sticker#

Button#

Interactive Button Reply#

Interactive List Reply#

Order Message#

Unsupported Message#