Class: Client

Client

Client for the Twilio Sync service.

new Twilio.Sync.Client(token [, options])

Parameters:
Name Type Argument Description
token String Twilio access token.
options Client#ClientOptions <optional>
Options to customize the Client.
Properties:
Name Type Description
connectionState Client#ConnectionState Contains current service connection state. Valid options are ['connecting', 'connected', 'disconnecting', 'disconnected', 'denied', 'error'].
Example
// Using NPM
var SyncClient = require('twilio-sync');
var syncClient = new SyncClient(token, { logLevel: 'debug' });

// Using CDN
var SyncClient = new Twilio.Sync.Client(token, { logLevel: 'debug' });

Members


<readonly> version :String

Current version of Sync client.
Type:
  • String

Methods


document( [arg])

Read or create a Sync Document.
Parameters:
Name Type Argument Description
arg String | Client#OpenOptions <optional>
One of:
  • Unique name or SID identifying a Sync Document - opens a Document with the given identifier or creates one if it does not exist.
  • none - creates a new Document with a randomly assigned SID and no unique name.
  • Client#OpenOptions object for more granular control.
  • Returns:
    a promise which resolves after the Document is successfully read (or created). This promise may reject if the Document could not be created or if this endpoint lacks the necessary permissions to access it.
    Type
    Promise.<Document>
    Example
    syncClient.document('MyDocument')
      .then(function(document) {
        console.log('Successfully opened a Document. SID: ' + document.sid);
        document.on('updated', function(event) {
          console.log('Received updated event: ', event);
        });
      })
      .catch(function(error) {
        console.log('Unexpected error', error);
      });

    list( [arg])

    Read or create a Sync List.
    Parameters:
    Name Type Argument Description
    arg String | Client#OpenOptions <optional>
    One of:
  • Unique name or SID identifying a Sync List - opens a List with the given identifier or creates one if it does not exist.
  • none - creates a new List with a randomly assigned SID and no unique name.
  • Client#OpenOptions object for more granular control.
  • Returns:
    a promise which resolves after the List is successfully read (or created). This promise may reject if the List could not be created or if this endpoint lacks the necessary permissions to access it.
    Type
    Promise.<List>
    Example
    syncClient.list('MyList')
      .then(function(list) {
        console.log('Successfully opened a List. SID: ' + list.sid);
        list.on('itemAdded', function(event) {
          console.log('Received itemAdded event: ', event);
        });
      })
      .catch(function(error) {
        console.log('Unexpected error', error);
      });

    map( [arg])

    Read or create a Sync Map.
    Parameters:
    Name Type Argument Description
    arg String | Client#OpenOptions <optional>
    One of:
  • Unique name or SID identifying a Sync Map - opens a Map with the given identifier or creates one if it does not exist.
  • none - creates a new Map with a randomly assigned SID and no unique name.
  • Client#OpenOptions object for more granular control.
  • Returns:
    a promise which resolves after the Map is successfully read (or created). This promise may reject if the Map could not be created or if this endpoint lacks the necessary permissions to access it.
    Type
    Promise.<Map>
    Example
    syncClient.map('MyMap')
      .then(function(map) {
        console.log('Successfully opened a Map. SID: ' + map.sid);
        map.on('itemUpdated', function(event) {
          console.log('Received itemUpdated event: ', event);
        });
      })
      .catch(function(error) {
        console.log('Unexpected error', error);
      });

    stream( [arg])

    Read or create a Sync Message Stream.
    Parameters:
    Name Type Argument Description
    arg String | Client#OpenOptions <optional>
    One of:
  • Unique name or SID identifying a Stream - opens a Stream with the given identifier or creates one if it does not exist.
  • none - creates a new Stream with a randomly assigned SID and no unique name.
  • Client#OpenOptions object for more granular control.
  • Returns:
    a promise which resolves after the Stream is successfully read (or created). The flow of messages will begin imminently (but not necessarily immediately) upon resolution. This promise may reject if the Stream could not be created or if this endpoint lacks the necessary permissions to access it.
    Type
    Promise.<Stream>
    Example
    syncClient.stream('MyStream')
      .then(function(stream) {
        console.log('Successfully opened a Message Stream. SID: ' + stream.sid);
        stream.on('messagePublished', function(event) {
          console.log('Received messagePublished event: ', event);
        });
      })
      .catch(function(error) {
        console.log('Unexpected error', error);
      });

    updateToken(token)

    Set new authentication token.
    Parameters:
    Name Type Description
    token String New token to set.
    Returns:
    Type
    Promise.<void>

    Type Definitions


    ClientOptions

    These options can be passed to Client constructor.
    Type:
    • Object
    Properties:
    Name Type Argument Default Description
    logLevel String <optional>
    'error' The level of logging to enable. Valid options (from strictest to broadest): ['silent', 'error', 'warn', 'info', 'debug', 'trace'].

    ConnectionState

    Indicates current state of connection between the client and Sync service.

    Valid options 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.
  • Type:
    • 'connecting' | 'connected' | 'disconnecting' | 'disconnected' | 'denied' | 'error'

    OpenOptions

    Options for opening a Sync Object.
    Type:
    • Object
    Properties:
    Name Type Argument Default Description
    id String <optional>
    Sync object SID or unique name.
    mode 'open_or_create' | 'open_existing' | 'create_new' <optional>
    'open_or_create' The 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.
  • ttl Number <optional>
    The time-to-live of the Sync object in seconds. This is applied only if the object is created.
    value Object <optional>
    { } The initial value for the Sync Document (only applicable to Documents).
    Example

    The following example is applicable to all Sync objects (i.e., syncClient.document(), syncClient.list(), syncClient.map(), syncClient.stream())

    // Attempts to open an existing Document with unique name 'MyDocument'
    // If no such Document exists, the promise is rejected
    syncClient.document({
        id: 'MyDocument',
        mode: 'open_existing'
      })
      .then(...)
      .catch(...);
    
    // Attempts to create a new Document with unique name 'MyDocument', TTL of 24 hours and initial value { name: 'John Smith' }
    // If such a Document already exists, the promise is rejected
    syncClient.document({
        id: 'MyDocument',
        mode: 'create_new',
        ttl: 86400
        value: { name: 'John Smith' } // the `value` property is only applicable for Documents
      })
      .then(...)
      .catch(...);

    Events


    connectionStateChanged

    Fired when connection state has been changed.
    Parameters:
    Name Type Description
    connectionState Client#ConnectionState Contains current service connection state.
    Example
    syncClient.on('connectionStateChanged', function(newState) {
      console.log('Received new connection state: ' + newState);
    });