Rate this page:

Sync SDK for JavaScript

Latest Release

During development at least, we recommend consuming the libraries linked here. These will automatically receive API-compatible improvements and bugfixes as we release

Sync SDK for JavaScript v0.12

Provides all the latest features of Twilio Sync in a single package. Available on our CDN in full source and minified variants. Documentation also available.

For use from within a browserified/web-packed code base, Sync is also published with to NPM. Use npm install --save twilio-sync to install the latest version.

Version History & Changelog

You will find links to specific patch versions here. We don't recommend using these links unless you have a specific need for a particular release version.

Sync SDK for Javascript v0.12.2 (April 27, 2020)

This release includes the following improvements:

  • Connection errors are reported with more details about what actually happened.
  • SDK type is now filled as “sync” to be compatible with mobile SDKs

Sync SDK for Javascript v0.12.1 (April 16, 2020)

This release includes the following improvements:

  • Logger name is now set to "twilio-sync"
  • Client metadata now gets filled if not provided by the user application to the Sync SDK
  • Added validation to the id attribute in OpenOptions to be a string
  • Added validation to ttl attribute in OpenOptions to be a number

Sync SDK for Javascript v0.12.0 (January 21, 2020)

This release includes the following feature:

  • LiveQuery can now automatically restore current state of the recordset after being offline for a short period of time. It's an internal functional change which requires no special adoption (no API compatibility issue whatsoever), but it might affect network traffic due to LiveQuery now fetching updates which could have happened while SDK was offline.

Sync SDK for Javascript v0.11.5 (November 21, 2019)

This release includes the following improvements:

  • Deleted legacy code to make event handling more clean and consistent with iOS and Android SDKs, a non-functional change.

Sync SDK for Javascript v0.11.4 (September 12, 2019)

This release includes the following improvements:

  • Fixed issues appearing in restrictive browser environments, enabling SDK operation without session storage.

Sync SDK for Javascript v0.11.2 (June 20, 2019)

This release includes the following improvements:

  • Introduced connectionError event.
  • Fixed a bug, where recovery after a partial network degradations did not resulted in the websocket reconnect.

Sync SDK for Javascript v0.11.1 (May 21, 2019)

This release includes the following improvements:

  • Removed a redundant external dependency ('backoff' package) and replaced it with 'operation-retrier' package, reducing the SDK footprint.
  • Fixed a bug, where the timed out requests were retried excessively, generating additional network traffic.

Sync SDK for Javascript v0.11.0 (May 10, 2019)

This release includes the following feature:

  • New close method has been introduced on every Sync primitive (Document, List, Map, Stream, LiveQuery). It can be called at any time to denote that the work on the Sync entity is concluded. Copies of the same Sync entity are refcounted and can be "closed" independently of one another. "Closed" Sync object accepts neither mutation operations nor service events. Once the last copy is closed, SDK unsubscribes from further service events pertaining to this Sync entity, which eventually stops the physical inflow of updates over the network.

Sync SDK for Javascript v0.10.4 (April 19, 2019)

This release mostly contains cosmetic changes (internal non-functional modifications) and cleanup activities, that is:

  • Removed two external dependencies: karibu and rfc6902.
  • Deleted legacy code, also reshuffled build scripts and code structure, a non-functional change.
  • Cleaned up documentation - no more references to private constructors.
  • Moved LiveQuery language documentation to a web page, hence a new link in Sync Client documentation that now points to it.

Sync SDK for Javascript v0.10.2 (March 29, 2019)

This release includes numerous bugfixes for the LiveQuery / InstantQuery objects that drive Flex:

  • Improved error reporting in case of incorrect query expression syntax.
  • Improved query parsing logic.
  • Reduced SDK size by moving some key functionality to the backend.
  • Integrated an updated version of websocket (Twilsock) library containing a fix for dropping timed out requests.

Sync SDK for Javascript v0.9.2 (February 15, 2019)

This release includes numerous bugfixes for the LiveQuery / InstantQuery objects that drive Flex:

  • Improved error reporting and handling in case of incorrect query expression syntax.
  • Added simple validation of indexName parameter passed to constructors.
  • Improved query parsing logic to detect invalid syntax better.
  • Minor updates to documentation.

Sync SDK for Javascript v0.9.1 (January 7, 2019)

In this release:

  • Added Client.liveQuery() method to fetch a recordset and subscribe to it using an SQL-like syntax, receiving updates matching this query in the future.
  • Added Client.instantQuery() method to fetch a recordset without subscribing to it

Note: these functions are only accessible to Flex developers, cannot be used on a regular Sync service instances.

Sync SDK for Javascript v0.8.6 (December 7, 2018)

In this release:

  • Fixed a connectivity bug that caused unhandled promise rejections.

Sync SDK for Javascript v0.8.5 (October 17, 2018)

In this release:

  • Integrating an updated version of websocket (Twilsock) library containing several fixes for reconnect issues on iOS.

Sync SDK for Javascript v0.8.4 (July 6, 2018)

In this release:

  • Fixed a syntax error which was causing applications with JS Sync SDK to crash in mobile browsers.

Sync SDK for Javascript v0.8.3 (June 25, 2018)

In this release:

  • Improve diagnostics, start adding timestamps to log lines.
  • Fix a transport bug where some of early requests could fail when sent before SDK initialization completes.

Sync SDK for Javascript v0.8.1 (May 21, 2018)

In this release:

  • Dramatically improved bandwidth use compared with previous versions ("Pre-authenticated Twilsock").
  • Knock-on performance improvements from more efficient bandwidth usage.
  • Removed HTTP fallback; all traffic is now directed over the websocket.
  • Introduced simplified terminal URL configuration. For traffic shaping, you can now control websocket termination with a stanza like the below:
    let sync = new SyncClient(token, {
        twilsock: { uri: 'wss://' }
  • Default logging level has been reduced to "silent". Override by supplying the logLevel option, e.g.
    let sync = new SyncClient(token, { logLevel: 'debug' });

Sync SDK for JavaScript v0.7.4 (January 16, 2017)

In this release:

  • Exposed dateUpdated attribute in Documents, Lists, Maps, and update it in browser session cache timely.

Sync SDK for JavaScript v0.7.2 (January 9, 2017)

In this release:

  • Fixed Map itemRemoved event payload for local events.
  • Improved SyncError exception description and logging.

Sync SDK for JavaScript v0.7.1 (December 21, 2017)

This release included only minor internal improvements and documentation clarifications.

Sync SDK for JavaScript v0.7.0 (November 27, 2017)

This release introduces some backwards incompatible changes. Please refer to more detailed release notes to help with migrating. In this release:

  • Provided more control over how SDK handles object opening and creation, via OpenOptions parameter.
  • Enabled configuring automatic garbage collection via TTL parameters for objects and collection items.
  • Removed document.get() method, use document.value instead.
  • Simplified emitted events, by combining local and remote events under the same name, differentiated by isLocal flag.
  • Renamed collectionRemoved event to removed.
  • Started automatically merging multiple state update events into single one, if they occur rapidly.
  • Fixed requested page size validation on the client side.
  • Made object subscription cancellation handling more robust.
  • Enabled returning null from mutator functions, gracefully abandoning data change operations.

Sync SDK for JavaScript v0.6.0 (September 15, 2017)

This release adds support for Message Streams with the Stream class.

Sync SDK for JavaScript v0.5.10 (August 21, 2017)

This release extends and improves on the API documentation of Sync Objects and the events they fire.

Sync SDK for JavaScript v0.5.9 (July 31, 2017)

In this release:

  • itemRemovedRemotely events now include the body of the removed item.
  • Internal improvements for resiliency.

Sync SDK for JavaScript v0.5.8 (June 19, 2017)

In this release:

  • An item-caching bug was fixed, in which the Sync SDK would diverge on very volatile objects
  • Internal retry handling was tweaked

Sync SDK for JavaScript v0.5.7 (May 31, 2017)

This release corrects a variety of issues in the .mutate() If-Match concurrency update functions. If you're using this feature on any Sync object this release is critical.

Sync SDK for JavaScript v0.5.6 (May 15, 2017)

This release corrects handling of non-alphanumeric map UniqueNames and map keys.

Sync SDK for JavaScript v0.5.5 (May 12, 2017)

This release includes improvements to connection recovery.

Sync SDK for JavaScript v0.5.4 (May 24, 2017)

This release includes improvements to performance over weak connections.

Sync SDK for JavaScript v0.5.3 (March 24, 2017)


  • You can now disable the Sync SDK's use of the session cache it with the below incantation. This may be useful if you need to conserve space.
new Twilio.Sync.Client(/* token */, { Sync: { enableSessionStorage: false } })

Bugs Addressed

  • [FIXED] Documents reverted to an old state if a browser tab was refreshed or clicked-through.
  • [FIXED] An object deleted on one SDK could somehow still be reconstituted on another client.
  • [FIXED] Map and List items were sometimes not properly deleted among collaborating Sync clients.

Sync SDK for JavaScript v0.5.1 (March 17, 2017)

This patch release fixes a bug in which the automated session cache became unreasonably stale, yielding extranneous update events on new pageloads. The cache should now be neatly updated on each pageload.

Sync SDK for JavaScript v0.5.0 (March 16, 2017)

New Features

  • Automatic Session Cache. This change brings dramatic speed increases for Sync re-initialization across page loads (e.g. if your user clicks through a link), particularly with many objects in play. No API change required.
  • Connection Recovery Efficiency. If the Twilsock connection should rupture, recovery of state upon reconnect is now dramatically more efficient. To a lesser extent, the same benefit should apply to cold starts (those not benefiting from the session cache), especially with many objects in play.
  • Token endpoint_id no longer required. It is no longer necessary to provide an endpoint_id field when minting your access tokens; Sync will automatically fingerprint a new endpoint in each browser tab. This change is backwards compatible: if you don't revise your backend code, the endpoint ID will simply be ignored.
  • Token Refresh Improved. Updating the token in your running Sync SDK will no longer cause a reconnect; the same connection will persist. Reachability webhooks, accordingly, will not fire on token refreshes.

Bug Fixes

  • A vexing bug rarely observed in Edge and Internet Explorer in which sync initialization failed silently has been squashed.
  • Handling of retries in the face of rate-limiting (HTTP 429) or overloads (HTTP 503) has been significantly improved.

Sync SDK for JavaScript v0.3.0 (Oct 25, 2016)

New Features

Breaking Change: Sync client constructor now expects the token directly, not an AccessManager. Example:

    syncClient = new Twilio.Sync.Client(tokenResponse.token);
  • Removes: AccessManager requirement. AccessManager is now only required for token lifecycle management, not for Sync client initialization.

Bug Fixes

  • Fixed bug where local connection state not always firing on connection state changes

Sync SDK for JavaScript v0.2.6 (Aug 15, 2016)

New Features

  • Adds: update method to documents, lists and maps. Method allows for convenient updating of specific keys in the JSON data stored in Sync.

Bug Fixes

  • N/A
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more