Some providers require Unipile to download historical data—data that already exists on the account before it is linked. This is necessary when:

• The provider’s data is decentralized and cannot be fetched on demand (e.g., WhatsApp), or
• Unipile enhances features for providers with limited capabilities (e.g., IMAP, which lacks full-text search).

This process is called the Initial Sync. It can take anywhere from a few seconds (small WhatsApp accounts) to several hours (large IMAP inboxes). During this time, historical data is only partially available, which may affect your application. Unipile exposes the sync status on the Account object and also notifies you through webhooks.

Providers using Initial Sync

The Initial Sync is required or available for:

• WhatsApp — mandatory
• IMAP — required for advanced search only

👍

All other providers have full historical data available to queried immediately after the account is linked.

Sync Status

The initial_sync field of an Account object has four possible values:

• pending — The account has just been linked and the initial sync has not started yet.
• running — Unipile is currently downloading historical data. This can take up to few minutes, mostly on big IMAP accounts that uses slow providers.
• failed — An error occurred during the sync of historical data. The account remains usable but historical data may be incomplete. Unipile will retry automatically.
• completed — The initial sync successfully finished and all historical data is available.

Tracking Sync Status

To stay informed about the sync progression, configure a webhook that listens to:

• account.initial_sync.running
• account.initial_sync.failed
• account.initial_sync.completed

See: Configure a webhook

Wait in Hosted Authentication

When using Hosted Auth, you can delay the redirection to your application until the initial sync is completed. To do this, set config.global.wait_for_sync to true.

const response = await unipile
  	.hostedAuth
  	.createAuthLink({
      config: {
        global: {
           wait_for_sync: true
        }
      },
      // Rest of the body
  	});

curl --request POST \
     --url https://api.unipile.com/v2/auth/link \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "config": { "global": { "wait_for_sync": true } },
  // Rest of the body
}
'

This approach keeps the user on the authentication screen until all required data is available. It is a simple and effective solution for applications that depend on complete historical data and want to avoid operating on partial data—without the need to configure webhooks.

However, keep in mind that this approach is not fully safe: users can still close the authentication window while the sync is in progress and return to your application before the initial sync has completed.

Best practice

Use webhooks to reliably track the initial sync status (account.initial_sync.* events) and gate access to features that require complete data. This ensures your application behaves correctly even if the user leaves the authentication flow early.