Add your URL on the Webhook page. We send a POST request (form data) to it for every message a customer sends you and every bot reply. Enable "Also send messages we send" to also receive messages sent from Inbox, Chat History, API or the WhatsApp phone (as from = bot). Works for WhatsApp Cloud and WhatsApp Web.
Your endpoint should respond quickly with HTTP 200 (requests time out after 5 seconds). Message status updates are a separate webhook — see Message Status Webhook.
POST {{YOUR_WEBHOOK_URL}}
| Field |
Type |
Description |
| secret_key |
String |
Secret key of your webhook (Webhook page). Verify it to make sure the request came from us. |
| wa_number |
String |
Your WhatsApp number. |
| recipient |
String |
Customer number (group id for group messages). |
| message |
String |
Message text, or the media URL for image / video / audio / document, or a Google Maps link for location. |
| caption |
String |
Media caption. WhatsApp Cloud only. |
| from |
String |
user = message received from the customer.
bot = message sent by you: bot replies, and (when "Also send messages we send" is enabled) messages sent from Inbox, Chat History, API or the WhatsApp phone.
|
| message_type |
String |
text, image, video, audio, document or location.
|
| message_id |
String |
WhatsApp message id. Status updates for messages you sent carry the same id. |
| is_group |
Number |
1 for group messages, otherwise 0.
|
| group_id |
String |
Group id. Only present for group messages. |
| sender |
String |
Number of the group member who sent the message. Only for received group messages (from = user). |
| sender_name |
String |
WhatsApp name of the group member who sent the message. Only for received group messages. |
| webhook_source |
String |
WhatsApp (WhatsApp Web) or WhatsApp Cloud.
|
{
"secret_key": "WEBHOOK_SECRET_KEY",
"wa_number": "919876543210",
"recipient": "918888888888",
"message": "Hi, what are your prices?",
"from": "user",
"message_type": "text",
"message_id": "wamid.HBgMOTE4ODg4ODg4ODg4FQIAEhggQTc2QkM4RjE1MkQ0QjU3NzRBAA==",
"is_group": 0,
"webhook_source": "WhatsApp Cloud"
}
{
"secret_key": "WEBHOOK_SECRET_KEY",
"wa_number": "919876543210",
"recipient": "918888888888",
"message": "Our plans start at Rs 999/month.",
"from": "bot",
"message_type": "text",
"message_id": "wamid.HBgMOTE4ODg4ODg4ODg4FQIAERgSQjM2RkU3QTlCNDQ3QjYwRTFCAA==",
"is_group": 0,
"webhook_source": "WhatsApp Cloud"
}
{
"secret_key": "WEBHOOK_SECRET_KEY",
"wa_number": "919876543210",
"recipient": "120363025246125486",
"message": "https://example.com/uploads/photo.jpg",
"from": "user",
"message_type": "image",
"message_id": "3EB0C4F5A1B2C3D4E5F6",
"is_group": 1,
"group_id": "120363025246125486",
"sender": "918777777777",
"sender_name": "Rahul",
"webhook_source": "WhatsApp"
}
PHP Example (receiver)
<?php
$data = $_POST;
if (($data['secret_key'] ?? '') !== 'WEBHOOK_SECRET_KEY') { http_response_code(403); exit; }
if (($data['event'] ?? '') === 'status') {
// status update - see Message Status Webhook
} elseif ($data['from'] === 'user') {
// message received from the customer
$who = !empty($data['is_group']) ? $data['sender'] : $data['recipient'];
$text = $data['message'];
} else {
// from = bot: bot reply or message sent by you / your agents
}
http_response_code(200);