How does it work ?

To link a WhatsApp account with Unipile, users must use the Link a Device feature provided by WhatsApp.

If the Unipile device is removed from the list of linked devices in WhatsApp, the account will transition to the disconnected state (🟡 Requires Authentication). This means the user must re-authenticate to restore full functionality.

Recommendations

1. Avoid using brand new accounts exclusively for software purposes. Instead, utilize WhatsApp accounts with historical activity from real users to prevent account to be suspended. If you use fresh account they can be blocked after 2-3 new chat, they need to be warmup during days with one or two chats.
2. Keep the primary device (the phone where WhatsApp is installed) powered on and connected to the internet. This ensures that data remains synchronized with Unipile, and prevents missing messages when using GET methods or receiving real-time events.

Link with Hosted Auth

To link WhatsApp accounts using Hosted Authentication, follow the Authenticate with Hosted Auth guide and specify WHATSAPP as the providers when calling Create Auth Link.

Server code

// ...

const response = await hostedAuthApi.createAuthLink({
  body: {
    providers: "WHATSAPP",
    expires_on: dayjs().add(10, "minutes").toISOString(),
    redirect_uri: "https://myapp.com/link-account/callback",
  },
});

// ...

# ...

response = hosted_auth_api.create_auth_link(
    {
        "providers": "WHATSAPP",
        "expires_on": "2025-05-05T00:00:00.000Z",
        "redirect_uri": "https://myapp.com/link-account/callback",
    }
)

# ...

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 '
{
  "providers": "WHATSAPP",
  "redirect_uri": "https://myapp.com/link-account/callback",
  "expires_on": "2025-05-05T00:00:00.000Z"
}
'

Link with Custom Auth

To build a custom authentication wizard for WhatsApp Accounts, follow the QR Code Flow guide.

Wait for Initial Sync to complete

As explained in the Initial Sync guide, WhatsApp data is decentralized, which means historical data must be synchronized with Unipile before it can be queried.

If your application requires full historical data immediately after an account is linked, it must wait until the initial sync is finished. To do so, Configure a webhook that listens to the account.initial_sync.completed event. This event signals that all historical data has been successfully downloaded and is now available for queries.