👍

Unipile V1 is not deprecated.

We will continue maintaining V1 for a long time; there is no deprecation date. Of course, new features will only be added to V2. You can keep using V1 while you test/migrate to V2.

We expect to release V2 Beta to production in summer 2026. If you are a new user planning to launch in the next few weeks, please consider implementing V2 directly. If you have already started implementing V1, it shouldn’t take long to make the necessary changes, but you can still launch on V1.

When V2 leaves beta, all new Unipile accounts will be created on V2 by default. You will need to contact us to create a V1 account if you have a specific use case.

Why migrate ?

Migrating to v2 can be time consuming at first glance, but don't worry, fundamentals are the same, it's mostly naming changes for a cleaner and more consistent API Design. In the long term, this new design is easier to work with.

Moreover, v2 comes with a bunch of new features :

• Dashboard
  • Organizations with members and roles
  • Environments
  • Webhooks debugging tools
  • Testing accounts
  • Account details
• Security
  • Webhooks signatures
  • 2FA on Dashboard
• API
  • Rate limiting & Caching for optimized requests
  • Customizable hosted auth wizard
  • New API Methods
  • New Webhook event types
  • Improved performance
• Documentation
  • Integration guides
  • Open sourced example projects
• New providers : Google Messages, Messenger, X (Twitter)

From pre-synchronization to on-demand retrieval

One of the biggest architectural changes between V1 and V2 is how data is made available.

In V1, Unipile generally synchronized large amounts of historical data when an account was linked. This synchronization could take some time, but once completed, most requests were served directly from Unipile’s infrastructure.

In V2, data is retrieved on demand whenever possible. This allows accounts to become available much faster and avoids lengthy synchronization phases before an account can be used.

Some providers still require an initial synchronization phase (such as WhatsApp), while others may perform partial synchronizations depending on provider constraints. However, the overall architecture now favors on-demand retrieval rather than preloading large amounts of data.

Does this mean more provider requests?

Not necessarily.

In V1, Unipile automatically synchronized large amounts of historical data when an account was linked. While this reduced the need for provider requests later on, it also meant that many requests were performed upfront to retrieve data that might never be used by the consuming application.

In V2, this responsibility is shifted. Instead of preloading large amounts of data by default, data is retrieved when it is actually needed.

As a result, the total number of provider requests may be lower, higher, or similar depending on your application’s usage patterns. Applications that only access a subset of the available data often benefit from fewer unnecessary provider requests overall.

To ensure this model remains efficient and safe, V2 introduces:

• Caching: Retrieved data is automatically cached by Unipile, reducing repeated provider requests.
• Rate limiting: Unipile automatically enforces provider-safe limits to protect connected accounts.

This allows applications to access data on demand while maintaining account safety and avoiding most of the drawbacks traditionally associated with direct provider access.

Benefits of the new architecture

• Accounts become available faster after linking.
• No need to wait for large historical synchronizations before using an account.
• Reduced infrastructure costs and synchronization delays.
• Better scalability for large accounts.
• Account safety remains protected through caching and rate limiting.

How to migrate ?

1. Sign up on v2.
2. Create a new Test Application.
3. Create a new API Key.
4. Update your source code to adapt to the new API Design
   1. (I use the SDK) Update the SDK and replace the v1 Access Token with the v2 API Key on client initialization.
   2. (I don't use the SDK) Replace your DSN with the new API base URL https://api.unipile.com/v2 and replace the v1 Access Token with the v2 API Key in X-API-KEY header.
   3. Check the list of changes in the following pages to adapt your code.
   4. Re-create Webhooks from v1 for development (See Configure a webhook) and update your source code to adapt to the new Realtime API Design.
5. Once your application is updated for v2, copy your data from v1 to v2 using the migration tool in the Menu of the v1 Dashboard. The migration tool will help you to copy data including Accounts, oAuth Settings and Subscription in a Unipile Production Application.
6. Create a new API Key in your production Application
7. Re-create Webhooks from the Test Application but using your production webhook endpoints
8. Deploy your updated code to production

API Overall changes

• Base URL: The DSN is no longer in use.
  • Make sure to use api.unipile.com/v2 as the base URL.
• Listing Routes: Routes for listing are no longer unified across accounts.
  • Make sure to take this in account in your app.
• Pagination: All routes for listing support pagination, but with offset/limit or cursor depending on the provider.
  • Make sure to update requests to listing routes that have been updated in the following list.
• Unipile IDs and Provider IDs: The distinction between "Provider" IDs and "Unipile" IDs has been removed. There is no more Unipile IDs, now, all IDs are "Provider" IDs.
  • Make sure your app is aware of those new ids.
• Account and Webhook IDs: Accounts, Webhook (basically every data not from a Provider) ids has changed format. They now start with acc_, we_, etc....
  • Make sure your app is aware of those new ids.
• Target Accounts: Previously, some endpoints were used to retrieve data across all connected accounts (listing). Now, each route retrieve the data for a single account. The ID of the targeted account is in the path of every endpoint. Therefore, every body and query params like account_id or account_type have been removed, and every method route starts with /v2/:account_id/...
• Route Consistency: Routes have been rewritten for consistency across the entire Unipile API.
  • Make sure to update requests to routes that have been removed or changed in the following list.
• Requests and Responses: Request parameters and response data have been updated to fix naming inconsistencies, improving efficiency for developers and reflecting the aforementioned changes.
  • Make sure to update requests to routes with updated params in the following list
• Objects schema changes: Objects shape have been rewritten for consistency and to give more informations. See Data Object Changes section below.
  • Make sure your app is aware of new data shapes.
• Attachments: All methods accepting files now use application/json and a base64 format to describe the file content.
  • Make sure to update those requests with the write Content-Type and to parse attachments as base64

Next steps