Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Best Practices for Building with Sync SDKs


Twilio Sync is a developer's toolbox that you can use to overcome a large set of technical challenges. Because it is a powerful tool, we have developed some guidelines for how to best engage with this product, particularly when using the SDKs.

This guide covers best practices for development using the Sync SDKs. The Sync team has learned a lot with our customers and can provide some known best practices to make implementation easier and reliable.

Before you start to work with Sync, we recommend checking that your use case matches one of the most common use cases, often within Twilio Flex:

  • A queue dashboard
  • Displaying an agent's recent calls in Flex
  • Managing stored responses

Sync is a powerful, low-level tool that pairs well with use cases like those above, often adding functionality to your Twilio Flex instance. If you want to implement basic contact center capabilities, however, we recommend looking at Flex itself. It gives you access to Flex Insights right out of the box, with no need to build a live dashboard yourself.

For more general guidance for building with Flex, please see our best practices guide, Building Scalable Sync Apps.


Working with JWT/JWE tokens

working-with-jwtjwe-tokens page anchor

The Sync SDKs use JSON Web Tokens ("JWT") and JSON Web Encryption ("JWE") tokens to secure your client-side application.

  • We recommend setting several hours (maximum 24H) for the token's time-to-live ("TTL"). This ensures that expired Sync objects are removed on time and do not remain accessible.

    • Token minimum TTL (time-to-live) is 30 minutes. It will work properly within 5 minutes as well, but some network issues may disrupt the token update operation.
  • You should implement methods to update your tokens in respective SDK clients, reacting to the token expiration events provided by SDKs.
  • To implement faster application start-up, you can pre-fetch your token and store it in temporary storage. This step saves you the round-trip time that it takes to make a request to your backend token generator.

    • To avoid reusing stale tokens, you can set your local storage to a shorter TTL than that of the token itself.
  • You can use a Twilio Function to generate a token within the Twilio environment. However, it is important to protect the token generator function. If the Function URL leaks, an arbitrary caller should not be able to create a token and authenticate with it.
  • The JWT/JWE token is the authorization to use your Sync service instance (and thus, charge you for this usage). Please make sure that you secure it properly.

The Sync SDKs handle most of the lifecycle management for you automatically. This means that you do not need to specifically implement reconnection methods for network drops, nor manage the app switching between the foreground and background on an end user's device.

  • The Sync SDK operates by sending commands to the backend and receiving updates from the backend over an independent channel. Most asynchronous operations require the SDK to wait asynchronously for an update event before you can see the actual updated values.
  • There is no need to implement a shutdown/create cycle on network drops.
    • The Sync SDK reconnects automatically after regaining network access.
  • There is no need to implement a shutdown/create cycle when a Sync app goes to the background and returns to the foreground.
    • The SDK reconnects automatically to the websocket as soon as it becomes the foreground app.

The Sync TTL ("time-to-live") lifecycle

the-sync-ttl-time-to-live-lifecycle page anchor

The Sync TTL feature automatically handles storage cleanup for you. You don't have to remember Sync object SIDs (String Identifiers) and issue individual delete requests. After data that you've stored in Sync reaches the set TTL threshold, they will be deleted automatically.

  • We cannot guarantee the precise moment at which a Sync object will be deleted. Delete tasks run on the backend in an asynchronous manner and with limited capacity. We can only guarantee that the Sync object will be deleted eventually, so please plan accordingly.
  • If you need to hide expired items on some UI etc, it is possible to implement your own logic by filtering expired items by the date_expires attribute value. For example, let's say that you stored recent calls for the last 30 days in a Sync map for each agent, in order to power a dashboard. To remain GDPR-compliant, you could filter out all Maps items whose date_expires value has passed, as well as not show older calls to the agents.

Rate this page: