Skip to main content
When a WSAPI instance pairs with a WhatsApp account for the first time, an initial synchronization process begins. This process loads your existing WhatsApp data into the instance so it’s ready for API operations.

​
What gets synced

During initial sync, WSAPI retrieves:
  • Contacts — your WhatsApp address book
  • Chats — recent conversation metadata
  • Groups — group memberships and settings
  • Recent messages — a window of recent message history (when HistorySync is enabled)
The initial sync does not download all historical messages. When HistorySync is enabled, only a recent window of messages is synced.

​
How it works

  1. Your instance connects to WhatsApp after pairing and you receive the logged_in event
  2. WhatsApp begins streaming initial data to the instance
  3. Once the initial data is fully synced, the initial_sync_finished event is emitted

​
HistorySync behavior

WSAPI supports a HistorySync setting to control whether message history synchronization is enabled.
  • When HistorySync is enabled:
    • After receiving initial_sync_finished, call POST /session/flush-history in the API to start syncing message history for all chats
    • Asynchronously, WSAPI then starts sending message_history_sync events (each event contains history messages for a chat)
  • When HistorySync is disabled (or not set):
    • You still receive the initial_sync_finished event, but no message history is synced
    • You do not receive message_history_sync events
HistorySync is disabled by default. If you want to sync message history, you must explicitly enable it at customer default settings or at per-instance level.

​
Sync duration

The time required depends on the amount of data in the WhatsApp account (number of contacts, chats, groups, etc.). For most accounts, the sync completes within a few seconds to a couple of minutes.

​
Best practices

  • Wait for the event. Don’t call POST /session/flush-history until sync is complete
  • Use event filtering. If you want to use the HistorySync feature, make sure message_history_sync in your event filters.
  • ‘initial_sync_finished’ is a session event and cannot be filtered out, so you will receive it regardless of your HistorySync settings.