API Docs for version 1.1.9500

Circuit JavaScript SDK

The Circuit JavaScript SDK can be used client-side as a regular JS API, or with node.js as server-side SDK.

If you don't have a developer account yet, get one for free. You will need an account to use the SDK.

The JS SDK supports OAuth 2.0. Register an app via the form on circuit.github.io.

JS SDK as well and node.js SDK examples are listed on circuit.github.io with its source code on github.
Also take a look at the Developer Portal to find out more about the Circuit SDK environment such as the REST API.

The entry point for the SDK documentation is the module Circuit with its main class Client.

Getting Started with the Client SDK
Getting Started with the node.js SDK
Change Log

Getting Started with the Client SDK

  1. Include the circuit.js file in your app by adding the line below to your HTML file.
    <script type="text/javascript" src="https://circuitsandbox.net/circuit.js"></script>
  2. In your application JavaScript file logon to Circuit and call APIs on the client instance.
    // Create Circuit client instance for OAuth 2.0 on the sandbox system
     var client = new Circuit.Client({
         client_id: '78cafde2f6854ad5ad80a67c532687bc',
         scope: 'READ_USER_PROFILE,READ_CONVERSATIONS',
         domain: 'circuitsandbox.net'
     });
    
     client.logon()
       .then(user => console.log('Logged on as ' + user.displayName))
       .then(client.addEventListener('itemAdded', item => console.log('itemAdded event received:', item)))
       .then(client.getConversations)
       .then(conversations => {
         console.log('Retrieved ' + conversations.length + ' conversations');
         return client.addTextItem(conversations[0].convId, 'Hello World');
       })
       .then(item => console.log('Msg sent on ' + (new Date(item.creationTime)).toString()))
       .catch(console.error);

Examples can be found on circuit.github.io.

Only modern browsers are supported. Edge does not have WebRTC support. IE is not supported.

Getting Started with the node.js SDK

The node.js SDK is a simple wrapper around the JS SDK and therefore exposes identical APIs to the Client SDK.

  1. Install node.js
  2. Get the Circuit npm module here
  3. Install the module via npm install ./circuit.tgz
  4. Create an index.js file with following content:
    // Load the circuit module
     var Circuit = require('circuit')
    
     // Instantiate a client for OAuth2 (Client Credentials Grant)
     var client = new Circuit.Client({
         client_id: '78cafde2f6854ad5ad80a67c532687bc',
         client_secret: 'ddfe13d8785b479dbb93dacf00ea83f0',
         domain: 'circuitsandbox.net'
     })
    
     client.logon()
       .then(user => console.log('Logged on user:', user))
       .catch(console.error)
  5. Run the app via node index.js

View the node.js examples on circuit.github.io, specifically these might be interesting:

  • node-sdk-example: This example shows how to logon to circuit, register for events, lookup a conversation, send a message, attach files to a message, send a comment.
  • node-linkify: Web server app to modify text messages on behalf of a user. Uses OAuth2 REST API and JavaScript SDK.
  • xlator-bot: This sample application shows how to listen to text messages, translate them using google-translate and reply to the message with the tranlsated text.

Change Log

Version 1.1.6700, 2016-07-08

  • Addedclient.toggleMediastream to send an arbitrary MediaStream such as from a Canvas.

Version 1.1.5600

  • Removeduser.smallImageUri and user.largeImageUri. Added user.hasAvatar.
  • Replaceduser.roles with user.userState of type UserState
  • Support running SDK and Circuit webclient in the same browser instance by using sdk prefix in domain in client configuration. (sdk.circuitsandbox.net)
  • Initiate a Circuit call from the Circuit webclient viaclient.sendClickToCallRequest
  • Get a list of your own logged on devices viaclient.getDevices
  • Get/set user settings (share location, presence opt out) viaclient.setUserSettings and client.getUserSettings
  • Get/set status message viaclient.setStatusMessage andclient.getStatusMessage
  • Get conversation details and regenerate PIN viaclient.getConversationDetails andclient.changeConversationPin
  • Renamed eventuserSettingsUpdated to userSettingsChanged
  • Match SDK version wth Circuit client version

Version 1.1.5600 update 1

  • Dial a phone number. This requires the telephony connector to be configured. API: client.dialNumber(number, name)
    codepen example
  • Send DTMF digits on an active telephony call. API: client.sendDigits(callId, digits)
  • Get the telephony UP/DOWN status. API: client.getTelephonyData()
  • Firefox 42+ and IE11+ support (no RTC with IE yet)

Version 1.1.7500

  • Send arbitrary MediaStream on an existing call. Useful for sending a MediaStream captured via the HTMLCanvasElement.captureStream API. API: client.toggleMediaStream(callId, stream)
  • OAuth2 support. Portal to create an app to get the client ID and secret is not available yet. In the meantime the system admin can create applications using the command line.
    Initiating OAuth login via: client.logon()
    For details on usage see Circuit.Client constructor and client.logon method.
    Codepen example coming soon
  • Remove IE support. IE was not supporting WebRTC on the SDK anyways and we plan to support WebRTC with Edge soon.

Version 1.1.7700

  • While in a RTC session, dial-out a PSTN number or a Circuit user: client.addParticipantToCall(callId, obj)
  • Live examples now on circuit.github.io.

Version 1.1.7700 update 1

  • accessToken getter/setter: var token = client.accessToken
  • OAuth2 logon with accessToken: client.logon({accessToken: <accessToken>})
  • OAuth2 client credentials logon (used for bots): client.logon({client_id: <client_id>, client_secret: <client_secret>})
  • OAuth2 token validation API: client.validateToken()

Version 1.1.9400

  • Support for incoming ATC calls with new APIs:
    getAtcCalls getAnswerDevices getCallDevices getPushDevices
    Requires Circuit.client options enableTelephony