- Developer account on circuitsandbox.net. Get it for free at developer registration.
- OAuth 2.0
client_id
and optionallyclient_secret
. Get if for free at circuit.github.com/oauth.
https://circuitsandbox.net/sdk/ with most APIs described in the Client class.
More info at circuit.github.io.
Add the the line below to the HTML file of your app. This will include the latest version of Circuit SDK and make the Circuit
object available.
<script type="text/javascript" src="https://unpkg.com/circuit-sdk"></script>
npm install --save circuit-sdk
The majority of apps fall in one of the three types below. Each type uses a different OAuth 2.0 Grant.
-
Client-side web applications use the JavaScript SDK with the OAuth 2.0 Implicit Grant.
// No client_secret needed for Implicit Grant. SDK will obtain access token. let client = new Circuit.Client({ client_id: '<your client_id>', domain: 'circuitsandbox.net' }); client.logon() .then(user => console.log('Logged on as ' + user.displayName))
-
Server-side web applications use the JavaScript SDK (or REST API) on the client, but handle the authentication flow on the server using the OAuth 2.0 Authorization Code Grant. The access token is obtained on the server and then passed to the client to use in the Circuit JavaScript SDK. These apps may also use the Node.js SDK on the server side to act on behalf of the user.
Example apps: node-linkify or circuit-google-assistant// access token is obtained and managed by server-side app let client = new Circuit.Client({ client_id: '<your client_id>', domain: 'circuitsandbox.net' }); client.logon({accessToken: '<access_token>'}) .then(user => console.log('Logged on as ' + user.displayName))
-
Bots use the Node.js SDK or the REST API and use the OAuth 2.0 Client Credentials Grant. Bots are a special type of user; they don't login on behalf of a regular user, hence no OAuth popup asking for a user`s credentials and permissions.
Example bots: xlator-bot or node-sdk-example
Example electron bots: webrtc-bot-example or live-cam-botconst Circuit = require('circuit-sdk'); let client = new Circuit.Client({ client_id: '<client_id>', client_secret: '<client_secret>', domain: 'circuitsandbox.net' }); client.logon() .then(user => console.log('Logged on as bot: ' + user.emailAddress))
JavaScript examples are located at /examples/js with more examples on jsbin.
Node.js example apps are on github. A summary is listed here. Runkit allows playing with Node.js modules live, similar to jsbin or jsfiddle on the client. Try it on runkit
Here are some snippets to get you started.
Logon as bot, create a group conversation with two users and send a text message.
client.logon()
.then(user => console.log(`Logged on as ${user.displayName}`, user))
.then(() => client.getUsersByEmail(['kim.jackson@mailinator.com', 'maeva.barnaby@mailinator.com']))
.then(users => users.map(user => user.userId))
.then(userIds => client.createGroupConversation(userIds, 'runkit example'))
.then(conv => client.addTextItem(conv.convId, 'I am test bot. What can I do for you?'))
.then(client.logout)
.catch(console.error)
Get 10 newest conversations of logged on user.
client.getConversations({numberOfConversations: 10})
.then(conversations => console.log(`Retrieved ${conversations.length} conversations`))
Start a video call with another user. Create conversation if not yet existing.
Only applicable to JavaScript SDK and only on browsers supporting WebRTC
client.makeCall('bob@company.com', {audio: true, video: true}, true)
.then(call => console.log('New call: ', call));
// Register new items added to the feed of this user. E.g. incoming text message
client.addEventListener('itemAdded', item =>
console.log('itemAdded event received:', item));
// Register for connection state changes
client.addEventListener('connectionStateChanged', evt => {
console.log(`New state is ${evt.state}`);
});
// Register and log all events
Circuit.supportedEvents.forEach(e => client.addEventListener(e, console.log));
Injectors allow extending the conversation, item and user objects within the SDK.
In this example a new attribute teaser
is created on the item object. This teaser
will be added to item objects in any reponse or event from the SDK.
Circuit.Injectors.itemInjector = function (item) {
if (item.type === Circuit.Enums.ConversationItemType.TEXT) {
// Create item.teaser attribute with replacing br and hr tags with a space
item.teaser = item.text.content.replace(/<(br[\/]?|\/li|hr[\/]?)>/gi, ' ');
} else {
item.teaser = item.type;
}
};
Chrome and Firefox are officially supported.
Help us improve the SDK or examples by sending us a pull-request or opening a GitHub Issue.