WhatsApp webhook fields, and which ones go where
A WhatsApp Business Account delivers events as named fields. Two carry conversation content and are routed to your endpoint. Six carry operational state and are what monitoring is built from. Knowing which is which decides your architecture.
- Two message fields, six operational
- Routing is set per account
- Named fields, not a generic payload
Nothing charged for 7 days. Cancel anytime.
Message path fields: messages and smb_message_echoes.
Operational fields kept for monitoring.
Override per WhatsApp Business Account, which is what splits them.
What does each field carry?
messages carries everything a customer sends to the number: text, media references, replies and reactions. smb_message_echoes carries what your team sends from the WhatsApp Business app, which only exists on a Coexistence number and is how software sees a human's replies.
account_update carries connection state: PARTNER_REMOVED when the app is uninstalled from the account, ACCOUNT_OFFBOARDED, ACCOUNT_RECONNECTED, and restriction or violation events. phone_number_quality_update carries quality rating and throughput changes. account_alerts carries alerts Meta raises against the account, and account_review_update carries the outcome of a review.
business_capability_update carries messaging limit and capability changes, and phone_number_name_update carries display name approvals and rejections.
Why does the split matter architecturally?
Because it decides whether conversation content ever reaches a provider.
The override sends the two message fields to your endpoint directly from Meta. The six operational fields continue to the provider, which is what makes a dashboard and alerting possible without anyone holding a message.
This is also why a claim about not storing messages can be structural rather than a policy. If the message fields are delivered elsewhere, there is no code path on which they could be stored. In our case an account with no override falls back to the default callback, where the handler drops those events without persisting them.
Which fields should your handler expect?
Only the two message fields, if the override is set, and it is worth writing the handler to ignore anything else rather than to fail on it.
Meta adds fields over time and a payload shape can gain keys without notice. A handler that switches on the field name and ignores what it does not recognise keeps working; one that assumes a shape throws on the first unfamiliar event.
It is also worth handling smb_message_echoes explicitly rather than treating it as noise. Without it, software has no idea a human already answered, which is how a customer ends up with two replies to the same question.
Common mistakes
- Assuming a generic payload. Every event names its field, and the handler should switch on it.
- Ignoring smb_message_echoes. Without it software replies on top of a human who already answered.
- Failing on unrecognised fields rather than skipping them. Meta adds fields without asking.
EasyCoexistence subscribes the operational fields for monitoring and routes the two message fields to your endpoint, or drops them unpersisted if you have not set one.
Frequently asked questions
Can I receive only some fields?
The override moves the message path to you. The operational split is fixed, because monitoring is built from it.
Does smb_message_echoes exist on a normal Cloud API number?
No. It exists because a Coexistence number has a human sending from the app as well as software sending from the API.
What happens to message events if I set no destination?
They arrive at our default callback and are dropped without being persisted.
Are the field names Meta's or yours?
Meta's. Nothing here is a name we invented, which is why they are worth learning once.
Keep reading
Ready to get started?
Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.
Start Free TrialNothing charged for 7 days. Cancel anytime.Verified on