> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wsapi.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Initial Sync

> Understand how WSAPI synchronizes data when an instance first connects

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)

<Note>
  The initial sync does not download all historical messages. When `HistorySync` is enabled, only a recent window of messages is synced.
</Note>

## 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

<Note>
  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.
</Note>

## 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](/basics/event-filtering).
* 'initial\_sync\_finished' is a session event and cannot be filtered out, so you will receive it regardless of your HistorySync settings.