The smb_app_state_sync webhook

What it carries

App side state, which in practice means the contacts a business already had on the phone.\n\nEvery contact with a WhatsApp number can be synchronised to the platform, which is what lets software recognise a customer who has been in the business's phone for years rather than treating them as a new number. That is a different thing from the conversations themselves, which arrive on the history field, and the two are separate because one is a directory and the other is a transcript.\n\nLike history, this only exists on Coexistence. There is no app state to sync on a number that was never in one.

What it does not carry

The app's own working tools, which have no representation on the platform side.

• Labels, which live on the device and cannot be read by software.
• Quick replies and the greeting and away messages.
• The catalog, orders and status.
• Channels, and voice or video call history.

Why this matters for an integration

Because it decides whether your system knows who is writing on day one.\n\nWithout the contact sync, every inbound message arrives as a phone number with no name attached, and matching it to a customer record is your problem. With it, the business's own contact list is available and the matching is mostly done.\n\nIt is worth planning for both, because a business can decline the sync or miss the window, and an integration that assumes contacts exist will show a wall of raw numbers to whoever opens it.

Common mistakes

• Assuming contacts will be there. A business can decline the sync or miss its window.
• Expecting labels or quick replies in this payload. They stay on the device.
• Confusing it with history, which carries conversations rather than the contact list.

Frequently asked questions

Keep reading