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.

By default, Hosted Auth lets the user choose between scanning a QR code and entering a pairing code. To restrict the available methods, set config.whatsapp.allow_methods to ['qr'], ['pairing'], or both values.

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",
    config: {
      whatsapp: {
        allow_methods: ["qr", "pairing"],
      },
    },
  },
});

// ...

# ...

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",
        "config": {
            "whatsapp": {
                "allow_methods": ["qr", "pairing"]
            }
        }
    }
)

# ...

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",
  "config": {
    "whatsapp": {
      "allow_methods": ["qr", "pairing"]
    }
  }
}
'

Link with Custom Auth

To build a custom authentication wizard for WhatsApp accounts, use either the QR Code Flow or the Credentials Flow. In the Credentials Flow, submit the WhatsApp phone number and handle the returned PAIRING_CODE checkpoint.

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.