WhatsApp API – Official (Meta Cloud API) & Unofficial — Webhooks
Events are delivered via POST to the instance's configured url. The output format
depends on webhookFormat (set per instance):
native(default) — the API's native payload, with no transformation.meta— envelope in the WhatsApp Cloud API (Meta) vocabulary. Unmappable events fall back to native.both— sends both (native + meta).
Envelope (meta format)
object:"wame"(the equivalent of Meta's"whatsapp_business_account"— marks that it's this API).entry[].id: masked WABA id (we don't expose Meta's internal ids).entry[].changes[].field:"messages"(or the event type).entry[].changes[].value:{ messaging_product, metadata, contacts?, messages?|statuses? }.metadata.phone_number_id: the instance key;display_phone_number: the connected number.
Intentional differences vs the official Cloud API
- Media (
image/audio/video/document/sticker):urlpoints toGET {URL_SERVER}/{key}/message/{id}/media; theidis the message id (not a separate media-asset-id). - Group: uses
group_id(keeps the group jid, e.g.123-456@g.us) directly on the message object. from_me: true: our extension — present on SENT messages (Meta doesn't echo outgoing messages).status.conversation/status.pricing: Meta-internal billing fields — emitted asnullplaceholders only for shape compatibility.
Models
Full examples live in assets/examples/webhooks/meta/ (generated by npm run examples:meta):
message-text
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_TEXT",
"timestamp": "1700000000",
"type": "text",
"text": {
"body": "Olá!"
}
}
]
}
}
]
}
]
}
message-image
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_IMG",
"timestamp": "1700000000",
"type": "image",
"image": {
"id": "WAMID_IMG",
"url": "https://us.api-wa.me/your-instance-id/message/WAMID_IMG/media",
"mime_type": "image/jpeg",
"sha256": "YWJj",
"caption": "foto"
}
}
]
}
}
]
}
]
}
message-audio
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_AUD",
"timestamp": "1700000000",
"type": "audio",
"audio": {
"id": "WAMID_AUD",
"url": "https://us.api-wa.me/your-instance-id/message/WAMID_AUD/media",
"mime_type": "audio/ogg",
"sha256": "YWJj",
"voice": true
}
}
]
}
}
]
}
]
}
message-video
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_VID",
"timestamp": "1700000000",
"type": "video",
"video": {
"id": "WAMID_VID",
"url": "https://us.api-wa.me/your-instance-id/message/WAMID_VID/media",
"mime_type": "video/mp4",
"sha256": "YWJj",
"caption": "v"
}
}
]
}
}
]
}
]
}
message-document
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_DOC",
"timestamp": "1700000000",
"type": "document",
"document": {
"id": "WAMID_DOC",
"url": "https://us.api-wa.me/your-instance-id/message/WAMID_DOC/media",
"mime_type": "application/pdf",
"sha256": "YWJj",
"filename": "orcamento.pdf",
"caption": "PDF"
}
}
]
}
}
]
}
]
}
message-sticker
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_STK",
"timestamp": "1700000000",
"type": "sticker",
"sticker": {
"id": "WAMID_STK",
"url": "https://us.api-wa.me/your-instance-id/message/WAMID_STK/media",
"mime_type": "image/webp",
"sha256": "YWJj",
"animated": false
}
}
]
}
}
]
}
]
}
message-location
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_LOC",
"timestamp": "1700000000",
"type": "location",
"location": {
"latitude": -25.4,
"longitude": -49.2,
"name": "Curitiba",
"address": "PR"
}
}
]
}
}
]
}
]
}
message-contacts
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_CON",
"timestamp": "1700000000",
"type": "contacts",
"contacts": [
{
"name": {
"formatted_name": "Beltrano"
},
"vcard": "BEGIN:VCARD..."
}
]
}
]
}
}
]
}
]
}
message-reaction
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_RCT",
"timestamp": "1700000000",
"type": "reaction",
"reaction": {
"message_id": "ORIG1",
"emoji": "👍"
}
}
]
}
}
]
}
]
}
message-reaction-removed
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_RCT2",
"timestamp": "1700000000",
"type": "reaction",
"reaction": {
"message_id": "ORIG1"
}
}
]
}
}
]
}
]
}
message-button
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_BTN",
"timestamp": "1700000000",
"type": "button",
"button": {
"text": "Sim",
"payload": "btn_yes"
}
}
]
}
}
]
}
]
}
message-interactive-list
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_LST",
"timestamp": "1700000000",
"type": "interactive",
"interactive": {
"type": "list_reply",
"list_reply": {
"id": "row_1",
"title": "Opção A",
"description": "desc"
}
}
}
]
}
}
]
}
]
}
message-interactive-button
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_TBTN",
"timestamp": "1700000000",
"type": "interactive",
"interactive": {
"type": "button_reply",
"button_reply": {
"id": "btn_1",
"title": "Confirmar"
}
}
}
]
}
}
]
}
]
}
message-unsupported
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_UNS",
"timestamp": "1700000000",
"type": "unsupported",
"errors": [
{
"code": 131051,
"title": "Unsupported message type",
"message": "Message type pollCreationMessageV3 is not supported",
"error_data": {
"details": "pollCreationMessageV3"
}
}
]
}
]
}
}
]
}
]
}
message-reply-context
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_RPL",
"timestamp": "1700000000",
"type": "text",
"text": {
"body": "respondendo"
},
"context": {
"from": "5511777776666",
"id": "QUOTED1"
}
}
]
}
}
]
}
]
}
message-referral
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511999998888"
}
],
"messages": [
{
"from": "5511999998888",
"id": "WAMID_ADS",
"timestamp": "1700000000",
"type": "text",
"text": {
"body": "vim do anúncio"
},
"referral": {
"source_url": "https://fb.me/x",
"source_id": "AD123",
"source_type": "ad",
"headline": "Promo",
"body": "Fale conosco",
"media_type": "image",
"thumbnail_url": "https://cdn/t.jpg",
"ctwa_clid": "CLID9"
}
}
]
}
}
]
}
]
}
message-group
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Fulano"
},
"wa_id": "5511777776666"
}
],
"messages": [
{
"from": "5511777776666",
"group_id": "16479379001-1580667835@g.us",
"id": "WAMID_GRP",
"timestamp": "1700000000",
"type": "text",
"text": {
"body": "oi grupo"
}
}
]
}
}
]
}
]
}
message-from-me
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"contacts": [
{
"profile": {
"name": "Eu"
},
"wa_id": "5566996852025"
}
],
"messages": [
{
"from": "5566996852025",
"id": "WAMID_OUT",
"timestamp": "1700000000",
"type": "text",
"text": {
"body": "msg minha"
},
"from_me": true
}
]
}
}
]
}
]
}
message-edit
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"messages": [
{
"from": "5511999998888",
"id": "WAMID_ORIG",
"timestamp": "1700000000",
"type": "edit",
"edit": {
"original_message_id": "WAMID_ORIG",
"message": {
"type": "text",
"text": {
"body": "mensagem corrigida"
}
}
}
}
]
}
}
]
}
]
}
status-sent
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"statuses": [
{
"id": "WAMID_TEXT",
"status": "sent",
"timestamp": "1700000000",
"recipient_id": "5511999998888",
"conversation": {
"id": null,
"expiration_timestamp": null,
"origin": {
"type": null
}
},
"pricing": {
"billable": null,
"pricing_model": null,
"type": null,
"category": null
}
}
]
}
}
]
}
]
}
status-delivered
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"statuses": [
{
"id": "WAMID_TEXT",
"status": "delivered",
"timestamp": "1700000000",
"recipient_id": "5511999998888",
"conversation": {
"id": null,
"expiration_timestamp": null,
"origin": {
"type": null
}
},
"pricing": {
"billable": null,
"pricing_model": null,
"type": null,
"category": null
}
}
]
}
}
]
}
]
}
status-read
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"statuses": [
{
"id": "WAMID_TEXT",
"status": "read",
"timestamp": "1700000000",
"recipient_id": "5511999998888",
"conversation": {
"id": null,
"expiration_timestamp": null,
"origin": {
"type": null
}
},
"pricing": {
"billable": null,
"pricing_model": null,
"type": null,
"category": null
}
}
]
}
}
]
}
]
}
status-played
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"statuses": [
{
"id": "WAMID_AUD",
"status": "played",
"timestamp": "1700000000",
"recipient_id": "5511999998888",
"conversation": {
"id": null,
"expiration_timestamp": null,
"origin": {
"type": null
}
},
"pricing": {
"billable": null,
"pricing_model": null,
"type": null,
"category": null
}
}
]
}
}
]
}
]
}
status-group
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"statuses": [
{
"id": "WAMID_GRP",
"status": "delivered",
"timestamp": "1700000000",
"recipient_id": "16479379001-1580667835@g.us",
"recipient_type": "group",
"recipient_participant_id": "5511999998888",
"conversation": {
"id": null,
"expiration_timestamp": null,
"origin": {
"type": null
}
},
"pricing": {
"billable": null,
"pricing_model": null,
"type": null,
"category": null
}
}
]
}
}
]
}
]
}
status-failed
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"statuses": [
{
"id": "WAMID_TEXT",
"status": "failed",
"timestamp": "1700000000",
"recipient_id": "5511999998888",
"conversation": {
"id": null,
"expiration_timestamp": null,
"origin": {
"type": null
}
},
"pricing": {
"billable": null,
"pricing_model": null,
"type": null,
"category": null
},
"errors": [
{
"code": 463,
"title": "Conta restringida",
"message": "Conta restringida",
"error_data": {
"details": "463"
}
}
]
}
]
}
}
]
}
]
}
receipt
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"statuses": [
{
"id": "WAMID_TEXT",
"status": "read",
"timestamp": "1700000005",
"recipient_id": "5511777776666",
"conversation": {
"id": null,
"expiration_timestamp": null,
"origin": {
"type": null
}
},
"pricing": {
"billable": null,
"pricing_model": null,
"type": null,
"category": null
}
}
]
}
}
]
}
]
}
presence
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "presence",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"presence": {
"wa_id": "160301265768606",
"status": "available"
}
}
}
]
}
]
}
connection-open
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "connection",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"connection": {
"status": "open",
"code": 200
}
}
}
]
}
]
}
connection-close
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "connection",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"connection": {
"status": "close",
"code": 1004,
"reason": "disconnected"
}
}
}
]
}
]
}
qrcode
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "qrcode",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"qrcode": {
"code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
}
}
}
]
}
]
}
call
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "call",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"calls": [
{
"id": "CALL1",
"from": "5511999998888",
"status": "offer",
"is_video": false,
"is_group": false,
"timestamp": "1700000000"
}
]
}
}
]
}
]
}
group-participants
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "groups",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"groups": {
"event": "participants_updated",
"id": "16479379001-1580667835@g.us",
"action": "add",
"participants": [
"5511999998888@s.whatsapp.net"
]
}
}
}
]
}
]
}
group-update
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "groups",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"groups": {
"event": "update",
"data": [
{
"id": "16479379001-1580667835@g.us",
"subject": "Novo nome"
}
]
}
}
}
]
}
]
}
health
{
"object": "wame",
"entry": [
{
"id": "wame.eW91ci1pbnN0YW5jZS1pZA",
"changes": [
{
"field": "health",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "5566996852025",
"phone_number_id": "your-instance-id"
},
"health": {
"status": "restricted",
"previous": "healthy",
"reason": "many 463",
"should_pause": true,
"should_rotate": false
}
}
}
]
}
]
}