The smb_app_state_sync field synchronizes WhatsApp Business app contact state for a business customer onboarded through a solution provider. In Dualhook setups, it is direct-routed to your endpoint via Webhook Override.
What smb_app_state_sync Reports
This field reports contact-book changes from the WhatsApp Business app:
- a contact was added,
- a contact was edited,
- a contact was removed,
- the initial app contact sync was triggered after onboarding.
The payload is not a Cloud API message send or delivery status. It is contact state from the business customer's WhatsApp Business app.
When It Fires
Meta sends this field when a provider synchronizes the business app contacts after onboarding, and later when the business customer adds, edits, or removes contacts in the WhatsApp Business app address book.
Payload Shape
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WABA_ID>",
"changes": [
{
"field": "smb_app_state_sync",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"state_sync": [
{
"type": "contact",
"contact": {
"full_name": "Pablo Morales",
"first_name": "Pablo",
"phone_number": "16505551234"
},
"action": "add",
"metadata": {
"timestamp": "1739321024"
}
}
]
}
}
]
}
]
}| Field | Notes |
|---|---|
state_sync[].type | Currently contact sync uses contact. |
state_sync[].action | add means added or edited; remove means removed. |
contact.full_name / contact.first_name | Present for add/edit, omitted for removals. |
contact.phone_number | WhatsApp contact phone number. |
metadata.timestamp | Timestamp for the contact-state event. |
Dualhook Handling
Dualhook does not ingest, store, forward, or replay smb_app_state_sync payloads. This field is direct-routed through Webhook Override, so Meta sends contact-sync payloads to your configured endpoint.
During Coexistence onboarding, Dualhook triggers Meta's one-time contact sync after Webhook Override is accepted. A successful trigger only means Meta accepted the sync request; it does not prove that contacts were delivered or that your endpoint processed them. Future app contact changes also go Meta → your endpoint.
If your endpoint misses contact-sync payloads, Dualhook has no stored copy to replay.
Implementation Notes
- Treat
addas upsert. Meta uses it for both new and edited contacts. - Treat
removeas deletion or tombstone, and do not require name fields on remove events. - Process asynchronously if the initial sync includes many contacts.
- Deduplicate by WABA ID, phone number ID, contact phone number, action, and timestamp.
- Review your privacy posture: once your endpoint receives contact sync, your system becomes the contact-data storage boundary.