From Dashboard

For quick testing or manual setup, you can link accounts directly from the Dashboard — no coding required.

Quick Add

Start the authentication wizard with default minimal settings to add any type of account in just a few clicks. At the end of the flow, you’ll be redirected to the Accounts list in the Dashboard.

This option is especially useful during development, when you need to:

• Quickly try out the API.
• Manually link accounts that are not tied to your users and don’t require special configuration.

Custom Authentication Link

From the Dashboard, you can also generate an authentication link with custom configuration.

This is useful when you want to:

• Test more complex scenarios during development (e.g., proxies, provider-specific options, or custom OAuth settings) without writing code.
• Share a one-time authentication link with your users. If you do, you can redirect them to your app at the end of the flow.

Programmatically

For integrating the linking process into your own product’s user experience. Authentication flows with providers are often complex. They can involve QR code scanning, 2FA (two-factor authentication), CAPTCHAs, browser cookies, and non-standard or undocumented APIs. This is notably the case for messaging providers such as WhatsApp, Telegram, Google Messages, Facebook, and X (Twitter). To handle these workflows, Unipile provides two programmatic options.

Hosted Authentication (Recommended)

This is the easiest and most robust option.

Unipile handles the entire authentication process—including login, 2FA, QR codes, and any provider-specific flows—through a hosted interface. This is the one you see when linking accounts from dashboard.

How it works:

• Generate an authentication link via the API
• Redirect your user to that link
• Once the user completes authentication, their account is securely linked to Unipile and they are redirected to your application.

This approach is secure, fast to implement, and automatically handles edge cases and updates when provider flows change.

📘

To start implementing, read our Hosted Authentication integration guide.

Custom Authentication (Advanced)

Use this option if you want to embed the full authentication flow inside your app, with a custom UI and UX.

This flow is powered by Auth Intents and involves solving checkpoints—each representing a step in the authentication process (e.g. login, OTP, captcha, QR scan, etc.).

How it works:

• Create an Auth Intent to start the flow
• You’ll receive checkpoint instructions from the API
• Guide the user through each checkpoint
• Once all checkpoints are solved, the account is linked

This method gives you complete control over the flow, but requires more development effort and robust error handling.

📘

To start implementing, read our Custom Authentication integration guide.

What Happens After Linking?

Once an account is linked:

• You can use API Methods. Read on Methods.
• You’ll receive real-time updates via webhooks. Read on Realtime.
• If the connection is lost (e.g. expired session, password change), you’ll be notified and can prompt the user to re-authenticate. Read on Connection Status.
• If the provider is down, you'll be notified. Read on Connection Status.

Account Linking Limitations

In some cases, Unipile may prevent an account from being linked at the end of the authentication process.

We recommend that your application handles these cases gracefully whether you're using a custom integration or Unipile's hosted authentication. This ensures a better user experience and allows you to manage edge cases appropriately across all scenarios.

Duplicate Account

Unipile does not allow the same account to be linked more than once for an Application. If an account is already linked, the API will return a 403 error with the type api/already_exists and detail as the existing linked Account ID.

Response example

{
  "object": "Error",
  "title": "Account already exists",
  "type": "api/already_exists",
  "status": 403,
  "detail": "acc_1234567890",
  "req-id": 1
}

👍

How to handle this case

This check is performed after the full authentication flow, meaning the account owner’s identity has been successfully verified. You can trust the user owns the account and handle this case accordingly, for example by suggesting they use the existing connection.

Restricted Account

Unipile may also restrict certain accounts from being linked — for example, in cases of free trial abuse or policy violations. In this situation, the API returns a 403 error with the type api/account_restricted and detail as the reason and Provider ID.

Response example

{
  "object": "Error",
  "title": "Account restricted",
  "type": "api/account_restricted",
  "status": 403,
  "detail": "reason",
  "req-id": 1
}

👍

How to handle this case

When this occurs, it is recommended to inform the user that the account cannot be linked and optionally guide them to support. You may also choose to notify your internal team for further review. Share with Unipile support the provider ID of concerned account to know more about the cause.