Architecture Evolution

The architecture has evolved significantly, and there are a few key concepts to understand before diving into the codebase.

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.

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