• Public
  • Public/Protected
  • All

Twilio Sync JavaScript client library

Twilio Sync is Twilio's state synchronization service, offering two-way real-time communication between browsers, mobiles, and the cloud. Visit our official site for more details: https://www.twilio.com/sync



npm install --save twilio-sync

Using this method, you can require twilio-sync.js like so:

var SyncClient = require('twilio-sync');
var syncClient = new SyncClient(token);


Releases of twilio-sync.js are hosted on a CDN, and you can include these directly in your web app using a <script> tag.

<script type="text/javascript" src="//media.twiliocdn.com/sdk/js/sync/v1.0/twilio-sync.min.js"></script>

Using this method, twilio-sync.js will set a browser global:

var syncClient = new Twilio.Sync.Client(token);


To use the library, you need to generate an Access Token and pass it to the Sync Client constructor. The Twilio SDK Starter applications for Node.js, Java, PHP, Ruby, Python, C# provide an easy way to set up a token generator locally. Alternatively, you can set up a Twilio Function based on the Sync Access Token template.

// Obtain a JWT access token: https://www.twilio.com/docs/sync/identity-and-access-tokens
var token = '<your-access-token-here>';
var syncClient = new Twilio.Sync.Client(token);

// Open a Document by unique name and update its data
  .then(function(document) {
    // Listen to updates on the Document
    document.on('updated', function(event) {
      console.log('Received Document update event. New data:', event.data);

    // Update the Document data
    var newData = { temperature: 23 };
    return document.set(newData);
  .then(function(updateResult) {
    console.log('The Document was successfully updated', updateResult)
  .catch(function(error) {
    console.error('Unexpected error', error)

For more code examples for Documents and other Sync objects, refer to the SDK API Docs:


See this link.




Renames and exports SyncClient


Renames and exports SyncClient

Type aliases


ConnectionState: TwilsockConnectionState

Client connection state. Directly reflects connection state of the underlying websocket transport. Possible values are as follows:

  • 'connecting' - client is offline and connection attempt is in process.
  • 'connected' - client is online and ready.
  • 'disconnecting' - client is going offline as disconnection is in process.
  • 'disconnected' - client is offline and no connection attempt is in process.
  • 'denied' - client connection is denied because of invalid JWT access token. User must refresh token in order to proceed.
  • 'error' - client connection is in a permanent erroneous state. Client re-initialization is required.


Mutator: (currentValue: Object) => Object

Type declaration

    • (currentValue: Object): Object
    • Applies a transformation to the data of a Sync entity. May be called multiple times on the same datum in case of collisions with remote code.


      • currentValue: Object

        Current data of the Sync entity in the cloud.

      Returns Object

      Desired new data for the item or null to gracefully cancel the mutation.


OpenMode: "open_or_create" | "open_existing" | "create_new"

Mode for opening the Sync object:

  • 'open_or_create' - reads a Sync object or creates one if it does not exist.
  • 'open_existing' - reads an existing Sync object. The promise is rejected if the object does not exist.
  • 'create_new' - creates a new Sync object. If the id property is specified, it will be used as the unique name.