API Docs for version 1.3.1803

Client

Module: Circuit

Summary

This is the main class of the Circuit module and is the entry point for all APIs.

An application creates a Client instance on which the logon is performend. After a successful logon, the other APIs on the client instance can be called. Event listeners are also exposed on the Client instance.

Most applications will only require a single Client instance. node.js applications might need to impersonate multiple users, so the app can simply create multiple client instances. Events are raised to the correct instance.

Constructor

Client

Syntax

Client

(
  • config
)

Summary

Parameters:

  • config Object

    Object literal containing configuration parameters

    • [client_id] String optional

      The OAuth2 client ID you obtain from the Developer Portal. Identifies the client that is making the request.

    • [client_secret] String optional

      The OAuth2 client secret you obtain from the Developer Portal. Applicable for client credentials grant type used for node.js apps.

    • [scope] String optional

      Comma-delimited set of permissions that the application requests. Values: READ_USER_PROFILE,WRITE_USER_PROFILE,READ_CONVERSATIONS,WRITE_CONVERSATIONS,READ_USER,CALL_RECORDING,CALLS,MENTION_EVENT,USER_MANAGEMENT, MANAGE_CONVERSATIONS,CREATE_CONVERSATIONS_CONTENT,DELETE_CONVERSATIONS_CONTENT,UPDATE_CONVERSATION_CONTENT,MANAGE_PRESENCE,MODERATE_CONVERSATIONS, ORGANIZE_CONVERSATIONS,SEARCH_CONVERSATIONS,USER_TO_USER

    • [autoRenewToken=false] Boolean optional

      Applicable to Client Credentials Grant only. If set to true, the OAuth2 access token is automatically renewed prior to expiry.

    • [domain='circuitsandbox.net'] String optional

      The domain of the Circuit server to use. Defaults to circuitsandbox.net.

    • [enableTelephony=false] Boolean optional

      Set to true to register for support incoming telephony calls. Requires 'calls' scope and a configured telephony connector for the tenant.

    • [emoticonMode='standard'] String optional

      standard or circuit. In standard mode the Circuit encoding is converted to standard unicode.

    • [removeMentionHtml=false] Boolean optional

      If true span element for mention is removed and only the mentioned user's name is shown.

    • [redirect_uri] String optional

      Optional. URL to redirect to upon successfull OAuth. Prevents unnesecarry rendering or parent page URL in OAuth popup.

Item Index

Methods

Methods

addAppMessageListener

Syntax

addAppMessageListener

(
  • type
  • cb
)
Void

Summary

Add listener for messages sent via sendAppMessageToUser or sendAppMessageToClient.

Required OAuth2 scopes: USER_TO_USER

Parameters:

  • type String

    Type

  • cb Function

    Callback with message and routing information.

Returns:

Void:

Example:

client.addAppMessageListener('channel1', (msg, routing) => {
  console.log(Message received, msg);
});

addEventListener

Syntax

addEventListener

(
  • type
)
Function

Summary

Register for Circuit events such as new a new message, incoming call, connection state change, etc.

Parameters:

  • type String

    Event type such as itemAdded

Returns:

Function:

callback See event definition on parameter(s) of callback function

Example:

// Register for new conversation items added to the feed (e.g. a new message)
client.addEventListener('itemAdded', evt => console.log('Item added:', evt.item);

// Register for connection state changes. E.g. connection going down and re-connecting
client.addEventListener('connectionStateChanged', function (evt) {
    console.log('Received connectionStateChanged event. state: ', evt.state)
});

addLabels

Syntax

addLabels

(
  • labels
)
Promise | Label

Summary

Creates one or more new labels.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • labels String[]

    Array of strings containing the names of the labels.

Returns:

Promise | Label:

A promise returning an array new labels.

Example:

client.addLabels(['My new label', 'Antoher new label'])
  .then(labels => console.log(Created ${labels.length} new labels));

addParticipant

Syntax

addParticipant

(
  • convId
  • userIds
  • [addToCall]
)
Promise

Summary

Add new participants to a group conversation or community.

Required OAuth2 scopes: WRITE_CONVERSATIONS or MANAGE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • userIds String[]

    Single user ID or array of User IDs

  • [addToCall] Boolean optional

    If set while a call is ongoing, added users are alerted

Returns:

Promise:

A promise with the conversation, or the new conversation in case a new conversation was created

Example:

client.addParticipant('8fc29770-84ab-4ace-9e85-3269de707499', ['874c528c-1410-4362-b519-6e7d26a2edb2'])
  .then(() => console.log('Successfully added'));

addParticipantToCall

Syntax

addParticipantToCall

(
  • callId
  • to
)
Promise

Summary

Add a participant to a call via dial out. The participant does not have to be a member of the conversation. Dialing PSTN number is also supported.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call.

  • to Object

    Object literal containing dial out information

    • [userId] String optional

      userId of participant to add to call. For a PSTN call the userId may be omitted.

    • [email] String optional

      email of participant to add to call. Omitted if userId is present. For a PSTN call the email may be omitted.

    • [number] String optional

      Phone number to dial. Not applicable to WebRTC dial-out.

    • [displayName] String optional

      Display name of user to dial. Not applicable to WebRTC dial-out.

Returns:

Promise:

A promise that is resolved when the user id dialed out.

Example:

// Call via PSTN number
client.addParticipantToCall('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', {number: '+15615551234', displayName: 'Bob Jones'})
.then(() => console.log('Success'));

// Or using the userID
client.addParticipantToCall('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', {userId: '56497aa7-5421-48e1-9069-2e8d3b12f778'});

addParticipantToRtcSession

Syntax

addParticipantToRtcSession

(
  • callId
  • to
)
Promise

Summary

Add a participant to an RTC Session via dial out. Unlike addParticipantToCall this API does not rely on a local call to be present. The participant does not have to be a member of the conversation. Dialing PSTN number is also supported.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call.

  • to Object

    Object literal containing dial out information

    • [userId] String optional

      userId of participant to add to call. For a PSTN call the userId may be omitted.

    • [email] String optional

      email of participant to add to call. Omitted if userId is present. For a PSTN call the email may be omitted.

    • [number] String optional

      Phone number to dial. Not applicable to WebRTC dial-out.

    • [displayName] String optional

      Display name of user to dial. Not applicable to WebRTC dial-out.

Returns:

Promise:

A promise that is resolved when the user id dialed out.

Example:

client.addParticipantToRtcSession('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', {number: '+15615551234', displayName: 'Bob Jones'})
  .then(() => console.log('Success'));

client.addParticipantToRtcSession('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', {userId: '56497aa7-5421-48e1-9069-2e8d3b12f778'})
  .then(() => console.log('Success'));

addTextItem

Syntax

addTextItem

(
  • convId
  • content
)
Promise | Item

Summary

Send a new text message with optional attachments and URL previews. This API accepts a single string with the text message, or an object literal with the text item attributes.
RICH text supports Bold, Italic, Highlight, Bullet, Numbering, Emojii, Hyperlink and Mention. The formatting is:
Bold: <b>Bold</b>
Italic: <i>Italic</i>
Highlight: <span class="rich-text-highlight">Highlight</span>
Bullets: <ul><li>Bullet</li></ul>
Numbering: <ol><li>Numbering</li></ol>
Emojii: Encoding at emoji-one site &#128526;
Hyperlink: <a href="https://github.com/circuit">Circuit on github</a>
Mention: <@0e372ae0-2dff-4439-8f87-1b8a6562f80e>, can you come over?
Mention (custom name): <span class="mention" abbr="0e372ae0-2dff-4439-8f87-1b8a6562f80e">@Roger</span>, can you come over?

Required OAuth2 scopes: WRITE_CONVERSATIONS or CREATE_CONVERSATIONS_CONTENT. READ_USER if using mentions.

Parameters:

  • convId String

    Conversation ID

  • content Object | String

    Content for text message. Either an object literal, or a string.

Returns:

Promise | Item:

A promise returning a the item added.

Example:

var content = {
    subject: 'Message with attachment',
    content: 'Hello <b>World</b>',
    contentType: Circuit.Enums.TextItemContentType.RICH,
    attachments: [new File(['file 1'], 'testfile.txt', {type: 'text/plain', lastModified: Date.now()})]
}
await client.addTextItem('e8b72e0e-d2d1-46da-9ed4-737875931440', content);

// Alternate API to send a text message.
await client.addTextItem('e8b72e0e-d2d1-46da-9ed4-737875931440', 'Hello World');

// Example content for mentioning a user by its userId which will be replace with user's display name.
content = '<@0e372ae0-2dff-4439-8f87-1b8a6562f80e>, call me'

// Example content for mentioning a user with only firstname. The abbr tad contains the userId of the mentioned user.
content = '<span class="mention" abbr="0e372ae0-2dff-4439-8f87-1b8a6562f80e">@Roger</span>, call me'

// Example hyperlink
content = 'Check out http://circuit.com or <a href="http://github.com/circuit">Circuit on github</a>'

// Example content for an emojii
content = 'Encoding at emojione.com &#128526;';

addWhiteboardElement

Syntax

addWhiteboardElement

(
  • callId
  • xmlElement
)
Promise

Summary

Add a whiteboard element (e.g. circle, line, freehand) to the whiteboard.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call.

  • xmlElement String

    SVG XML representation of the element. (Any JavaScript will be removed).

Returns:

Promise:

A promise that is resolved when the drawing has been sent to the peers.

Example:

client.addWhiteboardElement('8f365bf3-97ea-4d54-acc7-2c4801337521',

. '') .then(() => console.log('Successfully added whiteboarding element'));

answerCall

Syntax

answerCall

(
  • callId
  • mediaType
  • device
)
Promise

Summary

Answer an incoming call received in a callIncoming event.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to answer.

  • mediaType Object

    Object with boolean attributes: audio, video, desktop

  • device String

    Device to answer the call with. Use getAnswerDevices to list devices. By default call is answered via WebRTC.

Returns:

Promise:

A promise that is resolved when the call is answered.

Example:

client.answerCall('8f365bf3-97ea-4d54-acc7-2c4801337521', {audio: true, video: false})
  .then(() => console.log('The call has been answered'));

archiveConversation

Syntax

archiveConversation

(
  • convId
)
Promise

Summary

Archive a conversation. Succeeds if conversation is already archived.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

Returns:

Promise:

A promise without data

Example:

client.archiveConversation('d353db50-b835-483e-9fce-2b157b2253d3')
  .then(() => console.log('Conversation archived'));

assignLabels

Syntax

assignLabels

(
  • convId
  • labelIds
)
Promise | String[]

Summary

Assigns specified labels to the given conversation.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • convId String

    Id of which conversation labels should be added to.

  • labelIds String[]

    Array of label Ids to be added to the conversation.

Returns:

Promise | String[]:

A promise returning an array of label Ids assigned to the conversation.

Example:

client.assignLabels('d353db50-b835-483e-9fce-2b157b2253d3', ['146d546c-5012-4db4-a867-215e4c8cdb30', '398473a0-c39f-46af-884f-4e8a0e88c4d1'])
  .then(labels => console.log(${labels.length} labels are assigned to the conversation.));

cancelSearch

Syntax

cancelSearch

(
  • searchId
)
Promise

Summary

Cancel a pending search. E.g. startBasicSearch, startUserSearch

Required OAuth2 scopes: READ_USER, READ_CONVERSATIONS, or SEARCH_CONVERSATIONS

Parameters:

  • searchId String

    Search ID of the pending search

Returns:

Promise:

A promise without data

Example:

client.cancelSearch('c4cbbf23-cdcd-4824-881d-fea0c77c8f50')
  .then(() => console.log('Search cancelled');

changeConversationPin

Syntax

changeConversationPin

(
  • conversation
)
Promise | ConversationDetails

Summary

Change the PIN of a conversation.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • conversation String

    Conversation ID

Returns:

Promise | ConversationDetails:

A promise returning the conversation details with the new PIN and Guest link.

Example:

client.changeConversationPin('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
  .then(convDetails => console.log('Pin changed. Conversation details: ', convDetails));

changeHDVideo

Syntax

changeHDVideo

(
  • callId
  • hdQuality
  • resolution
)
Promise

Summary

Change the video resolution of an established call from SD to HD, or from HD to SD. If the call is already in HD mode, use changeVideoResolution to change from one HD resolution to another.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call.

  • hdQuality Boolean

    true to enable streaming HD quality up to 1920x1080.

  • resolution VideoResolutionLevel

    Video resolution, defaults to 1080p.

Returns:

Promise:

A promise that is resolved when action is complete.

Example:

client.changeHDVideo('8f365bf3-97ea-4d54-acc7-2c4801337521', true)
  .then(() => console.log('Successful'));

changePassword

Syntax

changePassword

() Promise

Summary

Change the password of the current user. Will popup password change page. Fires passwordChanged event.

Required OAuth2 scopes: WRITE_USER_PROFILE

Returns:

Promise:

A promise without data

Example:

client.changePassword()
  .then(() => console.log('Successfully changed password'));

changeVideoResolution

Syntax

changeVideoResolution

(
  • callId
  • resolution
)
Promise

Summary

Change the video resolution of an established call. Unlike changeHDVideo this API allows changing the HD resolution if already in an HD call.

Required OAuth2 scopes: CALLS

Parameters:

Returns:

Promise:

A promise that is resolved when action is complete.

Example:

client.changeVideoResolution('8f365bf3-97ea-4d54-acc7-2c4801337521', Circuit.Enums.VideoResolutionLevel.VIDEO_720)
  .then(() => console.log('Successful'));

clearWhiteboard

Syntax

clearWhiteboard

(
  • callId
  • [userId]
  • [preserveBackground]
)
Promise

Summary

Clear a whiteboard.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call.

  • [userId] String optional

    If set only elements of the given user are removed.

  • [preserveBackground] Boolean optional

    If true the background will be preserved

Returns:

Promise:

A promise that is resolved when the action has completed.

Example:

client.clearWhiteboard('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(() => console.log('Successfully cleared whiteboard'));

clearWhiteboardBackground

Syntax

clearWhiteboardBackground

(
  • callId
)
Promise

Summary

Clear the background of the whiteboard.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call.

Returns:

Promise:

A promise without data.

Example:

client.clearWhiteboardBackground('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(() => console.log('Successfully cleared the background'));

createCommunity

Syntax

createCommunity

(
  • [participants]
  • [topic]
  • [description]
)
Promise | Conversation

Summary

Create a new community.

Required OAuth2 scopes: WRITE_CONVERSATIONS or MANAGE_CONVERSATIONS

Parameters:

  • [participants] String[] optional

    User ID's of the users to create a community with

  • [topic] String optional

    Topic of community

  • [description] String optional

    Description of the community

Returns:

Promise | Conversation:

A promise returning the created community

Example:

client.createCommunity(null, 'Kiteboarding', 'Discuss best kiteboarding spots in Canada')
  .then(conv => console.log(Community created, conv));

createConferenceBridge

Syntax

createConferenceBridge

(
  • topic
)
Promise | Conversation

Summary

Create a new conference bridge conversation.
Requires the following scope: WRITE_CONVERSATIONS

Required OAuth2 scopes: WRITE_CONVERSATIONS or MANAGE_CONVERSATIONS

Parameters:

  • topic String

    Topic of conversation

Returns:

Promise | Conversation:

A promise returning the created conversation

Example:

client.createConferenceBridge('Sales Call')
  .then(conv => console.log(Conversation created, conv));

createDirectConversation

Syntax

createDirectConversation

(
  • participant
)
Promise | Object

Summary

Create a new direct conversation.
Requires the following scope: WRITE_CONVERSATIONS

Required OAuth2 scopes: WRITE_CONVERSATIONS or MANAGE_CONVERSATIONS

Parameters:

  • participant String

    User ID or email of the user to create a conversation with

Returns:

Promise | Object:

A promise returning an object with the conversation, and an alreadyExists boolean

Example:

client.createDirectConversation('bob@example.com')
  .then(res => {
    let str = res.alreadyExists ? 'already exists' : 'is new';
    console.log(Conversation ${str}, res.conversation);
  });

createGroupConversation

Syntax

createGroupConversation

(
  • [participants]
  • [topic]
)
Promise | Conversation

Summary

Create a new group conversation.
Requires the following scope: WRITE_CONVERSATIONS

Required OAuth2 scopes: WRITE_CONVERSATIONS or MANAGE_CONVERSATIONS

Parameters:

  • [participants] String[] optional

    User ID's of the users to create a conversation with

  • [topic] String optional

    Topic of conversation

Returns:

Promise | Conversation:

A promise returning the created conversation

Example:

client.createGroupConversation(['176f65ce-7bb2-4a35-9030-45cd9b09b512', '4dccc4a2-e6f0-4e58-afb2-5a3f9a00ee05'])
  .then(conv => console.log(Conversation created, conv));

createIncomingWebhook

Syntax

createIncomingWebhook

(
  • newWebhookData
)
Promise | IncomingWebhook

Summary

Creates a new webhook for a conversation.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • newWebhookData Object
    • conversationId String

      Id of the conversation to create the webhook for.

    • [userId] String optional

      Id of the user to create webhook for, if user is a bot.

    • [name] String optional

      Name of webhook.

    • [description] String optional

      Description of webhook.

Returns:

Promise | IncomingWebhook:

A promise returning an incoming webhook

Example:

 client.createIncomingWebhook({
         conversationId: 'b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a',
         userId: 'e8b72e0e-d2d1-46da-9ed4-7378759314488',
         name: 'NewWebhook',
         description: 'This is an new webhook.',
     })
     .then(webhook => console.log('Incoming Webhook:', webhook))
     .catch(console.error);

deleteIncomingWebhook

Syntax

deleteIncomingWebhook

(
  • webhookId
)
Promise

Summary

Deletes a webhook.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • webhookId String

    Id of the webhook to be deleted.

Returns:

Promise:

A promise without data

Example:

 client.deleteIncomingWebhook('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
     .then(() => console.log('Webhook deleted.'))
     .catch(console.error);

deleteRecording

Syntax

deleteRecording

(
  • Item
)
Promise

Summary

Delete a recording.

Required OAuth2 scopes: WRITE_CONVERSATIONS, DELETE_CONVERSATIONS_CONTENT, or CALL_RECORDING

Parameters:

  • Item String

    ID of item to remove the recording from.

Returns:

Promise:

A promise that is resolved when recording has been deleted.

Example:

client.deleteRecording('cc02d9ca-fb10-4a86-96b3-0198665525b8')
  .then(() => console.log('Successfully deleted recording'));

deleteTextItem

Syntax

deleteTextItem

(
  • itemId
)
Promise | Item

Summary

Delete a text item.

Required OAuth2 scopes: WRITE_CONVERSATIONS

Parameters:

  • itemId String

    Conversation Item ID of item to delete.

Returns:

Promise | Item:

A promise returning the item.

Example:

 const itemId = 'e8b72e0e-d2d1-46da-9ed4-7378759314488';
client.deleteTextItem(itemId)
  .then(console.log);

dialNumber

Syntax

dialNumber

(
  • number
  • [name]
)
Promise | Call

Summary

Start a telephony call from this client.

Required OAuth2 scopes: CALLS

Parameters:

  • number String

    Dialable number. Must match Circuit.Utils.PHONE_PATTERN.

  • [name] String optional

    Display name of number being dialed.

Returns:

Promise | Call:

A promise returning the created call.

Example:

client.dialNumber('+15615551111', 'Bob Smith')
  .then(call => console.log('New telephony call: ', call));

disableGuestAccess

Syntax

disableGuestAccess

(
  • convId
)
Promise

Summary

Disable guest access on a conversation.

Required OAuth2 scopes: WRITE_CONVERSATION or MODERATE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID.

Returns:

Promise:

A promise without data.

Example:

client.disableGuestAccess('338d2002-ae68-495c-aa5c-1dff3fbc845a')
  .then(() => console.log('Successfully disabled guest access'));

disableWhiteboard

Syntax

disableWhiteboard

(
  • callId
)
Promise

Summary

Disable the whiteboard feature on an active RTC call/conference.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call.

Returns:

Promise:

A promise that is resolved when the feature is disabled.

Example:

client.disableWhiteboard('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(() => console.log('Successfully disabled whiteboarding for this call'));

dropModeratorRights

Syntax

dropModeratorRights

(
  • convId
  • userId
)
Promise

Summary

Drop moderator rights to participants.

Required OAuth2 scopes: WRITE_CONVERSATION or MODERATE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID.

  • userId String

    User that gets moderator rights removed.

Returns:

Promise:

A promise without data.

Example:

client.dropModeratorRights('338d2002-ae68-495c-aa5c-1dff3fbc845a', '874c528c-1410-4362-b519-6e7d26a2edb2')
  .then(() => console.log('Successfully removed moderation rights'));

dropParticipant

Syntax

dropParticipant

(
  • callId
  • userId
)
Promise

Summary

Remove participant of a group call.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID.

  • userId String

    User ID of the participant to remove from the call.

Returns:

Promise:

A promise that is resolved when the participant has been removed.

Example:

client.dropParticipant('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', '874c528c-1410-4362-b519-6e7d26a2edb2')
  .then(() => console.log('Successfully dropped participant'));

editLabel

Syntax

editLabel

(
  • label
)
Promise | Label

Summary

Edit a given label.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • label Label

    Label object containing the labelId and name of the Label.

Returns:

Promise | Label:

A promise returning the edited label.

Example:

client.editLabel({
     labelId: 'd353db50-b835-483e-9fce-2b157b2253d3',
     value: 'My new label'
   })
  .then(label => console.log(Label: ${label.value}));

enableGuestAccess

Syntax

enableGuestAccess

(
  • convId
)
Promise

Summary

Enable guest access on a conversation.

Required OAuth2 scopes: WRITE_CONVERSATION or MODERATE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID.

Returns:

Promise:

A promise without data.

Example:

client.enableGuestAccess('338d2002-ae68-495c-aa5c-1dff3fbc845a')
  .then(() => console.log('Successfully enabled guest access'));

enableWhiteboard

Syntax

enableWhiteboard

(
  • callId
  • viewbox
)
Promise

Summary

Enable the whiteboard feature on an active RTC call/conference.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call.

  • viewbox Viewbox

    The viewbox of the SVG root element. This will allow the clients to transform their canvas into the used SVG coordinate system.

Returns:

Promise:

A promise that is resolved when the feature is enabled.

Example:

client.enableWhiteboard('8f365bf3-97ea-4d54-acc7-2c4801337521', { width: 800, height: 400 })
  .then(() => console.log('Successfully enabled whiteboarding for this call'));

endCall

Syntax

endCall

(
  • callId
)
Promise

Summary

End a direct call or leave a group conference.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to end.

Returns:

Promise:

A promise that is resolved when the call is ended.

Example:

client.endCall('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(() => console.log('The call has been ended'));

endConference

Syntax

endConference

(
  • callId
)
Promise

Summary

End a conference call. Disconnects all other participants as well.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to leave.

Returns:

Promise:

A promise that is resolved when the conference has ended.

Example:

client.endConference('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
  .then(call => console.log('Successfully ended conference'));

endRemoteCall

Syntax

endRemoteCall

(
  • callId
)
Promise

Summary

End a remote call.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to end.

Returns:

Promise:

A promise that is resolved when the call has been ended.

Example:

client.endRemoteCall('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
  .then(() => console.log('Successfully ended the remote call'));

favoriteConversation

Syntax

favoriteConversation

(
  • convId
)
Promise

Summary

Add a conversation to the favorite list. Succeeds if conversation is already favorited.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

Returns:

Promise:

A promise without data

Example:

client.favoriteConversation('d353db50-b835-483e-9fce-2b157b2253d3')
  .then(() => console.log('Conversation added to favorites'));

findCall

Syntax

findCall

(
  • callId
)
Promise | Call

Summary

Find a call by its call ID. Call may be local or remote, active or non-active.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to find.

Returns:

Promise | Call:

A promise returning the call.

Example:

client.findCall('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
  .then(call => console.log('Call found: ', call));

flagItem

Syntax

flagItem

(
  • convId
  • itemId
)
Promise

Summary

Flag an item. Flags are user specific.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • itemId String

    Item ID of item to be flagged

Returns:

Promise:

A promise without data

Example:

client.flagItem('8fc29770-84ab-4ace-9e85-3269de707499', '874c528c-1410-4362-b519-6e7d26a2edb2')
  .then(() => console.log('Successfully flagged'));

getAccounts

Syntax

getAccounts

(
  • [options]
)
Promise | User[]

Summary

Get the accounts, including users for this tenant/domain. This API requires tenant admin priviledges.

Required OAuth2 scopes: USER_MANAGEMENT tenant administrators have the user management permission by default

Parameters:

  • [options] Object optional

    Literal object with filter options

    • [pageSize] String optional

      Page size. Default is 25. Maximum is 100.

    • [sorting] String optional

      Sorting as defined in Circuit.Enums.GetAccountsSorting. Default is BY_FIRST_NAME

    • [ordering] String optional

      Ordering as defined in Circuit.Enums.SortOrder. Default is ASCENDING

    • [searchPointer] String optional

      Transparent string required to retrieve next results page

    • [searchCriterias] Array optional

      Array of literal objects for optional search criterias

    • [searchCriterias[].criteria] String optional

      Criteria as defined in Circuit.Enums.GetAccountsFilterCriteria

    • [searchCriterias[].value] String optional

      Criteria value, e.g. "Rog"

Returns:

Promise | User[]:

A promise that returns an object with hasMore boolean, searchPointer and accounts. Each account contains an account and user object.

Example:

client.getAccounts({
  pageSize: 50,
  sorting: Circuit.Enums.GetAccountsSorting.BY_LAST_NAME,
  ordering: Circuit.Enums.SortOrder.DESCENDING,
  searchCriterias: [{
    criteria: Circuit.Enums.GetAccountsFilterCriteria.FIRST_NAME,
    value: 'Ro'
  }]
})
  .then(res => console.log('First batch of accounts', res.accounts));

getActiveCall

Syntax

getActiveCall

() Promise | Call

Summary

Get local active call.

Required OAuth2 scopes: CALLS

Returns:

Promise | Call:

A promise returning the local active call.

Example:

client.getActiveCall()
  .then(call => console.log('Active local call: ', call));

getActiveRemoteCalls

Syntax

getActiveRemoteCalls

() Promise | Call[]

Summary

Get remote active calls.

Required OAuth2 scopes: CALLS

Returns:

Promise | Call[]:

A promise returning an array of remote active calls.

Example:

client.getActiveRemoteCalls()
  .then(calls => console.log(Active remote calls: ${calls.length}));

getAllLabels

Syntax

getAllLabels

() Promise | Object

Summary

Retrieve all labels.

Required OAuth2 scopes: READ_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Returns:

Promise | Object:

A promise returning a list of label objects.

Example:

client.getAllLabels()
  .then(labels => console.log(Found: ${labels.length} labels));

getArchivedConversations

Syntax

getArchivedConversations

(
  • [options]
)
Promise

Summary

Retrieve archived conversations

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • [options] Object optional

    Object literal containing paging and other options

    • [number] Number optional

      Maximum number of conversations to retrieve. Default is 10.

    • [timestamp] Number optional

      Conversations created before this timestamp are returned. Used for paging.

    • [numberOfParticipants] Number optional

      Maximum number of participants to return in the participants array. Default is 8.

Returns:

Promise:

A promise returning a list of archived conversations

Example:

client.getArchivedConversations({number: 10})
  .then(convs => console.log(Found: ${convs.length} conversations));

getAudioVideoStats

Syntax

getAudioVideoStats

() Promise

Summary

The original WebRTC PeerConnection getStats API for the active, local Audio/Video PeerConnection, returning RTCStatsReport. Note that Chrome and Firefox return a different RTCStatsReport object. Check the browser. See https://www.chromestatus.com/feature/5665052275245056 and https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport. Calling this API more than once every 5 seconds will affect the performance. For a simpler, normalized API use the preferred client.getLastRtpStats API instead.

Required OAuth2 scopes: CALLS

Returns:

Promise:

A Promise containing RTCStatsReport object when successful

Example:

client.getAudioVideoStats()
  .then(stats => stats.forEach(console.log))
  .catch(console.error);

getCalls

Syntax

getCalls

() Promise | Call[]

Summary

Get all local and remote calls in progress.

Required OAuth2 scopes: CALLS

Returns:

Promise | Call[]:

A promise returning an array of local and remote calls in progress.

Example:

client.getCalls()
  .then(calls => console.log(Calls in progress: ${calls.length}));

getConferenceInvitationText

Syntax

getConferenceInvitationText

(
  • locale
  • convId
)
Promise | String

Summary

Get the conference invitation HTML

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • locale String

    Locale/language to retrieve the text for as defined in Circuit.Contants.LOCALE. Defaults to EN_US

  • convId String

    Conversation ID

Returns:

Promise | String:

A promise returning a string containing the HTML of the conference invitation

Example:

client.getConferenceInvitationText('EN_US', 'b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
  .then(conferenceText => console.log('Conference Text: ', conferenceText));

getConversationById

Syntax

getConversationById

(
  • convId
)
Promise | Conversation

Summary

Retrieve a single conversations by its ID.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

Returns:

Promise | Conversation:

A promise returning a conversation

Example:

client.getConversationById('d353db50-b835-483e-9fce-2b157b2253d3')
  .then(conversation => console.log('Returned conversation: ', conversation));

getConversationDetails

Syntax

getConversationDetails

(
  • conversation
)
Promise | ConversationDetails

Summary

Get the conversation details such as the bridge numbers and guest link.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • conversation String

    Conversation ID

Returns:

Promise | ConversationDetails:

A promise returning the conversation details.

Example:

client.getConversationDetails('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
  .then(convDetails => console.log('Conversation details: ', convDetails));

getConversationFeed

Syntax

getConversationFeed

(
  • convId
  • [options]
)
Promise | Item,hasOlderThreads

Summary

Retrieve items of a conversation in a threaded structure before a specific timestamp. Allows specifying how many comments per thread to retrieve, and also how many unread messages of a thread to retrieve.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • [options] Object optional

    Object literal containing options

    • [timestamp] Number optional

      Defines a date to compare with the last creation date of an item (direction is always BEFORE). If no timestamp is provided, the current time is used.

    • [minTotalItems] Number optional

      Minimum number of comments to retrieve. Defaults to 25.

    • [maxTotalUnread] Number optional

      Maximum number of unread items to retrieve. Defaults to 500.

    • [commentsPerThread] Number optional

      Minimum number of comments per thread (up to 3) to retrieve. Defaults to 3.

    • [maxUnreadPerThread] Number optional

      Maximum number of unread comments per thread to retrieve. Defaults to 50.

Returns:

Promise | Item,hasOlderThreads:

A promise returning an object with an array of threads and a boolean indicating whether there are more older threads.

Example:

client.getConversationFeed('d353db50-b835-483e-9fce-2b157b2253d3')
  .then(res => console.log(Returned ${res.threads.length} threads));

getConversationItems

Syntax

getConversationItems

(
  • convId
  • [options]
)
Promise | Item[]

Summary

Retrieve multiple conversation items. By default the most recent items are returned.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • [options] Object optional

    Object literal containing options

    • [modificationDate] Number optional

      Mutually exclusive with creationDate. Defaults to current timestamp.

    • [creationDate] Number optional

      Mutually exclusive with modificationDate. Defaults to current timestamp.

    • [direction] SearchDirection optional

      Whether to get items BEFORE or AFTER a certain timestamp. Default is BEFORE.

    • [numberOfItems] Number optional

      Maximum number of conversation items to retrieve. Default 25.

Returns:

Promise | Item[]:

A promise returning an array of Items

Example:

client.getConversationItems('cc02d9ca-fb10-4a86-96b3-0198665525b8', {direction: 'AFTER'})
  .then(items => console.log(Returned ${items.length} items));

getConversationParticipants

Syntax

getConversationParticipants

(
  • convId
  • [options]
)
Promise | ConversationParticipantResult

Summary

Retrieve conversation participants using optional search criteria. Resulting objects are participant objects, not user objects. Also returns a searchPointer for next page and a boolean whether there are more participants.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • [options] Object optional

    Object literal containing options

    • [searchCriterias] ParticipantSearchCriteria[] optional

      A list of search criterias that are used to filter the participants. Criterias are using an AND operation.

    • [searchPointer] String optional

      Used for paging of results. Each results page returns a searchPointer that is to be used to fetch the next page.

    • [pageSize] Number optional

      Number of participants per page. Maximum is 100.

    • [includePresence] Boolean optional

      If set to true this will add the presence state of the user to the returned participant object. Default is false.

Returns:

Promise | ConversationParticipantResult:

A promise returning conversation participants.

Example:

client.getConversationParticipants('d353db50-b835-483e-9fce-2b157b2253d3', {pageSize: 50, includePresence: true})
  .then(res => console.log(Returned ${res.participants.length} participants));

getConversations

Syntax

getConversations

(
  • [options]
)
Promise | Conversations

Summary

Retrieve conversations.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • [options] Object optional

    Object literal containing options

    • [direction] SearchDirection optional

      Defines the direction of the search, i.e. get conversation BEFORE or AFTER a timestamp. If no direction is set but a timestamp the direction is set to BEFORE.

    • [timestamp] Number optional

      Timestamp used in conjunction with the direction parameter. Default is no timestamp, causing most recent conversations to be returned.

    • [numberOfConversations] Number optional

      Maximum number of conversations to retrieve. Default is 25.

    • [numberOfParticipants] Number optional

      Maximum number of participants to return in the participants array. Default is 8.

Returns:

Promise | Conversations:

A promise returning an array of Conversations.

Example:

client.getConversations({numberOfConversations: 10})
  .then(conversations => console.log(Returned ${conversations.length} conversations));

getConversationsByFilter

Syntax

getConversationsByFilter

(
  • [options]
)
Promise

Summary

Retrieve conversations or conversation IDs by a filter. A filter contains conditions specifying one or more labels or archived/muted indication.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • [options] Object optional

    Object literal containing filter parameters

    • [filterConnector] FilterConnector optional

      Object defining the filter criteria. Required.

    • [number] Number optional

      Maximum number of conversations to retrieve. Default is 10.

    • [timestamp] Number optional

      Conversations created before this timestamp are returned. Used for paging.

    • [numberOfParticipants] Number optional

      Maximum number of participants to return in the participants array. Default is 8.

    • [retrieveAction] RetrieveAction optional

      Influences the data returned. Conversations (with paging support) or all Conversation IDs. Defaults to CONVERSATIONS.

Returns:

Promise:

A promise returning a list of conversations, or conversation IDs.

Example:

client.getConversationsByFilter({
  filterConnector: {
    conditions: [{
      filterTarget: 'LABEL_ID',
      expectedValue: ['d353db50-b835-483e-9fce-2b157b2253d3']
    }]
  },
  number: 25,
  retrieveAction: Circuit.Enums.RetrieveAction.CONVERSATIONS
})
  .then(convs => console.log(Found: ${convs.length} archived conversations));

getConversationsByIds

Syntax

getConversationsByIds

(
  • convIds
)
Promise | Conversation[]

Summary

Retrieve conversations by their IDs.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • convIds Array

    Array of Conversation IDs

Returns:

Promise | Conversation[]:

A promise returning an array of conversation objects

Example:

client.getConversationsByIds(['d353db50-b835-483e-9fce-2b157b2253d3', '9721646e-850d-426f-a300-bbbed97024aa'])
  .then(conversations => console.log(conversations));

getConversationsByLabel

Syntax

getConversationsByLabel

(
  • labelId
  • [options]
)
Promise

Summary

Retrieve conversations with a specified label

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • labelId String

    Label ID

  • [options] Object optional

    Object literal containing paging and other options

    • [number] Number optional

      Maximum number of conversations to retrieve. Default is 10.

    • [timestamp] Number optional

      Conversations created before this timestamp are returned. Used for paging.

    • [numberOfParticipants] Number optional

      Maximum number of participants to return in the participants array. Default is 8.

Returns:

Promise:

A promise returning a list of conversations with that label

Example:

client.getConversationsByLabel('d353db50-b835-483e-9fce-2b157b2253d3, {numberOfParticipants: 3})
  .then(convs => console.log(Found: ${convs.length} conversations));

getConversationsByType

Syntax

getConversationsByType

(
  • conversationType
  • [options]
)
Promise

Summary

Retrieve conversations with a specified type

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • conversationType ConversationType

    Type of conversations to retrieve.

  • [options] Object optional

    Object literal containing paging and other options

    • [number] Number optional

      Maximum number of conversations to retrieve. Default is 25.

    • [timestamp] Number optional

      Conversations created before this timestamp are returned. Used for paging.

    • [numberOfParticipants] Number optional

      Maximum number of participants to return in the participants array. Default is 8.

Returns:

Promise:

A promise returning a list of conversations with that type.

Example:

client.getConversationsByType(Circuit.Enums.ConversationType.DIRECT, {number: 10})
  .then(convs => console.log(Returned: ${convs.length} conversations));

getConversationTopics

Syntax

getConversationTopics

(
  • convId
  • [options]
)
Promise | ConversationTopicResult

Summary

Retrieve conversation topics.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • [options] Object optional

    Object literal containing options

    • [timestamp] Number optional

      Timestamp used to search BEFORE.

    • [maxNumberOfTopics] Number optional

      Maximum number of topics to return.

Returns:

Promise | ConversationTopicResult:

A promise returning conversation topics.

Example:

client.getConversationTopics('1bf601e2-affc-4869-9b05-3715b5bb4751', {maxNumberOfTopics: 10})
  .then(res => console.log(Returned ${res.conversationTopics.length} topics and the conversation does ${res.hasOlderTopics ? '' : 'not'} have older topics.));

getCookie

Syntax

getCookie

() String

Summary

Get the authentication cookie.

Returns:

String:

cookie

Example:

let cookie = client.getCookie();

getDevices

Syntax

getDevices

() Promise | Device[]

Summary

Retrieve devices the user is logged in with.

Required OAuth2 scopes: READ_CONVERSATIONS or READ_USER_PROFILE

Returns:

Promise | Device[]:

A promise that returns the array of devices

Example:

client.getDevices()
  .then(devices => console.log('Device count: ', devices.length));

getDirectConversationWithUser

Syntax

getDirectConversationWithUser

(
  • query
  • [createIfNotExists]
)
Promise | Conversation

Summary

Get the direct conversation with a user by its user ID or email address. Note that adding a user to a direct conversation creates a new conversation with all 3 participants. The reason for that is because in Circuit direct conversations are private and stay private.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • query String

    User ID or email address

  • [createIfNotExists] Boolean optional

    Create conversation with user if not already existing. Default is false.

Returns:

Promise | Conversation:

A promise returning a the conversation

Example:

client.getDirectConversationWithUser('bob@unify.com')
  .then(console.log);

getFavoriteConversationIds

Syntax

getFavoriteConversationIds

() Promise | Object

Summary

Retrieve favorited conversation IDs.

Required OAuth2 scopes: READ_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Returns:

Promise | Object:

A promise returning an object with a list of favorited conversation IDs.

Example:

client.getFavoriteConversationIds()
  .then(favoriteConvIds => console.log(Favs: ${favoriteConvIds.length}));

getFlaggedItems

Syntax

getFlaggedItems

() Promise | ConversationFlaggedItems[]

Summary

Get all flagged items.

Required OAuth2 scopes: READ_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Returns:

Promise | ConversationFlaggedItems[]:

A promise with an array of objects containing the flagged info

Example:

client.getFlaggedItems()
  .then(res => console.log(${res.length} conversations with flagged items));

getIncomingWebhook

Syntax

getIncomingWebhook

(
  • webhookId
)
Promise | IncomingWebhook

Summary

Get a webhook by its ID.

Required OAuth2 scopes: READ_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • webhookId String

    Id of the webhook to be retrieved.

Returns:

Promise | IncomingWebhook:

A promise returning an incoming webhook

Example:

 client.getIncomingWebhook('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
     .then(webhook => console.log('Webhook:', webhook))
     .catch(console.error);

getIncomingWebhooks

Syntax

getIncomingWebhooks

(
  • searchCondition
)
Promise | GetIncomingWebhooksResult

Summary

Returns webhooks for a tenant, user, or conversation based on what type of Id is passed. One of the types of Ids are required.

Required OAuth2 scopes: READ_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • searchCondition Object
    • pageSize String

      The maximum number of returned incoming webhooks. This field is limited to 100. If the page size is larger the backend will reduce the size to 100. Note: One of the following search Ids is required for this API.

    • [tenantId] String optional

      Id of the tenant to return webhooks for.

    • [userId] String optional

      Id of the user to return webhooks for.

    • [conversationId] String optional

      Id of the conversation to return webhooks for.

    • [searchPointer] String optional

      The search pointer used for paging.

Returns:

Promise | GetIncomingWebhooksResult:

A promise returning GetIncomingWebhooksResult

Example:

 client.getIncomingWebhooks({ conversationId: 'b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', pageSize: 5 })
     .then(res => console.log('The results of this search for this conversation is:', res))
     .catch(console.error);

getItemById

Syntax

getItemById

(
  • itemId
)
Promise | Item

Summary

Retrieve a single conversation item by its ID.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • itemId String

    Conversation Item ID

Returns:

Promise | Item:

A promise returning an item

Example:

client.getItemById('cc02d9ca-fb10-4a86-96b3-0198665525b8')
  .then(console.log);

getItemsById

Syntax

getItemsById

(
  • itemIds
)
Promise | Item[]

Summary

Retrieve multiple conversation items by their ID.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • itemIds String[]

    Conversation Item IDs

Returns:

Promise | Item[]:

A promise returning an array of items

Example:

client.getItemsById(['cc02d9ca-fb10-4a86-96b3-0198665525b8'])
  .then(console.log);

getItemsByThread

Syntax

getItemsByThread

(
  • convId
  • threadId
  • [options]
)
Promise | Item,hasMore

Summary

Retrieve conversation items of a thread, not including the parent item.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • threadId String

    Thread ID

  • [options] Object optional

    Object literal containing options

    • [modificationDate] Number optional

      Defines a date to compare with the last modification date of an item. Defaults to current timestamp. Mutually exclusive with creationDate. Usually used to retrieve the new items in a thread after last cached item.

    • [creationDate] Number optional

      Defines a date to compare with the creation date of an item. Defaults to current timestamp. Mutually exclusive with modificationDate. Usually used to retrieve older items in a thread, e.g. fetch previous 25 items.

    • [direction] SearchDirection optional

      Whether to get items BEFORE or AFTER a certain timestamp.

    • [number] Number optional

      Maximum number of conversation items to retrieve. Default (-1) is to retrieve all items of a thread.

Returns:

Promise | Item,hasMore:

A promise returning an object with an array of items and a boolean indicating if there are more items.

Example:

client.getItemsByThread('d353db50-b835-483e-9fce-2b157b2253d3', 'e8b72e0e-d2d1-46da-9ed4-737875931440')
  .then(res => console.log(Returned all ${res.items.length} items of this thread));

getJournalEntries

Syntax

getJournalEntries

(
  • [options]
)
Promise | Item[]

Summary

Retrieve telephony call journals of logged on user.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • [options] Object optional
    • [journalFilter] JournalFilter optional

      filter constraints used for what to retrieve. Defaults to ALL.

    • [timestamp] Boolean optional

      Timestamp used in conjunction with the direction parameter. Default is no timestamp, causing most recent conversations to be returned.

    • [direction] String optional

      Whether to get items BEFORE or AFTER a certain timestamp. Default is BEFORE.

    • [numberOfEntries] String optional

      Number of entries to retrieve.

Returns:

Promise | Item[]:

A promise returning the item.

Example:

client.getJournalEntries({ journalFilter: Circuit.Enums.JournalFilter.VOICEMAILS })
.then(voicemails => console.log(There are ${voicemails.length} voicemails));

getLastRtpStats

Syntax

getLastRtpStats

(
  • callId
)
RTCStatsReport

Summary

Get the RTP call statistics of the last stats collection interval (every 5 sec by default)

Required OAuth2 scopes: CALLS

Parameters:

Returns:

RTCStatsReport:

An array of RTP stats, or for the new format a map of ID and RtpStats.

Example:

var stats = client.getLastRtpStats('8f365bf3-97ea-4d54-acc7-2c4801337521');

getLocalAudioVideoStream

Syntax

getLocalAudioVideoStream

() Promise

Summary

Get the local video stream (audio/video)

Required OAuth2 scopes: CALLS

Returns:

Promise:

A promise containing the MediaStream

Example:

client.getLocalAudioVideoStream()
  .then(stream => console.log(stream));

getLocalScreenshareStream

Syntax

getLocalScreenshareStream

() Promise

Summary

Get the local video stream for the screenshare.

Required OAuth2 scopes: CALLS

Returns:

Promise:

A promise containing the MediaStream

Example:

client.getLocalScreenshareStream()
  .then(stream => console.log(stream));

getLoggedOnUser

Syntax

getLoggedOnUser

() Promise | User

Summary

Get the logged on user.

Required OAuth2 scopes: READ_USER_PROFILE

Returns:

Promise | User:

A promise that returns the logged on user

Example:

client.getLoggedOnUser()
  .then(user => console.log('Client is authenticated: ' + user.displayName));

getMarkedConversations

Syntax

getMarkedConversations

() Promise | Object deprecated

Summary

Retrieve all marked (muted and favorited) conversation IDs.

Required OAuth2 scopes: READ_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Returns:

Promise | Object:

A promise returning an object with a list of favorited conversation IDs and a list of muted conversation IDs.

Example:

client.getMarkedConversations()
  .then(res => console.log(Muted: ${res.mutedConvIds.length}, Favs: ${res.favoriteConvIds.length}));

getMaxVideoResolution

Syntax

getMaxVideoResolution

(
  • deviceId
)
Promise

Summary

Get the maximum video resolution supported on the provided video input device (camera). API requires permissions to access the camera. Camera indicator will turn on for a split second. API cannot be called when already accessing the camera. Resolutions tested as FHD (1080p), HD (720p) and VGA.

Required OAuth2 scopes: CALLS

Parameters:

  • deviceId String

    device ID obtained via navigator.mediaDevices.enumerateDevices().

Returns:

Promise:

A promise containing the resolution (Circuit.Enums.VideoResolution)

Example:

client.getMaxVideoResolution('97cbef604ce613e5a024f66b5b7c1ced3cd854b1dd132a2729dd0d2f62558956')
  .then(resolution => console.log('Max resolution is' + resolution));

getPresence

Syntax

getPresence

(
  • userIds
  • [full]
)
Promise | Presence

Summary

Get the presence for a list of user IDs.

Required OAuth2 scopes: READ_USER

Parameters:

  • userIds String

    List of user IDs

  • [full] Boolean optional

    If true, detailed presence is retrurned which also includes long/lat, timezone, etc

Returns:

Promise | Presence:

A promise returning an array of Presence objects

Example:

client.getPresence(['72ee640f-9ac3-4275-b9ec-46d08e499c5a'])
  .then(presenceList => console.log('Presence objects for requested users: ', presenceList));

getRemoteStreams

Syntax

getRemoteStreams

(
  • callId
)
MediaStream[]

Summary

Get the remote (receiving) media streams (audio, video and screenshare). For group calls there is one audio stream and 4 video streams. Not all streams may have audio/video tracks. For direct calls there is a single stream with audio and possibly video tracks.

Required OAuth2 scopes: CALLS

Parameters:

Returns:

MediaStream[]:

An array of MediaStream objects. Returns null is call is not present.

Example:

var audioStream = client.getRemoteStreams(callId).find(s => s.getAudioTracks().length > 0);

getStartedCalls

Syntax

getStartedCalls

() Promise | Call[]

Summary

Get calls in Started state, meaning the conference has started but the user has not yet joined.

Required OAuth2 scopes: CALLS

Returns:

Promise | Call[]:

A promise returning an array of started calls.

Example:

client.getStartedCalls()
  .then(calls => console.log(Started calls: ${calls.length}));

getStatusMessage

Syntax

getStatusMessage

()

Summary

Get the status message of the logged on user.

Required OAuth2 scopes: READ_USER_PROFILE

Returns:

Promise A promise containing the status message

Example:

client.getStatusMessage()
  .then(statusMessage => console.log('Status message is: ', statusMessage));

getSupportConversation

Syntax

getSupportConversation

() Promise | Conversation

Summary

Get the special support conversation. The support conversation is a special conversation the user can report problems with. Server will create one if not existing.

Required OAuth2 scopes: READ_CONVERSATIONS

Returns:

Promise | Conversation:

A promise returning a conversation

Example:

client.getSupportConversation()
  .then(conversation => console.log('Returned conversation: ', conversation));

getSupportConversationId

Syntax

getSupportConversationId

() String

Summary

Get the special support conversation ID. The support conversation is a special conversation the user can report problems with.

Required OAuth2 scopes: WRITE_CONVERSATIONS or READ_CONVERSATIONS

Returns:

String:

Support Conversation ID

Example:

client.getSupportConversationId()
  .then(convId => console.log('Support Conversation ID: ' + convId));

getSupportInfo

Syntax

getSupportInfo

() SupportInfo

Summary

Get the tenant settings supportInfo. The support info is the tenant settings defining how the user get support

Required OAuth2 scopes: READ_USER_PROFILE

Returns:

SupportInfo:

Support Info object

Example:

client.getSupportInfo()
  .then(supportInfo => console.log('Support Info: ' + supportInfo));

getTelephonyConversationId

Syntax

getTelephonyConversationId

() String

Summary

Get the special telephony conversation ID. The telephony conversation is a special conversation the user has in case the tenant is enabled for telephony.

Required OAuth2 scopes: READ_CONVERSATIONS

Returns:

String:

Telephony Conversation ID

Example:

client.getTelephonyConversationId()
  .then(convId => console.log('Telephony Conversation ID: ' + convId));

getTelephonyData

Syntax

getTelephonyData

() Promise | Object

Summary

Get the telephony data such as the connection state and default caller ID.

Required OAuth2 scopes: CALLS

Returns:

Promise | Object:

A promise returning the telephony data object.

Example:

client.getTelephonyData()
  .then(console.log);

getTenantUsers

Syntax

getTenantUsers

(
  • [options]
)
Promise | User[] deprecated

Summary

Get the users for this tenant/domain. This API requires tenant admin priviledges.

Required OAuth2 scopes: USER_MANAGEMENT tenant administrators have the user management permission by default

Parameters:

  • [options] Object optional

    Literal object with filter options

    • [pageSize] String optional

      Page size. Default is 25.

    • [sorting] String optional

      Sorting as defined in Constants.GetAccountsSorting. Default is BY_FIRST_NAME

Returns:

Promise | User[]:

A promise that returns an array of users

Example:

client.getTenantUsers({pageSize: 10, sorting: Constants.GetAccountsSorting.BY_LAST_NAME})
  .then(users => console.log('First batch of users', users));

getUserByEmail

Syntax

getUserByEmail

(
  • [email]
  • [filter]
)
Promise | User

Summary

Retrieve a user by its email.

Required OAuth2 scopes: READ_USER

Parameters:

  • [email] String optional

    Email address to search. Returns complete user objects.

  • [filter] Object optional

    Mutually exclusive with email parameter

    • emailAddresses String[]

      Email addresses to search

    • [complete=true] Boolean optional

      Set to true to return complete set of attributes

    • [secondaryLookup=false] Boolean optional

      Set to true to also lookup by alternate emails

Returns:

Promise | User:

A promise that returns the user

Example:

const user = await client.getUserByEmail({
  emailAddress: 'bob@example.com',
  secondaryLookup: true
});

const user = await client.getUserByEmail('bob@example.com');

getUserById

Syntax

getUserById

(
  • userId
)
Promise | User

Summary

Retrieve user by its ID.

Required OAuth2 scopes: READ_USER

Parameters:

Returns:

Promise | User:

A promise that returns the user

Example:

client.getUserById('d353db50-b835-483e-9fce-2b157b2253d3')
  .then(user => console.log('User is:', user));

getUsersByEmail

Syntax

getUsersByEmail

(
  • [emails]
  • [filter]
)
Promise | User[]

Summary

Retrieve users by their email address.

Required OAuth2 scopes: READ_USER

Parameters:

  • [emails] String[] optional

    Email addresses to search

  • [filter] Object optional

    Mutually exclusive with emails parameter

    • emailAddresses String[]

      Email addresses to search

    • [complete=true] Boolean optional

      Set to true to return complete set of attributes

    • [secondaryLookup=false] Boolean optional

      Set to true to also lookup by alternate emails

Returns:

Promise | User[]:

A promise that returns the array of users

Example:

const users = await client.getUsersByEmail(['bob@unify.com', 'alice@unify.com']);

const users = await client.getUsersByEmail({
  emailAddresses: ['bob@unify.com', 'alice@unify.com'],
  complete: true,
  secondaryLookup: true
});

getUsersById

Syntax

getUsersById

(
  • userIds
  • [limited]
)
Promise | User[]

Summary

Retrieve users by their ID.

Required OAuth2 scopes: READ_USER

Parameters:

  • userIds String[]

    Array of User IDs

  • [limited] Boolean optional

    If true, a limited user object is retrurned with the most important attributes. Default is false.

Returns:

Promise | User[]:

A promise that returns the array of users

Example:

client.getUsersById(['d353db50-b835-483e-9fce-2b157b2253d3'])
  .then(users => console.log('Users are:', users));

getUserSettings

Syntax

getUserSettings

()

Summary

Get all user settings of the logged on user.

Required OAuth2 scopes: READ_USER_PROFILE

Returns:

Promise A promise returning the UserSettings object on success

Example:

client.getUserSettings()
  .then(userSettings => console.log('userSettings are: ', userSettings));

getWhiteboard

Syntax

getWhiteboard

(
  • callId
)
Promise | Whiteboard

Summary

Get the complete whiteboard drawing.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call.

Returns:

Promise | Whiteboard:

A promise containing the whiteboard drawing.

Example:

client.getWhiteboard('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(board => console.log('Successfully retrieved the whiteboard'));

grantModeratorRights

Syntax

grantModeratorRights

(
  • convId
  • userId
)
Promise

Summary

Grant moderator rights to participants.

Required OAuth2 scopes: WRITE_CONVERSATION or MODERATE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID.

  • userId String

    User that gets moderator rights.

Returns:

Promise:

A promise without data.

Example:

client.grantModeratorRights('338d2002-ae68-495c-aa5c-1dff3fbc845a', '874c528c-1410-4362-b519-6e7d26a2edb2')
  .then(() => console.log('Successfully granted moderation rights'));

isAuthenticated

Syntax

isAuthenticated

()

Summary

Check if the client is already authenticated and has a valid session.

Returns:

Promise A promise without data

Example:

client.isAuthenticated()
  .then(() => console.log('Client is authenticated'));
  .catch(err => console.error('Client is not authenticated', err));

isCompatible

Syntax

isCompatible

() Boolean

Summary

Check if browser is compatible. Use supports API for supported features on the current browser.

Returns:

Boolean:

true if browser is compatible

joinCommunity

Syntax

joinCommunity

(
  • convId
)
Promise | Conversation

Summary

Join a community.

Required OAuth2 scopes: WRITE_CONVERSATIONS or MANAGE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

Returns:

Promise | Conversation:

A promise returning the joined community

Example:

client.joinCommunity('35fefd79-6a56-49fd-b585-9a0373253eeb')
  .then(community => console.log(Joined community: , community));

joinConference

Syntax

joinConference

(
  • callId
  • mediaType
  • [clientId]
)
Promise

Summary

Join a conference call from the current device, or optionally from another logged on device.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to join.

  • mediaType MediaType

    Media type for the call.

  • [clientId] String optional

    clientId of device where to join the call from

Returns:

Promise:

A promise that is resolved when the call is joined.

Example:

client.joinConference('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', {audio: true, video: false})
  .then(() => console.log('Successfully joined the call'));

leaveConference

Syntax

leaveConference

(
  • callId
)
Promise

Summary

Leave a conference call.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to leave.

Returns:

Promise:

A promise that is resolved when leaving the call is successful.

Example:

client.leaveConference('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
  .then(call => console.log('Successfully left the call'));

likeItem

Syntax

likeItem

(
  • itemId
)
Promise

Summary

Like an item. Likes will be seen by others.

Required OAuth2 scopes: WRITE_CONVERSATIONS or UPDATE_CONVERSATION_CONTENT

Parameters:

  • itemId String

    Item ID of item to be liked

Returns:

Promise:

A promise without data

Example:

client.likeItem('874c528c-1410-4362-b519-6e7d26a2edb2')
  .then(() => console.log('Successfully liked item'));

logon

Syntax

logon

(
  • [options]
)
Promise | User

Summary

Logon to Circuit using OAuth2.
Not providing any parameters will popup the OAuth2 window unless recently logged in which case the SDK will have remembered the OAuth2 token.
If the app already has an OAuth2 access token (e.g. via using the REST API), then the token can be passed in as accessToken.
OAuth2 supported grant types by the SDK:

  • Implicit Grant - usually used in client-side web apps running in browsers
  • Client Credentials Grant - usually used for node.js bots

Parameters:

  • [options] Object optional

    Optional object with OAuth2 access token, or API token

    • [accessToken] String optional

      OAuth2 access token

    • [prompt] String optional

      If set to true, then when passing an accessToken without a valid session, then a logon popup is shown. Not applicable for node.js

    • [logonChecked] String optional

      If set to true, then no OAuth popup is shown and instead an exception is thrown if authentication session or token is invalid. Only applicable for implicit grant.

    • [skipTokenValidation] String optional

      If set to true, then the app is responsible to obtain and validate access token. Used for native apps like Ionic.

    • [username] String optional

      Username (email) for Resource Owner Grant Type

    • [password] String optional

      Password for Resource Owner Grant Type

    • [token] String optional

      API token (deprecated)

Returns:

Promise | User:

A promise that returns the logged on user in case of success

Example:

// OAuth2 logon - Implicit Grant or Client Credentials Grant
// This implies the client_id (and client_secret for Client Credentials Grant) is provided
// to the Circuit.client constructor.
client.logon()
.then(user => console.log(Authenticated as ${user.displayName}))
.catch(console.error);

// OAuth2 accessToken logon. The SDK stores the accessToken in localStorage, so this API
// should not be needed in regular use cases.
client.logon({accessToken: 'f75ae5b43ab2499a9b9aba460915ef11', prompt: true})
.then(user => console.log(Authenticated as ${user.displayName}))

// OAuth2 Resource Owner Grant Type logon. This grant type should only be used if other flows
// are not viable. Also, it should only be used if the application is trusted by the user
// (e.g. it is owned by the service, or the user's desktop OS), so not in a browser.
client.logon({username: 'bob@example.com', password: 'P@ssw0rd'})
.then(user => console.log(Authenticated as ${user.displayName}))

// API token logon (deprecated, replaced by OAuth2 Client Credentials Grant)
client.logon({token: 'Ifa20af19c21d16a182256620a'})
.then(user => console.log(Authenticated as ${user.displayName}))

logonCheck

Syntax

logonCheck

() Promise

Summary

Checks whether the logon will succeed, meaning a valid token is in localStorage and a valid authentication sesssion is active. This API is useful for auto-logon attempts on page load. The logon API needs to be called within 5 seconds of a successful logonCheck call. If the logonCheck is unsuccessful the app can show a login button. Due to browser security a page load cannot trigger a new popup window to be opened, hence this API.

Returns:

Promise:

A promise without data

Example:

client.logonCheck()
  .then(() => console.log('Ready to call logon even on a page load'))
  .catch(() => console.log('Present a login button'));

logout

Syntax

logout

(
  • [force]
)
Promise

Summary

Log this client instance out. The 'force' parameter can be used to force a logout of the current session (e.g. another SDK app in another browser tab, or even the Circuit webclient). Logging out does not revoke the OAuth2 access token.

Parameters:

  • [force] Boolean optional

    Setting force to true also terminates the Circuit connection of other browser tabs

Returns:

Promise:

A promise without data

Example:

client.logout();

makeCall

Syntax

makeCall

(
  • user
  • mediaType
  • [createIfNotExists]
)
Promise | Call

Summary

Start a direct call with a user by its email address or user ID.

Required OAuth2 scopes: CALLS (also requires WRITE_CONVERSATIONS if a conversation needs to be created)

Parameters:

  • user String

    email or userID of the User to call

  • mediaType MediaType

    Media type for the call.

  • [createIfNotExists] Boolean optional

    Create conversation with user if not already existing. Default is false.

Returns:

Promise | Call:

A promise returning the created call.

Example:

client.makeCall('bob@company.com',  {audio: true, video: true, videoResolution: Circuit.Enums.VideoResolutionLevel.VIDEO_720})
  .then(call => console.log('New call: ', call));

markItemsAsRead

Syntax

markItemsAsRead

(
  • convId
  • creationTime
)
Promise

Summary

Mark all items of the specified conversation, before a timestamp as read.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • creationTime Number

    Items older than this timestamp are marked as read. Defaults to current time.

Returns:

Promise:

A promise without data

Example:

client.markItemsAsRead('338d2002-ae68-495c-aa5c-1dff3fbc845a')
  .then(() => console.log('done'));

moderateConversation

Syntax

moderateConversation

(
  • convId
)
Promise

Summary

Moderate a conversation.

Required OAuth2 scopes: WRITE_CONVERSATION or MODERATE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID.

Returns:

Promise:

A promise without data.

Example:

client.moderateConversation('338d2002-ae68-495c-aa5c-1dff3fbc845a')
  .then(() => console.log('Successfully moderated conversation'));

mute

Syntax

mute

(
  • callId
)
Promise

Summary

Mute an existing call.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to mute.

Returns:

Promise:

A promise that is resolved when the mute is complete.

Example:

client.mute('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(() => console.log('Successfully muted call'));

muteDevice

Syntax

muteDevice

(
  • callId
  • [destClientId]
  • [option]
)
Promise

Summary

Mute/unmute the mic or speaker of your other web device (e.g. Circuit WebClient or another SDK client). Use getDevices() to obtain ClientIDs of user's other devices.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    The call ID of the call

  • [destClientId] String optional

    ClientID of device to mute the call. Only web clients supported. If none provided, first webclient found is used.

  • [option] Object optional

    Literal object with mic or speaker boolean attributes. Defaults to true for mic and speaker.

Returns:

Promise:

A promise that is resolved when the call is muted on the device.

Example:

// Mute the mic and disable incoming audio for the specified call on device specified by its Client ID
client.muteDevice('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', null, {mic: true, speaker: true})
  .then(() => console.log('Success'));

muteParticipant

Syntax

muteParticipant

(
  • callId
  • userId
)
Promise

Summary

Mute a remote participant.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID.

  • userId String

    User ID of the participant to mute.

Returns:

Promise:

A promise that is resolved when the participant has been muted.

Example:

client.muteParticipant('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', '874c528c-1410-4362-b519-6e7d26a2edb2')
  .then(() => console.log('Successfully muted participant'));

muteRtcSession

Syntax

muteRtcSession

(
  • callId
)
Promise

Summary

Mute all participants except the current user.

Required OAuth2 scopes: CALLS

Parameters:

Returns:

Promise:

A promise that is resolved when the participants have been muted.

Example:

client.muteRtcSession('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
  .then(() => console.log('Successfully muted participants'));

navigateToConversation

Syntax

navigateToConversation

(
  • convId
  • [destClientId]
  • [noLaunch]
)
Promise

Summary

Navigates to a Conversation If destClientId is provided, then the conversation opens on that device, and if that device is not logged on an error is returned. Use getDevices to find logged on devices. If no destClientId is provided the request is sent to all logged on devices with the first one oppening the conversation. If a destClientId is provided the conversation is opened immediately. If user is not logged on the another web-based client, then a new browser tab is opened.

Required OAuth2 scopes: READ_CONVERSATIONS

Parameters:

  • convId String

    conversation id

  • [destClientId] String optional

    ClientID of device to open the conversation.

  • [noLaunch] String optional

    If set to false (or omitted) default launch web browser on local device unless if no other clients are logged on. Mutually exclusive with destClientId.

Returns:

Promise:

A promise that is resolved when the conversation is opened on your other device.

Example:

client.navigateToConversation('d2dec6ed-2998-47be-aefd-64e6d1e5fb4c')
  .then(() => console.log('Navigate to Conversation'));

pullRemoteCall

Syntax

pullRemoteCall

(
  • callId
  • [audioOnly]
)
Promise

Summary

Pull a remote call to the local device.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to join.

  • [audioOnly] Boolean optional

    flag to check whether to pull with audio only.

Returns:

Promise:

A promise that is resolved when the call has been pulled.

Example:

client.pullRemoteCall('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
  .then(() => console.log('Successfully pulled the call'));

removeAppMessageListener

Syntax

removeAppMessageListener

(
  • [type]
  • [cb]
)

Summary

Remove listener for UserMessage events for a specific type. If the callback is not specified, all listeners for the given type are removed. If neither type nor callback is specified, all listeners are removed.

Required OAuth2 scopes: USER_TO_USER

Parameters:

  • [type] String optional

    Type

  • [cb] Function optional

    Callback to be removed.

Example:

client.removeAppMessageListener('channel1', myHandler);
client.removeAppMessageListener('channel1');
client.removeAppMessageListener();

removeLabels

Syntax

removeLabels

(
  • labelIds
)
Promise | String[]

Summary

Unassigns the labels from their conversations and removes the labels.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • labelIds String[]

    Array of label Ids to be removed

Returns:

Promise | String[]:

A promise returning an array of removed label Ids.

Example:

client.removeLabels('d353db50-b835-483e-9fce-2b157b2253d3')
  .then(labels => console.log(${labels.length} labels have been removed));

removeParticipant

Syntax

removeParticipant

(
  • convId
  • userIds
)
Promise

Summary

Remove a participant from a group conversation or community.

Required OAuth2 scopes: WRITE_CONVERSATIONS or MANAGE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • userIds String[]

    Single user ID or array of User IDs

Returns:

Promise:

A promise without data

Example:

client.removeParticipant('8fc29770-84ab-4ace-9e85-3269de707499', '874c528c-1410-4362-b519-6e7d26a2edb2')
  .then(() => console.log('Successfully removed'));

removeWhiteboardElement

Syntax

removeWhiteboardElement

(
  • callId
  • xmlId
)
Promise

Summary

Remove a whiteboard element.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call.

  • xmlId String

    SDK generated ID of the SVG elements.

Returns:

Promise:

A promise that is resolved when the drawing has been removed.

Example:

client.addWhiteboardElement('8f365bf3-97ea-4d54-acc7-2c4801337521',

. '') .then(() => console.log('Successfully removed whiteboarding element'));

renewSessionToken

Syntax

renewSessionToken

() Promise

Summary

Renew the session token of the current user. This is the authentication session, not the OAuth token.

Required OAuth2 scopes: n/a

Returns:

Promise:

A promise without data

Example:

client.renewSessionToken()
  .then(() => console.log('Session token renewed'));

renewToken

Syntax

renewToken

() Promise | Token

Summary

Renew the OAuth2 access token of the current user.

Required OAuth2 scopes: n/a

Returns:

Promise | Token:

A promise that returns the token

Example:

client.renewToken()
  .then(token => console.log('New access token is: ' + token));

revokeToken

Syntax

revokeToken

(
  • [token]
)
Promise

Summary

Revoke the OAuth2 access token.

Parameters:

  • [token] String optional

    If omitted, the internally used token is revoked.

Returns:

Promise:

A promise without data

Example:

client.revokeToken();

sendAppMessageToClient

Syntax

sendAppMessageToClient

(
  • type
  • [destClientId]
  • content
)

Summary

Send an application specific message to another client of the logged on user. Use addClientMessageListener to listen for user messages on the receiving side. To send a message to your other users, use sendAppMessageToUser. Sending a reply is the responsibility of the application.

Required OAuth2 scopes: USER_TO_USER

Parameters:

  • type String

    The type of the message

  • [destClientId] String optional

    The client ID of the device to send the message to.

  • content Object

    The content to send. Object must be serializable.

Example:

client.sendAppMessageToClient('topic1', null, {
  messageType: 'REQUEST_ABC',
  data: {msg: 'Hello', id: '1234'}
});

sendAppMessageToUser

Syntax

sendAppMessageToUser

(
  • type
  • userId
  • content
)

Summary

Send an application specific message to another user. Use addAppMessageListener to listen for user messages on the receiving side. To send a message to your own clients, use sendAppMessageToClient. Sending a reply is the responsibility of the application.

Required OAuth2 scopes: USER_TO_USER

Parameters:

  • type String

    The type of the message

  • userId String

    The user ID of the user to send the message to

  • content Object

    The content to send. Object must be serializable.

Example:

client.sendAppMessageToUser('channel1', 'b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', {
  reqId: '1234',
  msgName: 'CHAT_REQ',
  text: 'Hello World'
})
.then(() => console.log(Message sent));

sendClickToAnswerRequest

Syntax

sendClickToAnswerRequest

(
  • callId
  • [mediaType]
  • [destClientId]
)
Promise

Summary

Answer an incoming call on one of your other devices. If destClientId is provided, then the call is initiated on that device, and if that device is not logged on an error is returned. Use getDevices to find logged on devices. If no destClientId is provided the request is sent to all logged on devices with the first one answering the call. Does not launch a new browser tab in case user is not logged on with another web-based client.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call to answer

  • [mediaType] String optional

    audio or video. Defaults to 'audio'.

  • [destClientId] String optional

    ClientID of device to answer the call on.

Returns:

Promise:

A promise that is resolved when the call is answered on your other device.

Example:

client.sendClickToAnswerRequest('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
  .then(() => console.log('Success'));

sendClickToCallRequest

Syntax

sendClickToCallRequest

(
  • target
  • [mediaType]
  • [destClientId]
  • [noLaunch]
)
Promise

Summary

Start a direct call with a user initiated on one of your other devices. Also called Click-2-Call. If destClientId is provided, then the call is initiated on that device, and if that device is not logged on an error is returned. Use getDevices to find logged on devices. If no destClientId is provided the request is sent to all logged on devices with the first one initiating the call. If a destClientId is provided the call is initiated immediately, otherwise a confirmation popup is shown. If user is not logged on the another web-based client, then a new browser tab is opened.

Required OAuth2 scopes: CALLS

Parameters:

  • target String

    email address or phone number of user to call

  • [mediaType] String optional

    audio or video. Defaults to 'audio'.

  • [destClientId] String optional

    ClientID of device to initiate the call.

  • [noLaunch] String optional

    If set to false (or omitted) default launch web browser on local device unless if no other clients are logged on. Mutually exclusive with destClientId.

Returns:

Promise:

A promise that is resolved when the call is initiated on your other device.

Example:

client.sendClickToCallRequest('bob@company.com', 'video')
  .then(() => console.log('Circuit video call initiated'));

client.sendClickToCallRequest('12265551234')
  .then(() => console.log('Phone call initiated'));

sendDigits

Syntax

sendDigits

(
  • callId
  • digits
)
Promise

Summary

Send DTMF digits in active local call.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    The call ID of active call

  • digits String

    The digits to be sent

Returns:

Promise:

A promise returning no content.

Example:

client.sendDigits('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', '5')
  .then(() => console.log('Digits sent'));

setAudioVideoStream

Syntax

setAudioVideoStream

(
  • callId
  • stream
  • [mediaType]
)
Promise

Summary

Set the media stream for audio/video to be transmitted in the active call.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to add/remove a media stream.

  • stream MediaStream

    Audio/Video MediaStream to send.

  • [mediaType] MediaType optional

    Media type for the call. If not set, audio/video is set based on tracks in stream.

Returns:

Promise:

A promise that is resolved when the mediaStream has been set.

Example:

client.setAudioVideoStream('8f365bf3-97ea-4d54-acc7-2c4801337521', stream)
  .then(() => console.log('Successfully set media stream'));

setCallForwarding

Syntax

setCallForwarding

(
  • settings
)

Summary

Set/Unset call forwarding.

Required OAuth2 scopes: USER_TO_USER, READ_USER, and READ_CONVERSATIONS

Parameters:

  • settings Object
    • status Boolean

      Boolean to determine whether to enable or disable call forwarding.

    • [number] String optional

      Phone number to set call forwarding to. Default will set to previous call forwarding number.

Returns:

Promise A promise without data

Example:

client.setCallForwarding({status: true, number: '15611234567'})
  .then(() => console.log('Call forwarding settings updated'));

setCookie

Syntax

setCookie

(
  • cookie
)
Void

Summary

Set the authentication cookie to be used for XMLHttpRequests and WebSockets.

Parameters:

  • cookie String

    Set the cookie to be used.

Returns:

Void:

Example:

client.setCookie(myCookie);

setMediaDevices

Syntax

setMediaDevices

(
  • devices
)
Promise

Summary

Set the playback, recording, video and ringing devices to be used for calls. Can be called before or during a call. Use navigator.mediaDevices.enumerateDevices to get the available media devices. If multiple devices are set for a particular type (e.g. playback), then the first media device still available when starting the call is used.

Required OAuth2 scopes: CALLS

Parameters:

  • devices Object

    Literal object containing the playback, recording, video and ringing device IDs.

    • [playback] String | String[] optional

      Playback (audio output) media device ID, or array of IDs.

    • [recording] String | String[] optional

      Recording (audio input) media device ID, or array of IDs.

    • [video] String | String[] optional

      Video (camera) media device ID, or array of IDs.

    • [ringing] String | String[] optional

      Ringing media device ID, or array of IDs.

Returns:

Promise:

A promise returning no content.

Example:

client.setMediaDevices({
    recording: 'c2c9e42e18ad18d8dd16942ab653c029d81411fbbb2c6b8fedf7e0e36739099d',
    video: ['617fb618597cef464e0bbe72c7978bc195435f9f04ac3d9d8961618d7d9fd07b', 'ed7e20a16115b672215db6479549abea11d41ba65de42b246d2575f678ac09be']
  })
  .then(() => console.log('New mic and camera device set'));

setOauthConfig

Syntax

setOauthConfig

(
  • config
)

Summary

Set the OAuth2 configuration for the Circuit client instance. This data can also be provided as part of the configuration parameters in the constructor.

Parameters:

  • config Object

    Object literal containing the OAuth2 configuration parameters

    • [client_id] String optional

      The OAuth2 client ID you obtain from the Developer Portal. Identifies the client that is making the request.

    • [client_secret] String optional

      The OAuth2 client secret you obtain from the Developer Portal. Applicable for client credentials grant type used for Node.js apps.

    • [scope] String optional

      Comma-delimited set of permissions that the application requests. Values: READ_USER_PROFILE,WRITE_USER_PROFILE,READ_CONVERSATIONS,WRITE_CONVERSATIONS,READ_USER,CALL_RECORDING,CALLS,MENTION_EVENT,USER_MANAGEMENT, MANAGE_CONVERSATIONS,CREATE_CONVERSATIONS_CONTENT,DELETE_CONVERSATIONS_CONTENT,UPDATE_CONVERSATION_CONTENT,MANAGE_PRESENCE,MODERATE_CONVERSATIONS, ORGANIZE_CONVERSATIONS,SEARCH_CONVERSATIONS,USER_TO_USER

setPresence

Syntax

setPresence

(
  • presence
)
Promise

Summary

Set the presence of the logged on user.

Required OAuth2 scopes: WRITE_USER_PROFILE or MANAGE_PRESENCE

Parameters:

Returns:

Promise:

A promise without data

Example:

client.setPresence({state: Circuit.Enums.PresenceState.AVAILABLE})
  .then(() => console.log('Presence updated'));

setScreenshareStream

Syntax

setScreenshareStream

(
  • callId
  • stream
)
Promise

Summary

Set the media stream for screenshare to be transmitted in the active call. Useful for sending a MediaStream captured via the HTMLCanvasElement.captureStream API. API has been renamed from toggleMediaStream. See https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/captureStream

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to add/remove a media stream.

  • stream MediaStream

    Screenhare MediaStream to send.

Returns:

Promise:

A promise that is resolved when the mediaStream has been set.

Example:

client.setScreenshareStream('8f365bf3-97ea-4d54-acc7-2c4801337521', stream)
  .then(() => console.log('Successfully set media stream'));

setStatusMessage

Syntax

setStatusMessage

(
  • statusMessage
)

Summary

Set the status message of the logged on user. Fires userPresenceChanged event to users on other logged on clients and to all other users that subscribe to this user's presence.

Required OAuth2 scopes: WRITE_USER_PROFILE or MANAGE_PRESENCE

Parameters:

  • statusMessage String

    Status message. Set to empty string to clear status message.

Returns:

Promise A promise without data

Example:

client.setStatusMessage('At the beach enjoying life')
  .then(() => console.log('Status message set'));

setUserSettings

Syntax

setUserSettings

(
  • userSettings
)

Summary

Save user settings of the logged on user.

Required OAuth2 scopes: WRITE_USER_PROFILE

Parameters:

  • userSettings UserSettings

    User settings. Only attributes present are updated.

Returns:

Promise A promise without data

Example:

client.setUserSettings({presenceOptOut: true})
  .then(() => console.log('presence opt out setting updated'));

setWhiteboardBackground

Syntax

setWhiteboardBackground

(
  • callId
  • file
)
Promise

Summary

Set the background of the whiteboard.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call.

  • file File

    File object for background image.

Returns:

Promise:

A promise without data.

Example:

client.setWhiteboardBackground('8f365bf3-97ea-4d54-acc7-2c4801337521', file)
  .then(() => console.log('Successfully uploaded and set background'));

startAdvancedUserSearch

Syntax

startAdvancedUserSearch

(
  • searchTerm
)
Promise | String

Summary

Start an asynchronous user search returning a search ID. Search results are received with search result events. Searches are done with an object containing the search parameters. Raises basicSearchResults and searchStatus events.

Required OAuth2 scopes: READ_USER

Parameters:

  • searchTerm Object

    object literal containing the search parameters.

    • query String

      The query string that is searched for.

    • [searchContext] String optional

      The SearchContext which is searched for. e.g USER or MEETING_POINT. Defaults to USER.

    • [searchExactAssignedPhoneNumber] Boolean optional

      If true, only users with the exact number assigned as ATC (telephony) number are returned. Defaults to false.

Returns:

Promise | String:

A promise returning the search ID. Search ID is used to correlate the asynchronous events.

Example:

client.startAdvancedUserSearch({ query: 'Allison' })
  .then(searchId => console.log('Search started with ID: ' + searchId));

client.startAdvancedUserSearch({
  query: '15611234567',
  scope: Circuit.Enums.SearchContext.USER,
  searchExactAssignedPhoneNumber: true
})
  .then(searchId => console.log('Search started with ID: ' + searchId));

startBasicSearch

Syntax

startBasicSearch

(
  • searchTerm
)
Promise | String

Summary

Start an asynchronous basic search returning a search ID. Search results are received with search result events. Raises basicSearchResults and searchStatus events.

Required OAuth2 scopes: READ_USER, READ_CONVERSATIONS, or SEARCH_CONVERSATIONS

Parameters:

  • searchTerm String | Array

    Array of searchTerm objects, or a string for a simple scope search search.

    • searchTerm String

      The string that is searched for.

    • scope String

      The scope to search in.

    • [startTime] Number optional

      start date used for DATE scope. In ms since midnight on January 1, 1970 in UTC

    • [endTime] Number optional

      end date used for DATE scope. In ms since midnight on January 1, 1970 in UTC

    • [rootConnector] FilterConnector optional

      filter constraints used for FILTER scopes. See getConversationsByFilter for example.

Returns:

Promise | String:

A promise returning the search ID. Search ID is used to correlate the asynchronous events.

Example:

client.startBasicSearch('Kiteboarding')
  .then(searchId => console.log('Search started with ID: ' + searchId));

client.startBasicSearch([{
  scope: Circuit.Enums.SearchScope.CONVERSATIONS,
  searchTerm: 'Vacation'
}, {
  scope: Circuit.Enums.SearchScope.MEMBERS,
  searchTerm: 'Paul'
}])
  .then(searchId => console.log('Search started with ID: ' + searchId));

client.startBasicSearch([{
  scope: Circuit.Enums.SearchScope.DATE,
  startTime: new Date(new Date().setDate(new Date().getDate()-1)) // yesterday
}])
  .then(searchId => console.log('Search started with ID: ' + searchId));

startConference

Syntax

startConference

(
  • conversation
  • mediaType
  • [clientId]
)
Promise | Call

Summary

Start a conference call.

Required OAuth2 scopes: CALLS

Parameters:

  • conversation String

    Conversation ID

  • mediaType MediaType

    Media type for the call.

  • [clientId] String optional

    clientId of device where to start the call from. If clientId is used this API will only return the callId, not the call.

Returns:

Promise | Call:

A promise returning the created call.

Example:

client.startConference('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', {audio: true, video: false})
  .then(call => console.log('New call: ', call));

startRecording

Syntax

startRecording

(
  • callId
  • [mediaTypes]
  • [videoLayout]
)
Promise

Summary

Start recording the active call.

Required OAuth2 scopes: CALL_RECORDING

Parameters:

  • callId String

    the ID of the call to start recording for. Only local active calls can be recorded.

  • [mediaTypes] Object optional

    a set of media types to be recorded if used in the call. Possible values are audio, video and text. Default: {audio: true, video: true} Note: For backward compatibility this method also accepts {Boolean} value for the second parameter which determines if video/screenshare is recorded.

  • [videoLayout] VideoLayout optional

    Video layout to be used for recording with optional pinning of user.

Returns:

Promise:

A promise that is resolved when recording has started.

Example:

client.startRecording('8f365bf3-97ea-4d54-acc7-2c4801337521', {audio: true, video: true, text: true})
  .then(() => console.log('Successfully started recording'));

startUserSearch

Syntax

startUserSearch

(
  • searchTerm
)
Promise | String

Summary

Start an asynchronous user search returning a search ID. Search results are received with search result events. Searches are done with beginning characters of first and lastname. Raises basicSearchResults and searchStatus events.

Required OAuth2 scopes: READ_USER or SEARCH_CONVERSATIONS

Parameters:

  • searchTerm String | Object

    string, or object literal containing a query attribute as search string

    • query String

      The query string that is searched for.

    • [reversePhoneNumberLookup] Boolean optional

      If true match term from the last digits of user's phone numbers. If false match search term anywhere in users phone numbers.

Returns:

Promise | String:

A promise returning the search ID. Search ID is used to correlate the asynchronous events.

Example:

client.startUserSearch('Ro')
  .then(searchId => console.log('Search started with ID: ' + searchId));

stopRecording

Syntax

stopRecording

(
  • callId
  • [mediaTypes]
)
Promise

Summary

Stop recording the active call.

Required OAuth2 scopes: CALL_RECORDING

Parameters:

  • callId String

    the ID of the call to stop recording for.

  • [mediaTypes] Object optional

    a set of media types to stop recording for if started. Possible values are audio, video and text. Default: {audio: true, video: true}.

Returns:

Promise:

A promise that is resolved when recording has started.

Example:

client.stopRecording('8f365bf3-97ea-4d54-acc7-2c4801337521', {audio: true, video: true, text: true})
  .then(() => console.log('Successfully stopped recording'));

submitForm

Syntax

submitForm

(
  • itemId
  • form
)
Promise

Summary

Submits a form posted in a message by the SDK

Required OAuth2 scopes: WRITE_CONVERSATION

Parameters:

Returns:

Promise:

A promise without data

Example:

client.submitForm('e8b72e0e-d2d1-46da-9ed4-7378759314488', {
  id: 'form1234',
  data: [{
    key: 'sport', // e.g. dropdown, input
    value: 'F1'
  }, {
    key: 'isDangerous', // single checkbox
    value: 'true'
  }, {
    key: 'drivers',  // multi-checkbox
    value: 'Vettel,Alonso,LeClerc'
  }]
})
  .then(() => console.log('Form submitted');

subscribePresence

Syntax

subscribePresence

(
  • userIds
)
Promise

Summary

Subscribe to presence notifications of users.

Required OAuth2 scopes: READ_USER

Parameters:

Returns:

Promise:

A promise without data

Example:

client.subscribePresence(['874c528c-1410-4362-b519-6e7d26a2edb2','451e05a7-4649-4887-bfd2-21e70ec47e57'])
  .then(() => console.log('Successfully subscribed'));

subscribeTenantPresence

Syntax

subscribeTenantPresence

() Promise

Summary

Subscribe to presence notifications of all users in the tenant. userPresenceChanged event will only contain the new state and user ID. Other attributes such as location are not included when subscribing for the whle tenant. API requires tenant admin permissions. API only allowed for Client Credentials apps (bots).

Required OAuth2 scopes: READ_USER and only by tenant admins

Returns:

Promise:

A promise without data

Example:

client.subscribeTenantPresence()
  .then(() => console.log('Successfully subscribed'));

subscribeTypingIndicator

Syntax

subscribeTypingIndicator

(
  • convId
)
Promise

Summary

Subscribe to typing indicaticator of a conversation. Raises 'typing' event

Required OAuth2 scopes: WRITE_CONVERSATIONS or READ_CONVERSATION

Parameters:

  • convId String

    Conversation ID

Returns:

Promise:

A promise without data

Example:

client.subscribeTypingIndicator('2b5a62d4-575a-41bb-afef-87c34a52d70e')
  .then(() => console.log('Successfully subscribed'));

supportedFeatures

Syntax

supportedFeatures

() Object

Summary

List supported features for current browser. Only list features are currently text and rtc.

Returns:

Object:

Object specifying what features are supported.

suspendIncomingWebhook

Syntax

suspendIncomingWebhook

(
  • webhookId
)
Promise

Summary

Suspend a webhook.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • webhookId String

    Id of the webhook to be suspended.

Returns:

Promise:

A promise without data

Example:

 client.suspendIncomingWebhook('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
     .then(() => console.log('Webhook suspended.'))
     .catch(console.error);

switchRecordingLayout

Syntax

switchRecordingLayout

(
  • callId
  • videoLayout
)
Promise

Summary

Switch the recording layout of the active call.

Required OAuth2 scopes: CALL_RECORDING

Parameters:

  • callId String

    callId of the active call

  • videoLayout VideoLayout

    Video layout to be used for recording with optional pinning of user.

Returns:

Promise:

A promise that is resolved when layout has changed.

Example:

client.switchRecordingLayout('8f365bf3-97ea-4d54-acc7-2c4801337521', {
  layoutName: Circuit.Enums.RecordingVideoLayoutName.VIDEO_SCREEN_50_50,
  layoutMapping: [{tileId: 'Video', tileContent: '72ee640f-9ac3-4275-b9ec-46d08e499c5a'}]
})
  .then(() => console.log('Successfully changed recording layout'));

toggleRemoteAudio

Syntax

toggleRemoteAudio

(
  • callId
)
Promise

Summary

Toggle the incoming (remote) audio stream on an existing call. Use callStatus event and call.remoteAudioDisabled to determine if remote audio is to be paused.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call.

Returns:

Promise:

A promise that is resolved when the toggle is complete.

Example:

client.toggleRemoteAudio(callId).then(call => console.log(Remote audio state: ${call.remoteAudioDisabled}));

// remoteAudio is the audio element
client.addEventListener('callStatus', evt => {
   if (callId === evt.call.callId) {
     if (remoteAudio.srcObject !== evt.call.remoteAudioStream) {
       remoteAudio.srcObject = evt.call.remoteAudioStream;
     }
     if (evt.reason === 'remoteStreamUpdated') {
       evt.call.remoteAudioDisabled ? remoteAudio.pause() : remoteAudio.play();
     }
  }

});

toggleScreenShare

Syntax

toggleScreenShare

(
  • callId
)
Promise

Summary

Toggle local screenshare on an existing call. To check if screenshare is currently active check call.localMediaType and call.mediaType.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to add/remove screen share.

Returns:

Promise:

A promise that is resolved when the screen share has been added/removed.

Example:

client.toggleScreenShare('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(() => console.log('Successfully toggled'));

toggleVideo

Syntax

toggleVideo

(
  • callId
)
Promise

Summary

Toggle sending video on an existing call.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to toggle video.

Returns:

Promise:

A promise that is resolved when the toggle is complete.

Example:

client.toggleVideo('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(() => console.log('Successfully toggled'));

toggleWhiteboardOverlay

Syntax

toggleWhiteboardOverlay

(
  • callId
)
Promise

Summary

Toggle the overlay of the whiteboard.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call.

Returns:

Promise:

A promise without data.

Example:

client.toggleWhiteboardOverlay('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(() => console.log('Successfully toggled the overlay'));

typing

Syntax

typing

(
  • convId
  • isTyping
  • [itemId]
)
Promise

Summary

Causes a typing event from the user in a given conversation.

Required OAuth2 scopes: WRITE_CONVERSATION or READ_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • isTyping Boolean

    Typing status

  • [itemId] String optional

    Item ID of parent. Optional. Allows for more granular typing indicator.

Returns:

Promise:

A promise without data

Example:

client.typing('2b5a62d4-575a-41bb-afef-87c34a52d70e', true)
  .then(() => console.log('Successfully sent'));

unarchiveConversation

Syntax

unarchiveConversation

(
  • convId
)
Promise

Summary

Unarchive a conversation. Succeeds if conversation is already unarchived.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

Returns:

Promise:

A promise without data

Example:

client.unarchiveConversation('d353db50-b835-483e-9fce-2b157b2253d3')
  .then(() => console.log('Conversation unarchived'));

unassignLabels

Syntax

unassignLabels

(
  • convId
  • labelIds
)
Promise | String[]

Summary

Unassigns specified labels from the given conversation.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • convId String

    Id of which conversation labels should be removed from.

  • labelIds String[]

    Array of label Ids to be removed from the conversation.

Returns:

Promise | String[]:

A promise returning an array of remaining label Ids in the conversation.

Example:

client.unassignLabels('d353db50-b835-483e-9fce-2b157b2253d3', ['146d546c-5012-4db4-a867-215e4c8cdb30', '398473a0-c39f-46af-884f-4e8a0e88c4d1'])
  .then(labels => console.log(${labels.length} labels are still assigned to the converation.));

undoWhiteboard

Syntax

undoWhiteboard

(
  • callId
  • steps
  • userId
)
Promise

Summary

Undo recent changes to the whiteboard.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    Call ID of the call.

  • steps Number

    Number of steps to undo.

  • userId String

    If the user ID is set only steps of this user are undone.

Returns:

Promise:

A promise without data.

Example:

client.undoWhiteboard('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(() => console.log('Successfully undone steps'));

unfavoriteConversation

Syntax

unfavoriteConversation

(
  • convId
)
Promise

Summary

Remove a conversation from the favorite list. Succeeds if conversation is already unfavorited.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

Returns:

Promise:

A promise without data

Example:

client.unfavoriteConversation('d353db50-b835-483e-9fce-2b157b2253d3')
  .then(() => console.log('Conversation removed from favorites'));

unflagItem

Syntax

unflagItem

(
  • convId
  • itemId
)
Promise

Summary

Clear the flag of an item.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • itemId String

    Item ID of item to be cleared

Returns:

Promise:

A promise without data

Example:

client.unflagItem('8fc29770-84ab-4ace-9e85-3269de707499', '874c528c-1410-4362-b519-6e7d26a2edb2')
  .then(() => console.log('Successfully unflagged'));

unlikeItem

Syntax

unlikeItem

(
  • itemId
)
Promise

Summary

Unlike an item.

Required OAuth2 scopes: WRITE_CONVERSATIONS or UPDATE_CONVERSATION_CONTENT

Parameters:

  • itemId String

    Item ID of item to be unliked

Returns:

Promise:

A promise without data

Example:

client.unlikeItem('874c528c-1410-4362-b519-6e7d26a2edb2')
  .then(() => console.log('Successfully unliked item'));

unmoderateConversation

Syntax

unmoderateConversation

(
  • convId
)
Promise

Summary

Unmoderate a conversation.

Required OAuth2 scopes: WRITE_CONVERSATION or MODERATE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID.

Returns:

Promise:

A promise without data.

Example:

client.unmoderateConversation('338d2002-ae68-495c-aa5c-1dff3fbc845a')
  .then(() => console.log('Successfully unmoderated conversation'));

unmute

Syntax

unmute

(
  • callId
)
Promise

Summary

Unmute an existing call.

Required OAuth2 scopes: CALLS

Parameters:

  • callId String

    callId of the call to unmute.

Returns:

Promise:

A promise that is resolved when the unmute is complete.

Example:

client.unmute('8f365bf3-97ea-4d54-acc7-2c4801337521')
  .then(() => console.log('Successfully unmuted call'));

unsubscribePresence

Syntax

unsubscribePresence

(
  • userIds
)
Promise

Summary

Unsubscribe to presence notifications of users.

Required OAuth2 scopes: READ_USER

Parameters:

Returns:

Promise:

A promise without data

Example:

client.unsubscribePresence(['874c528c-1410-4362-b519-6e7d26a2edb2','451e05a7-4649-4887-bfd2-21e70ec47e57'])
  .then(() => console.log('Successfully unsubscribed'));

unsubscribeTenantPresence

Syntax

unsubscribeTenantPresence

() Promise

Summary

Unsubscribe to presence notifications of all users in the tenant. API only allowed for Client Credentials apps (bots). API requires tenant admin permissions.

Required OAuth2 scopes: READ_USER and only by tenant admins

Returns:

Promise:

A promise without data

Example:

client.unsubscribeTenantPresence()
  .then(() => console.log('Successfully unsubscribed'));

unsubscribeTypingIndicator

Syntax

unsubscribeTypingIndicator

(
  • convId
)
Promise

Summary

Unsubscribe to typing indicaticator of a conversation.

Required OAuth2 scopes: WRITE_CONVERSATIONS or READ_CONVERSATION

Parameters:

  • convId String

    Conversation ID

Returns:

Promise:

A promise without data

Example:

client.unsubscribeTypingIndicator('2b5a62d4-575a-41bb-afef-87c34a52d70e')
  .then(() => console.log('Successfully unsubscribed'));

unsuspendIncomingWebhook

Syntax

unsuspendIncomingWebhook

(
  • webhookId
)
Promise

Summary

Unsuspend a webhook.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • webhookId String

    Id of the webhook to be unsuspended.

Returns:

Promise:

A promise without data

Example:

 client.unsuspendIncomingWebhookById('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
     .then(() => console.log('Webhook unsuspended.'))
     .catch(console.error);

updateConversation

Syntax

updateConversation

(
  • convId
  • data
)
Promise | Conversation

Summary

Update a conversation or community.

Required OAuth2 scopes: WRITE_CONVERSATIONS or MANAGE_CONVERSATIONS

Parameters:

  • convId String

    Conversation ID

  • data Object

    Literal object with attributes to change

    • [topic] String optional

      Topic of conversation/community

    • [description] String optional

      Description (only applicable to communities)

Returns:

Promise | Conversation:

A promise returning the updated conversation

Example:

client.updateConversation('338d2002-ae68-495c-aa5c-1dff3fbc845a', {topic: 'Kiteboarding Fun'})
  .then(conv => console.log(Topic updated, conv));

updateIncomingWebhook

Syntax

updateIncomingWebhook

(
  • webhookData
)
Promise | IncomingWebhook

Summary

Update an existing webhook.

Required OAuth2 scopes: WRITE_CONVERSATIONS or ORGANIZE_CONVERSATIONS

Parameters:

  • webhookData Object
    • webhookId String

      Id of the webhook to update.

    • [name] String optional

      Nameof webhook.

    • [description] String optional

      Description webhook.

Returns:

Promise | IncomingWebhook:

A promise returning the updated incoming webhook

Example:

 client.updateIncomingWebhook({
         webhookId: 'b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a',
         name: 'UpdatedWebhook',
         description: 'This is an updated webhook.',
     })
     .then(webhook => console.log('Updated webhook:', webhook))
     .catch(console.error);

updateTextItem

Syntax

updateTextItem

(
  • content
)
Promise | Item

Summary

Update an existing text message. See addTextItem for RICH text formatting support.

Required OAuth2 scopes: WRITE_CONVERSATIONS or UPDATE_CONVERSATION_CONTENT

Parameters:

  • content Object

    Content for text message to be updated.

    • itemId String

      Conversation Item ID of item to update.

    • [contentType] TextItemContentType optional

      Default 'RICH'. Whether the content is rich text (HTML) or plain text.

    • [subject] String optional

      Subject/Title of message. Only supported for parent post (i.e. parentId omitted)

    • [content] String optional

      Actual text content.

    • [attachments] File[] optional

      Array of HTML File objects objects.

    • [form] FormMetadata optional

      Form object.

Returns:

Promise | Item:

A promise returning the item.

Example:

var content = {
    itemId: 'e8b72e0e-d2d1-46da-9ed4-7378759314488',
    subject: 'Updated subject',
    content: 'Updated text content',
    contentType: Circuit.Enums.TextItemContentType.RICH,
    attachments: [new File(['file 1'], 'testfile.txt', {type: 'text/plain', lastModified: Date.now()})]
}
client.updateTextItem(content)
  .then(console.log);

updateUser

Syntax

updateUser

(
  • user
)
Promise

Summary

Update the logged on user's own user object.

Required OAuth2 scopes: WRITE_USER_PROFILE

Parameters:

  • user Object

    Object literal containing the user attributes to update

    • userId String

      UserId

    • [firstName] String optional

      First name

    • [lastName] String optional

      Last name

    • [phoneNumber] PhoneNumber[] optional

      Phone numbers

    • [emailAddresses] EmailAddress[] optional

      Email addresses

    • [userLocale] UserLocale optional

      User Locale

    • [jobTitle] String optional

      Job title

    • [company] String optional

      Company

Returns:

Promise:

A promise without data

Example:

client.updateUser({userId: '72ee640f-9ac3-4275-b9ec-46d08e499c5a', firstName: 'Bob'})
  .then(() => console.log('Successfully updated user'));

uploadCustomVoicemailGreeting

Syntax

uploadCustomVoicemailGreeting

(
  • file
)

Summary

Upload a custom voicemail greeting (.wav file). This API only uploads the recording. Use API setUserSettings (attribute 'enableCustomVoicemailGreeting') to switch from detault greeting to uploaded custom greeting. The custom voicemail greeting can be downloaded via getUserSettings attribute voicemailCustomGreetingUri

Required OAuth2 scopes: WRITE_USER_PROFILE

Parameters:

  • file File

    Custom voicemail greeting as wav file.

Returns:

Promise A promise without data

Example:

client.uploadCustomVoicemailGreeting(file)
  .then(() => console.log('greeting uploaded'));

validateToken

Syntax

validateToken

(
  • [accessToken]
)

Summary

Validates the OAuth2 accessToken.

Parameters:

  • [accessToken] String optional

    If not provided, current accessToken of the client instance is validated.

Returns:

Promise A promise without data

Example:

client.validateToken()
  .then(token => console.log('accessToken is valid'))
  .catch(err => console.error('accessToken is not valid', err));

Properties

accessToken

Syntax

accessToken

String

Summary

OAuth2 access token

connectionState

Syntax

connectionState

ConnectionState

Summary

Connection State

domain

Syntax

domain

String

Summary

Domain connected to.

Default: circuitsandbox.net

expiresAt

Syntax

expiresAt

Number

Summary

OAuth2 token expiry

loggedOnUser

Syntax

loggedOnUser

User

Summary

User object of currently logged on user. Available after logon is finished which is not immediately after event connectionStateChanged/Connected.

supportedEvents

Syntax

supportedEvents

Array

Summary

List of supported events

version

Syntax

version

String

Summary

SDK version

Events

accessTokenRenewed

Syntax

accessTokenRenewed

Summary

Fired when OAuth access token has been renewed.

Event Payload:

  • event Object

    Object literal containing the event properties

basicSearchResults

Syntax

basicSearchResults

Summary

Asynchronous search results for startUserSearch or startBasicSearch.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • data Object

      Object literal containing search ID and its results

callEnded

Syntax

callEnded

Summary

Fired when a call is terminated.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • call Object

      Call object

    • replaced Boolean

      True if call has been replaced with a new call

callIncoming

Syntax

callIncoming

Summary

Fired when an incoming call is received. I.e. client is alerting

Event Payload:

  • event Object

    Object literal containing the event properties

callNetworkQualityChanged (Unified plan enabled)

Syntax

callNetworkQualityChanged (Unified plan enabled)

Summary

Fired when call network quality changes.

Event Payload:

  • event Object

    Object literal containing the event properties

    • callId String

      ID of the call

    • type String

      Event name

    • data Object

      Call quality object

      • userId Object
        User ID of local user
      • audio Object
        Audio quality object
      • audio.qualityLevel Object
        Low=1, Medium=2, High=3
      • audio.currentPlReceive Object
        Packet Loss on receiving stream
      • audio.currentPlSend Object
        Packet Loss on sending stream
      • audio.firstTimeLowQuality Object
        true if this is the first time with low quality on this call
  • event Object

    Object literal containing the event properties

    • String

      ID of the call

    • String

      Event name

    • Object

      Network quality level defined in Circuit.Enums.RtpQualityLevel

callRtpThresholdCleared

Syntax

callRtpThresholdCleared

Summary

Fired when call quality recovered after having reached the threshold.

Event Payload:

  • event Object

    Object literal containing the event properties

callRtpThresholdReached

Syntax

callRtpThresholdReached

Summary

Fired when call quality falls below a predefined threshold.

Event Payload:

  • event Object

    Object literal containing the event properties

callStatus

Syntax

callStatus

Summary

Fired when the call state, or any other call attribute of a local or remote call changes. Use the isRemote property to determine if the call is local or remote. A call is considered remote when a) the call is active on anohter device, or b) a group call is not joined yet.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • call Object

      Call object

    • [participant] Object optional

      Participant object for participant related reasons

    • [participants] Object optional

      Participants object for participant related reasons

    • [recordingInfo] Object optional

      data for callRecording reasons

    • [activeSpeakers] Object optional

      data for activeSpeakerChanged reason

    • reason String

      Reason event is triggered. Supported reasons are: callStateChanged, remoteStreamUpdated, localStreamEnded, callMuted, localUserMuted, localUserUnmuted, localUserSelfMuted, localUserSelfUnmuted, callLocked, callMoved, participantUpdated, participantAdded, participantJoined, participantRemoved, callRecording, droppedRemotely, sdpConnected, activeSpeakerChanged and whiteboardEnabled.

connectionStateChange

Syntax

connectionStateChange

Summary

Fired when the connection state changes.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • state String

      Connection State (Disconnected, Connecting, Reconnecting, Connected)

conversationArchived

Syntax

conversationArchived

Summary

Fired when a conversation has been archived for the logged on user

Event Payload:

  • event Object

    Object literal containing the event properties

conversationCreated

Syntax

conversationCreated

Summary

Fired when a new conversation is created for this user. This can be a brand new conversation, or being added to a conversation.

Event Payload:

  • event Object

    Object literal containing the event properties

conversationFavorited

Syntax

conversationFavorited

Summary

Fired when a conversation has been favorited for the logged on user

Event Payload:

  • event Object

    Object literal containing the event properties

conversationReadItems

Syntax

conversationReadItems

Summary

Fired when user read items on anohter device

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • data Object

      User data

      • convId String
        Conversation ID
      • lastReadTimestamp String[]
        Timestamp of last read item in this conversation

conversationUnarchived

Syntax

conversationUnarchived

Summary

Fired when a conversation has been unarchived for the logged on user

Event Payload:

  • event Object

    Object literal containing the event properties

conversationUnfavorited

Syntax

conversationUnfavorited

Summary

Fired when a conversation has been unfavorited for the logged on user

Event Payload:

  • event Object

    Object literal containing the event properties

conversationUpdated

Syntax

conversationUpdated

Summary

Fired when an existing conversation is updated, or user has been added to a new conversation.

Event Payload:

  • event Object

    Object literal containing the event properties

conversationUserDataChanged

Syntax

conversationUserDataChanged

Summary

Fired when conversation user data changes. E.g. label added/changed/removed

Event Payload:

  • event Object

    Object literal containing the event properties

formSubmission

Syntax

formSubmission

Summary

Fired when a user submits a form created by logged on user/bot.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • itemId String

      Item ID containing the form

    • form FormData

      Data of submitted form

    • submitterId String

      User ID of submitter

itemAdded

Syntax

itemAdded

Summary

Fired when a new conversation item is received. Note that the sender of an item will also receive this event.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • item Item

      Item being added

itemFlagged

Syntax

itemFlagged

Summary

Fired when a conversation item is flagged.

Event Payload:

  • event Object

    Object literal containing the event properties

itemUnflagged

Syntax

itemUnflagged

Summary

Fired when a conversation item is unflagged.

Event Payload:

  • event Object

    Object literal containing the event properties

itemUpdated

Syntax

itemUpdated

Summary

Fired when an existing conversation item is updated.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • item Item

      Itembeing updated

labelEdited

Syntax

labelEdited

Summary

Fired when an existing label is edited

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • label Label

      Edited label object

labelsAdded

Syntax

labelsAdded

Summary

Fired when new labels are added

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • labels Label[]

      Array of added label objects

labelsRemoved

Syntax

labelsRemoved

Summary

Fired when labels are removed

Event Payload:

  • event Object

    Object literal containing the event properties

loggedOnUserUpdated

Syntax

loggedOnUserUpdated

Summary

Fired when any attribute on the loggedOnUser changed

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • user Item

      Updated loggedOnUser object

mention

Syntax

mention

Summary

Mention notification for logged on user.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • mention Object
      • itemReference Object
        Object literal containing the convId and itemId
      • itemReference.convId Object
        Conversation ID
      • itemReference.itemId Object
        Item ID
      • userReference Object
        Object literal containing the userId
      • userReference.userId Object
        User ID

passwordChanged

Syntax

passwordChanged

Summary

Fired when password has been changed.

Event Payload:

  • event Object

    Object literal containing the event properties

reconnectFailed

Syntax

reconnectFailed

Summary

Fired when automatic reconnecting to the server fails.

Event Payload:

  • event Object

    Object literal containing the event properties

renewAccessTokenFailed

Syntax

renewAccessTokenFailed

Summary

Fired when renewal of OAuth access token has failed.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • error String

      Error object if token renew failed

renewSessionTokenFailed

Syntax

renewSessionTokenFailed

Summary

Fired when renewal of session token has failed.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • error String

      Error object if token renew failed

searchStatus

Syntax

searchStatus

Summary

Status of a pending search. E.g. Indication a search is FINISHED.

Event Payload:

sessionClosed

Syntax

sessionClosed

Summary

Fired when session has been forcefully closed by server.

Event Payload:

sessionExpiring

Syntax

sessionExpiring

Summary

Fired when session is about to expire.

Event Payload:

  • event Object

    Object literal containing the event properties

sessionTokenRenewed

Syntax

sessionTokenRenewed

Summary

Fired when session token has been renewed.

Event Payload:

  • event Object

    Object literal containing the event properties

systemMaintenance

Syntax

systemMaintenance

Summary

Fired to inform of an upcoming maintenance event.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • data Object

      Object literal containing start and end time

      • startTime Number
        The start time of the maintenance window in UTC
      • endTime Number
        The end time of the maintenance window in UTC

typing

Syntax

typing

Summary

Fired when a participant types a message in a conversation the user has subscribed to.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • data.isTyping Boolean

      Typing status

    • data.participantId String

      Participant user ID

    • data.parentItemId String

      Parent item ID

    • data.convId String

      Conversation ID

userPresenceChanged

Syntax

userPresenceChanged

Summary

Fired when the presence of a subscribed user changes.

Event Payload:

  • event Object

    Object literal containing the event properties

  • presenceState Presence

    Updated presence object

userSettingsChanged

Syntax

userSettingsChanged

Summary

Fired when one or more user settings for the logged on user change.

Event Payload:

  • event Object

    Object literal containing the event properties

userUpdated

Syntax

userUpdated

Summary

Fired when the local user is updated. E.g. I change the jobTitle on my mobile device.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • user User

      Updated user object

whiteboardBackground

Syntax

whiteboardBackground

Summary

Whiteboard background set or cleared.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • action String

      'set' or 'cleared'

    • [element] WhiteboardElement optional

      Applicable for 'set'. The element for the background

    • [possibleUndoOperations] Number optional

      Applicable for 'set'. The number of supported undo operations for the whiteboard.

whiteboardCleared

Syntax

whiteboardCleared

Summary

Whiteboard cleared.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • [userId] String optional

      userId if only elements for a specific user have been cleared

    • [possibleUndoOperations] Number optional

      The number of supported undo operations for the whiteboard.

whiteboardConversionFailed

Syntax

whiteboardConversionFailed

Summary

Whiteboard conversion failed event.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • callId String

      Call ID of whiteboard session that failed

    • errorText String

      Error text of failed whiteboard conversion

    • lastElements String

      The last svg elements of the whiteboard

whiteboardElement

Syntax

whiteboardElement

Summary

Whiteboard element added, removed or updated.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • action String

      'added', 'removed' or 'updated'

    • [element] WhiteboardElement optional

      element added or updated

    • [elementId] WhiteboardElementId optional

      element removed

    • [possibleUndoOperations] Number optional

      The number of supported undo operations for the whiteboard.

whiteboardEnabled

Syntax

whiteboardEnabled

Summary

Whiteboard enabled/disabled on a call.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • enabled Boolean

      true if enabled, false if disabled

    • [whiteboard] Whiteboard optional

      The whiteboard object (only when whiteboard becomes enabled)

whiteboardOverlayToggled

Syntax

whiteboardOverlayToggled

Summary

Whiteboard overlay toggled.

Event Payload:

  • event Object

    Object literal containing the event properties

whiteboardSync

Syntax

whiteboardSync

Summary

Whiteboard sync event.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • [whiteboard] Whiteboard optional

      The whiteboard object

    • [possibleUndoOperations] Number optional

      The number of supported undo operations for the whiteboard.