Client
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
ObjectObject literal containing configuration parameters
-
[client_id]
String optionalThe OAuth2 client ID you obtain from the Developer Portal. Identifies the client that is making the request.
-
[client_secret]
String optionalThe OAuth2 client secret you obtain from the Developer Portal. Applicable for
client credentials
grant type used for node.js apps. -
[scope]
String optionalComma-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 optionalApplicable to Client Credentials Grant only. If set to
true
, the OAuth2 access token is automatically renewed prior to expiry. -
[domain='circuitsandbox.net']
String optionalThe domain of the Circuit server to use. Defaults to circuitsandbox.net.
-
[enableTelephony=false]
Boolean optionalSet to true to register for support incoming telephony calls. Requires 'calls' scope and a configured telephony connector for the tenant.
-
[emoticonMode='standard']
String optionalstandard
orcircuit
. In standard mode the Circuit encoding is converted to standard unicode. -
[removeMentionHtml=false]
Boolean optionalIf
true
span element for mention is removed and only the mentioned user's name is shown. -
[redirect_uri]
String optionalOptional. URL to redirect to upon successfull OAuth. Prevents unnesecarry rendering or parent page URL in OAuth popup.
-
Item Index
Methods
- addAppMessageListener
- addEventListener
- addLabels
- addParticipant
- addParticipantToCall
- addParticipantToRtcSession
- addTextItem
- addWhiteboardElement
- answerCall
- archiveConversation
- assignLabels
- cancelSearch
- changeConversationPin
- changeHDVideo
- changePassword
- changeVideoResolution
- clearWhiteboard
- clearWhiteboardBackground
- createCommunity
- createConferenceBridge
- createDirectConversation
- createGroupConversation
- createIncomingWebhook
- deleteIncomingWebhook
- deleteRecording
- deleteTextItem
- dialNumber
- disableGuestAccess
- disableWhiteboard
- dropModeratorRights
- dropParticipant
- editLabel
- enableGuestAccess
- enableWhiteboard
- endCall
- endConference
- endRemoteCall
- favoriteConversation
- findCall
- flagItem
- getAccounts
- getActiveCall
- getActiveRemoteCalls
- getAllLabels
- getArchivedConversations
- getAudioVideoStats
- getCalls
- getConferenceInvitationText
- getConversationById
- getConversationDetails
- getConversationFeed
- getConversationItems
- getConversationParticipants
- getConversations
- getConversationsByFilter
- getConversationsByIds
- getConversationsByLabel
- getConversationsByType
- getConversationTopics
- getCookie
- getDevices
- getDirectConversationWithUser
- getFavoriteConversationIds
- getFlaggedItems
- getIncomingWebhook
- getIncomingWebhooks
- getItemById
- getItemsById
- getItemsByThread
- getJournalEntries
- getLastRtpStats
- getLocalAudioVideoStream
- getLocalScreenshareStream
- getLoggedOnUser
- getMarkedConversations deprecated
- getMaxVideoResolution
- getPresence
- getRemoteStreams
- getStartedCalls
- getStatusMessage
- getSupportConversation
- getSupportConversationId
- getSupportInfo
- getTelephonyConversationId
- getTelephonyData
- getTenantUsers deprecated
- getUserByEmail
- getUserById
- getUsersByEmail
- getUsersById
- getUserSettings
- getWhiteboard
- grantModeratorRights
- isAuthenticated
- isCompatible
- joinCommunity
- joinConference
- leaveConference
- likeItem
- logon
- logonCheck
- logout
- makeCall
- markItemsAsRead
- moderateConversation
- mute
- muteDevice
- muteParticipant
- muteRtcSession
- navigateToConversation
- pullRemoteCall
- removeAppMessageListener
- removeLabels
- removeParticipant
- removeWhiteboardElement
- renewSessionToken
- renewToken
- revokeToken
- sendAppMessageToClient
- sendAppMessageToUser
- sendClickToAnswerRequest
- sendClickToCallRequest
- sendDigits
- setAudioVideoStream
- setCallForwarding
- setCookie
- setMediaDevices
- setOauthConfig
- setPresence
- setScreenshareStream
- setStatusMessage
- setUserSettings
- setWhiteboardBackground
- startAdvancedUserSearch
- startBasicSearch
- startConference
- startRecording
- startUserSearch
- stopRecording
- submitForm
- subscribePresence
- subscribeTenantPresence
- subscribeTypingIndicator
- supportedFeatures
- suspendIncomingWebhook
- switchRecordingLayout
- toggleRemoteAudio
- toggleScreenShare
- toggleVideo
- toggleWhiteboardOverlay
- typing
- unarchiveConversation
- unassignLabels
- undoWhiteboard
- unfavoriteConversation
- unflagItem
- unlikeItem
- unmoderateConversation
- unmute
- unsubscribePresence
- unsubscribeTenantPresence
- unsubscribeTypingIndicator
- unsuspendIncomingWebhook
- updateConversation
- updateIncomingWebhook
- updateTextItem
- updateUser
- uploadCustomVoicemailGreeting
- validateToken
Events
- accessTokenRenewed
- basicSearchResults
- callEnded
- callIncoming
- callNetworkQualityChanged (Unified plan enabled)
- callRtpThresholdCleared
- callRtpThresholdReached
- callStatus
- connectionStateChange
- conversationArchived
- conversationCreated
- conversationFavorited
- conversationReadItems
- conversationUnarchived
- conversationUnfavorited
- conversationUpdated
- conversationUserDataChanged
- formSubmission
- itemAdded
- itemFlagged
- itemUnflagged
- itemUpdated
- labelEdited
- labelsAdded
- labelsRemoved
- loggedOnUserUpdated
- mention
- passwordChanged
- reconnectFailed
- renewAccessTokenFailed
- renewSessionTokenFailed
- searchStatus
- sessionClosed
- sessionExpiring
- sessionTokenRenewed
- systemMaintenance
- typing
- userPresenceChanged
- userSettingsChanged
- userUpdated
- whiteboardBackground
- whiteboardCleared
- whiteboardConversionFailed
- whiteboardElement
- whiteboardEnabled
- whiteboardOverlayToggled
- whiteboardSync
Methods
addAppMessageListener
Syntax
addAppMessageListener
-
type
-
cb
Summary
Add listener for messages sent via sendAppMessageToUser
or sendAppMessageToClient
.
USER_TO_USER
Returns:
Example:
client.addAppMessageListener('channel1', (msg, routing) => {
console.log(Message received
, msg);
});
addEventListener
Syntax
Summary
Register for Circuit events such as new a new message, incoming call, connection state change, etc.
Parameters:
-
type
StringEvent type such as
itemAdded
Returns:
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
Summary
Creates one or more new labels.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
labels
String[]Array of strings containing the names of the labels.
Example:
client.addLabels(['My new label', 'Antoher new label'])
.then(labels => console.log(Created ${labels.length} new labels
));
addParticipant
Syntax
Summary
Add new participants to a group conversation or community.
WRITE_CONVERSATIONS
or MANAGE_CONVERSATIONS
Parameters:
Returns:
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
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.
CALLS
Parameters:
-
callId
StringcallId of the call.
-
to
ObjectObject literal containing dial out information
-
[userId]
String optionaluserId of participant to add to call. For a PSTN call the userId may be omitted.
-
[email]
String optionalemail of participant to add to call. Omitted if userId is present. For a PSTN call the email may be omitted.
-
[number]
String optionalPhone number to dial. Not applicable to WebRTC dial-out.
-
[displayName]
String optionalDisplay name of user to dial. Not applicable to WebRTC dial-out.
-
Returns:
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
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.
CALLS
Parameters:
-
callId
StringcallId of the call.
-
to
ObjectObject literal containing dial out information
-
[userId]
String optionaluserId of participant to add to call. For a PSTN call the userId may be omitted.
-
[email]
String optionalemail of participant to add to call. Omitted if userId is present. For a PSTN call the email may be omitted.
-
[number]
String optionalPhone number to dial. Not applicable to WebRTC dial-out.
-
[displayName]
String optionalDisplay name of user to dial. Not applicable to WebRTC dial-out.
-
Returns:
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
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 😎
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?
WRITE_CONVERSATIONS
or CREATE_CONVERSATIONS_CONTENT
. READ_USER
if using mentions.
Parameters:
-
convId
StringConversation ID
-
content
Object | StringContent for text message. Either an object literal, or a string.
-
[parentId]
String optionalItem ID of parent post if this is a reply.
-
[contentType]
TextItemContentType optionalDefault 'RICH'. Whether the content is rich text (HTML) or plain text.
-
[subject]
String optionalSubject/Title of message. Only supported for parent post (i.e. parentId omitted)
-
[content]
String optionalActual text content.
-
[attachments]
File[] optionalArray of File objects objects.
-
[form]
FormMetadata optionalForm object. See https://github.com/circuit/circuit-sdk/wiki/Forms for details.
-
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 😎';
addWhiteboardElement
Syntax
Summary
Add a whiteboard element (e.g. circle, line, freehand) to the whiteboard.
CALLS
Parameters:
Returns:
A promise that is resolved when the drawing has been sent to the peers.
Example:
client.addWhiteboardElement('8f365bf3-97ea-4d54-acc7-2c4801337521',
. '
answerCall
Syntax
Summary
Answer an incoming call received in a callIncoming event.
CALLS
Parameters:
Returns:
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
Summary
Archive a conversation. Succeeds if conversation is already archived.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
convId
StringConversation ID
Returns:
A promise without data
Example:
client.archiveConversation('d353db50-b835-483e-9fce-2b157b2253d3')
.then(() => console.log('Conversation archived'));
assignLabels
Syntax
Summary
Assigns specified labels to the given conversation.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
Returns:
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
Summary
Cancel a pending search. E.g. startBasicSearch, startUserSearch
READ_USER
, READ_CONVERSATIONS
, or SEARCH_CONVERSATIONS
Parameters:
-
searchId
StringSearch ID of the pending search
Returns:
A promise without data
Example:
client.cancelSearch('c4cbbf23-cdcd-4824-881d-fea0c77c8f50')
.then(() => console.log('Search cancelled');
changeConversationPin
Syntax
Summary
Change the PIN of a conversation.
READ_CONVERSATIONS
Parameters:
-
conversation
StringConversation ID
Returns:
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
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.
CALLS
Parameters:
-
callId
StringcallId of the call.
-
hdQuality
Booleantrue to enable streaming HD quality up to 1920x1080.
-
resolution
VideoResolutionLevelVideo resolution, defaults to 1080p.
Returns:
A promise that is resolved when action is complete.
Example:
client.changeHDVideo('8f365bf3-97ea-4d54-acc7-2c4801337521', true)
.then(() => console.log('Successful'));
changePassword
Syntax
Summary
Change the password of the current user. Will popup password change page. Fires passwordChanged
event.
WRITE_USER_PROFILE
Returns:
A promise without data
Example:
client.changePassword()
.then(() => console.log('Successfully changed password'));
changeVideoResolution
Syntax
Summary
Change the video resolution of an established call. Unlike changeHDVideo this API allows changing the HD resolution if already in an HD call.
CALLS
Parameters:
-
callId
StringcallId of the call.
-
resolution
VideoResolutionLevelVideo resolution
Returns:
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
Summary
Clear a whiteboard.
CALLS
Parameters:
Returns:
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
Summary
Clear the background of the whiteboard.
CALLS
Parameters:
-
callId
StringCall ID of the call.
Returns:
A promise without data.
Example:
client.clearWhiteboardBackground('8f365bf3-97ea-4d54-acc7-2c4801337521')
.then(() => console.log('Successfully cleared the background'));
createCommunity
Syntax
Summary
Create a new community.
WRITE_CONVERSATIONS
or MANAGE_CONVERSATIONS
Parameters:
Returns:
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
Summary
Create a new conference bridge conversation.
Requires the following scope: WRITE_CONVERSATIONS
WRITE_CONVERSATIONS
or MANAGE_CONVERSATIONS
Parameters:
-
topic
StringTopic of conversation
Returns:
A promise returning the created conversation
Example:
client.createConferenceBridge('Sales Call')
.then(conv => console.log(Conversation created
, conv));
createDirectConversation
Syntax
Summary
Create a new direct conversation.
Requires the following scope: WRITE_CONVERSATIONS
WRITE_CONVERSATIONS
or MANAGE_CONVERSATIONS
Parameters:
-
participant
StringUser ID or email of the user to create a conversation with
Returns:
Example:
client.createDirectConversation('bob@example.com')
.then(res => {
let str = res.alreadyExists ? 'already exists' : 'is new';
console.log(Conversation ${str}
, res.conversation);
});
createGroupConversation
Syntax
Summary
Create a new group conversation.
Requires the following scope: WRITE_CONVERSATIONS
WRITE_CONVERSATIONS
or MANAGE_CONVERSATIONS
Parameters:
Returns:
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
Summary
Creates a new webhook for a conversation.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
Returns:
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
Summary
Deletes a webhook.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
webhookId
StringId of the webhook to be deleted.
Returns:
A promise without data
Example:
client.deleteIncomingWebhook('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
.then(() => console.log('Webhook deleted.'))
.catch(console.error);
deleteRecording
Syntax
Summary
Delete a recording.
WRITE_CONVERSATIONS
, DELETE_CONVERSATIONS_CONTENT
, or CALL_RECORDING
Parameters:
-
Item
StringID of item to remove the recording from.
Returns:
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
Summary
Delete a text item.
WRITE_CONVERSATIONS
Parameters:
-
itemId
StringConversation Item ID of item to delete.
Example:
const itemId = 'e8b72e0e-d2d1-46da-9ed4-7378759314488';
client.deleteTextItem(itemId)
.then(console.log);
dialNumber
Syntax
Summary
Start a telephony call from this client.
CALLS
Parameters:
Example:
client.dialNumber('+15615551111', 'Bob Smith')
.then(call => console.log('New telephony call: ', call));
disableGuestAccess
Syntax
Summary
Disable guest access on a conversation.
WRITE_CONVERSATION
or MODERATE_CONVERSATIONS
Parameters:
-
convId
StringConversation ID.
Returns:
A promise without data.
Example:
client.disableGuestAccess('338d2002-ae68-495c-aa5c-1dff3fbc845a')
.then(() => console.log('Successfully disabled guest access'));
disableWhiteboard
Syntax
Summary
Disable the whiteboard feature on an active RTC call/conference.
CALLS
Parameters:
-
callId
StringCall ID of the call.
Returns:
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
Summary
Drop moderator rights to participants.
WRITE_CONVERSATION
or MODERATE_CONVERSATIONS
Returns:
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
Summary
Remove participant of a group call.
CALLS
Parameters:
Returns:
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
Summary
Edit a given label.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
label
LabelLabel object containing the labelId and name of the Label.
Example:
client.editLabel({
labelId: 'd353db50-b835-483e-9fce-2b157b2253d3',
value: 'My new label'
})
.then(label => console.log(Label: ${label.value}
));
enableGuestAccess
Syntax
Summary
Enable guest access on a conversation.
WRITE_CONVERSATION
or MODERATE_CONVERSATIONS
Parameters:
-
convId
StringConversation ID.
Returns:
A promise without data.
Example:
client.enableGuestAccess('338d2002-ae68-495c-aa5c-1dff3fbc845a')
.then(() => console.log('Successfully enabled guest access'));
enableWhiteboard
Syntax
Summary
Enable the whiteboard feature on an active RTC call/conference.
CALLS
Parameters:
Returns:
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
Summary
End a direct call or leave a group conference.
CALLS
Parameters:
-
callId
StringcallId of the call to end.
Returns:
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
Summary
End a conference call. Disconnects all other participants as well.
CALLS
Parameters:
-
callId
StringcallId of the call to leave.
Returns:
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
Summary
End a remote call.
CALLS
Parameters:
-
callId
StringcallId of the call to end.
Returns:
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
Summary
Add a conversation to the favorite list. Succeeds if conversation is already favorited.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
convId
StringConversation ID
Returns:
A promise without data
Example:
client.favoriteConversation('d353db50-b835-483e-9fce-2b157b2253d3')
.then(() => console.log('Conversation added to favorites'));
findCall
Syntax
Summary
Find a call by its call ID. Call may be local or remote, active or non-active.
CALLS
Parameters:
-
callId
StringcallId of the call to find.
Example:
client.findCall('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
.then(call => console.log('Call found: ', call));
flagItem
Syntax
Summary
Flag an item. Flags are user specific.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Returns:
A promise without data
Example:
client.flagItem('8fc29770-84ab-4ace-9e85-3269de707499', '874c528c-1410-4362-b519-6e7d26a2edb2')
.then(() => console.log('Successfully flagged'));
getAccounts
Syntax
Summary
Get the accounts, including users for this tenant/domain. This API requires tenant admin priviledges.
USER_MANAGEMENT
tenant administrators have the user management permission by default
Parameters:
-
[options]
Object optionalLiteral object with filter options
-
[pageSize]
String optionalPage size. Default is 25. Maximum is 100.
-
[sorting]
String optionalSorting as defined in Circuit.Enums.GetAccountsSorting. Default is
BY_FIRST_NAME
-
[ordering]
String optionalOrdering as defined in Circuit.Enums.SortOrder. Default is
ASCENDING
-
[searchPointer]
String optionalTransparent string required to retrieve next results page
-
[searchCriterias]
Array optionalArray of literal objects for optional search criterias
-
[searchCriterias[].criteria]
String optionalCriteria as defined in Circuit.Enums.GetAccountsFilterCriteria
-
[searchCriterias[].value]
String optionalCriteria value, e.g. "Rog"
-
Returns:
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
Summary
Get local active call.
CALLS
Example:
client.getActiveCall()
.then(call => console.log('Active local call: ', call));
getActiveRemoteCalls
Syntax
Summary
Get remote active calls.
CALLS
Example:
client.getActiveRemoteCalls()
.then(calls => console.log(Active remote calls: ${calls.length}
));
getAllLabels
Syntax
Summary
Retrieve all labels.
READ_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Example:
client.getAllLabels()
.then(labels => console.log(Found: ${labels.length} labels
));
getArchivedConversations
Syntax
Summary
Retrieve archived conversations
READ_CONVERSATIONS
Parameters:
-
[options]
Object optionalObject literal containing paging and other options
-
[number]
Number optionalMaximum number of conversations to retrieve. Default is 10.
-
[timestamp]
Number optionalConversations created before this timestamp are returned. Used for paging.
-
[numberOfParticipants]
Number optionalMaximum number of participants to return in the participants array. Default is 8.
-
Returns:
A promise returning a list of archived conversations
Example:
client.getArchivedConversations({number: 10})
.then(convs => console.log(Found: ${convs.length} conversations
));
getAudioVideoStats
Syntax
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.
CALLS
Returns:
A Promise containing RTCStatsReport object when successful
Example:
client.getAudioVideoStats()
.then(stats => stats.forEach(console.log))
.catch(console.error);
getCalls
Syntax
Summary
Get all local and remote calls in progress.
CALLS
Example:
client.getCalls()
.then(calls => console.log(Calls in progress: ${calls.length}
));
getConferenceInvitationText
Syntax
Summary
Get the conference invitation HTML
READ_CONVERSATIONS
Parameters:
Returns:
Example:
client.getConferenceInvitationText('EN_US', 'b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
.then(conferenceText => console.log('Conference Text: ', conferenceText));
getConversationById
Syntax
Summary
Retrieve a single conversations by its ID.
READ_CONVERSATIONS
Parameters:
-
convId
StringConversation ID
Returns:
A promise returning a conversation
Example:
client.getConversationById('d353db50-b835-483e-9fce-2b157b2253d3')
.then(conversation => console.log('Returned conversation: ', conversation));
getConversationDetails
Syntax
Summary
Get the conversation details such as the bridge numbers and guest link.
READ_CONVERSATIONS
Parameters:
-
conversation
StringConversation ID
Returns:
A promise returning the conversation details.
Example:
client.getConversationDetails('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
.then(convDetails => console.log('Conversation details: ', convDetails));
getConversationFeed
Syntax
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.
READ_CONVERSATIONS
Parameters:
-
convId
StringConversation ID
-
[options]
Object optionalObject literal containing options
-
[timestamp]
Number optionalDefines 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 optionalMinimum number of comments to retrieve. Defaults to 25.
-
[maxTotalUnread]
Number optionalMaximum number of unread items to retrieve. Defaults to 500.
-
[commentsPerThread]
Number optionalMinimum number of comments per thread (up to 3) to retrieve. Defaults to 3.
-
[maxUnreadPerThread]
Number optionalMaximum number of unread comments per thread to retrieve. Defaults to 50.
-
Returns:
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
Summary
Retrieve multiple conversation items. By default the most recent items are returned.
READ_CONVERSATIONS
Parameters:
-
convId
StringConversation ID
-
[options]
Object optionalObject literal containing options
-
[modificationDate]
Number optionalMutually exclusive with creationDate. Defaults to current timestamp.
-
[creationDate]
Number optionalMutually exclusive with modificationDate. Defaults to current timestamp.
-
[direction]
SearchDirection optionalWhether to get items
BEFORE
orAFTER
a certain timestamp. Default isBEFORE
. -
[numberOfItems]
Number optionalMaximum number of conversation items to retrieve. Default 25.
-
Example:
client.getConversationItems('cc02d9ca-fb10-4a86-96b3-0198665525b8', {direction: 'AFTER'})
.then(items => console.log(Returned ${items.length} items
));
getConversationParticipants
Syntax
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.
READ_CONVERSATIONS
Parameters:
-
convId
StringConversation ID
-
[options]
Object optionalObject literal containing options
-
[searchCriterias]
ParticipantSearchCriteria[] optionalA list of search criterias that are used to filter the participants. Criterias are using an AND operation.
-
[searchPointer]
String optionalUsed for paging of results. Each results page returns a searchPointer that is to be used to fetch the next page.
-
[pageSize]
Number optionalNumber of participants per page. Maximum is 100.
-
[includePresence]
Boolean optionalIf set to true this will add the presence state of the user to the returned participant object. Default is false.
-
Returns:
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
Summary
Retrieve conversations.
READ_CONVERSATIONS
Parameters:
-
[options]
Object optionalObject literal containing options
-
[direction]
SearchDirection optionalDefines 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 optionalTimestamp used in conjunction with the direction parameter. Default is no timestamp, causing most recent conversations to be returned.
-
[numberOfConversations]
Number optionalMaximum number of conversations to retrieve. Default is 25.
-
[numberOfParticipants]
Number optionalMaximum number of participants to return in the participants array. Default is 8.
-
Returns:
A promise returning an array of Conversations.
Example:
client.getConversations({numberOfConversations: 10})
.then(conversations => console.log(Returned ${conversations.length} conversations
));
getConversationsByFilter
Syntax
Summary
Retrieve conversations or conversation IDs by a filter. A filter contains conditions specifying one or more labels or archived/muted indication.
READ_CONVERSATIONS
Parameters:
-
[options]
Object optionalObject literal containing filter parameters
-
[filterConnector]
FilterConnector optionalObject defining the filter criteria. Required.
-
[number]
Number optionalMaximum number of conversations to retrieve. Default is 10.
-
[timestamp]
Number optionalConversations created before this timestamp are returned. Used for paging.
-
[numberOfParticipants]
Number optionalMaximum number of participants to return in the participants array. Default is 8.
-
[retrieveAction]
RetrieveAction optionalInfluences the data returned. Conversations (with paging support) or all Conversation IDs. Defaults to
CONVERSATIONS
.
-
Returns:
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
Summary
Retrieve conversations by their IDs.
READ_CONVERSATIONS
Parameters:
-
convIds
ArrayArray of Conversation IDs
Returns:
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
Summary
Retrieve conversations with a specified label
READ_CONVERSATIONS
Parameters:
-
labelId
StringLabel ID
-
[options]
Object optionalObject literal containing paging and other options
-
[number]
Number optionalMaximum number of conversations to retrieve. Default is 10.
-
[timestamp]
Number optionalConversations created before this timestamp are returned. Used for paging.
-
[numberOfParticipants]
Number optionalMaximum number of participants to return in the participants array. Default is 8.
-
Returns:
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
Summary
Retrieve conversations with a specified type
READ_CONVERSATIONS
Parameters:
-
conversationType
ConversationTypeType of conversations to retrieve.
-
[options]
Object optionalObject literal containing paging and other options
-
[number]
Number optionalMaximum number of conversations to retrieve. Default is 25.
-
[timestamp]
Number optionalConversations created before this timestamp are returned. Used for paging.
-
[numberOfParticipants]
Number optionalMaximum number of participants to return in the participants array. Default is 8.
-
Returns:
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
Summary
Retrieve conversation topics.
READ_CONVERSATIONS
Parameters:
Returns:
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
Summary
Get the authentication cookie.
Returns:
cookie
Example:
let cookie = client.getCookie();
getDevices
Syntax
Summary
Retrieve devices the user is logged in with.
READ_CONVERSATIONS
or READ_USER_PROFILE
Example:
client.getDevices()
.then(devices => console.log('Device count: ', devices.length));
getDirectConversationWithUser
Syntax
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.
READ_CONVERSATIONS
Parameters:
Returns:
A promise returning a the conversation
Example:
client.getDirectConversationWithUser('bob@unify.com')
.then(console.log);
getFavoriteConversationIds
Syntax
Summary
Retrieve favorited conversation IDs.
READ_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Example:
client.getFavoriteConversationIds()
.then(favoriteConvIds => console.log(Favs: ${favoriteConvIds.length}
));
getFlaggedItems
Syntax
Summary
Get all flagged items.
READ_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Returns:
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
Summary
Get a webhook by its ID.
READ_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
webhookId
StringId of the webhook to be retrieved.
Returns:
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
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.
READ_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
searchCondition
Object-
pageSize
StringThe 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 optionalId of the tenant to return webhooks for.
-
[userId]
String optionalId of the user to return webhooks for.
-
[conversationId]
String optionalId of the conversation to return webhooks for.
-
[searchPointer]
String optionalThe search pointer used for paging.
-
Returns:
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
Summary
Retrieve a single conversation item by its ID.
READ_CONVERSATIONS
Parameters:
-
itemId
StringConversation Item ID
Example:
client.getItemById('cc02d9ca-fb10-4a86-96b3-0198665525b8')
.then(console.log);
getItemsById
Syntax
Summary
Retrieve multiple conversation items by their ID.
READ_CONVERSATIONS
Parameters:
-
itemIds
String[]Conversation Item IDs
Example:
client.getItemsById(['cc02d9ca-fb10-4a86-96b3-0198665525b8'])
.then(console.log);
getItemsByThread
Syntax
Summary
Retrieve conversation items of a thread, not including the parent item.
READ_CONVERSATIONS
Parameters:
-
convId
StringConversation ID
-
threadId
StringThread ID
-
[options]
Object optionalObject literal containing options
-
[modificationDate]
Number optionalDefines 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 optionalDefines 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 optionalWhether to get items
BEFORE
orAFTER
a certain timestamp. -
[number]
Number optionalMaximum number of conversation items to retrieve. Default (-1) is to retrieve all items of a thread.
-
Returns:
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
Summary
Retrieve telephony call journals of logged on user.
READ_CONVERSATIONS
Parameters:
-
[options]
Object optional-
[journalFilter]
JournalFilter optionalfilter constraints used for what to retrieve. Defaults to ALL.
-
[timestamp]
Boolean optionalTimestamp used in conjunction with the direction parameter. Default is no timestamp, causing most recent conversations to be returned.
-
[direction]
String optionalWhether to get items
BEFORE
orAFTER
a certain timestamp. Default isBEFORE
. -
[numberOfEntries]
String optionalNumber of entries to retrieve.
-
Example:
client.getJournalEntries({ journalFilter: Circuit.Enums.JournalFilter.VOICEMAILS })
.then(voicemails => console.log(There are ${voicemails.length} voicemails
));
getLastRtpStats
Syntax
getLastRtpStats
-
callId
Summary
Get the RTP call statistics of the last stats collection interval (every 5 sec by default)
CALLS
Parameters:
-
callId
Stringcall ID
Returns:
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
Summary
Get the local video stream (audio/video)
CALLS
Returns:
A promise containing the MediaStream
Example:
client.getLocalAudioVideoStream()
.then(stream => console.log(stream));
getLoggedOnUser
Syntax
Summary
Get the logged on user.
READ_USER_PROFILE
Example:
client.getLoggedOnUser()
.then(user => console.log('Client is authenticated: ' + user.displayName));
getMarkedConversations
Syntax
Summary
Retrieve all marked (muted and favorited) conversation IDs.
READ_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Returns:
Example:
client.getMarkedConversations()
.then(res => console.log(Muted: ${res.mutedConvIds.length}, Favs: ${res.favoriteConvIds.length}
));
getMaxVideoResolution
Syntax
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.
CALLS
Parameters:
-
deviceId
Stringdevice ID obtained via navigator.mediaDevices.enumerateDevices().
Returns:
A promise containing the resolution (Circuit.Enums.VideoResolution)
Example:
client.getMaxVideoResolution('97cbef604ce613e5a024f66b5b7c1ced3cd854b1dd132a2729dd0d2f62558956')
.then(resolution => console.log('Max resolution is' + resolution));
getPresence
Syntax
Summary
Get the presence for a list of user IDs.
READ_USER
Parameters:
Example:
client.getPresence(['72ee640f-9ac3-4275-b9ec-46d08e499c5a'])
.then(presenceList => console.log('Presence objects for requested users: ', presenceList));
getRemoteStreams
Syntax
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.
CALLS
Parameters:
-
callId
Stringcall ID
Returns:
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
Summary
Get calls in Started
state, meaning the conference has started but the user has not yet joined.
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.
READ_USER_PROFILE
Returns:
Promise A promise containing the status message
Example:
client.getStatusMessage()
.then(statusMessage => console.log('Status message is: ', statusMessage));
getSupportConversation
Syntax
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.
READ_CONVERSATIONS
Returns:
A promise returning a conversation
Example:
client.getSupportConversation()
.then(conversation => console.log('Returned conversation: ', conversation));
getSupportConversationId
Syntax
Summary
Get the special support conversation ID. The support conversation is a special conversation the user can report problems with.
WRITE_CONVERSATIONS
or READ_CONVERSATIONS
Returns:
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
READ_USER_PROFILE
Returns:
Support Info object
Example:
client.getSupportInfo()
.then(supportInfo => console.log('Support Info: ' + supportInfo));
getTelephonyConversationId
Syntax
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.
READ_CONVERSATIONS
Returns:
Telephony Conversation ID
Example:
client.getTelephonyConversationId()
.then(convId => console.log('Telephony Conversation ID: ' + convId));
getTelephonyData
Syntax
Summary
Get the telephony data such as the connection state and default caller ID.
CALLS
Example:
client.getTelephonyData()
.then(console.log);
getTenantUsers
Syntax
Summary
Get the users for this tenant/domain. This API requires tenant admin priviledges.
USER_MANAGEMENT
tenant administrators have the user management permission by default
Parameters:
Example:
client.getTenantUsers({pageSize: 10, sorting: Constants.GetAccountsSorting.BY_LAST_NAME})
.then(users => console.log('First batch of users', users));
getUserByEmail
Syntax
Summary
Retrieve a user by its email.
READ_USER
Parameters:
Example:
const user = await client.getUserByEmail({
emailAddress: 'bob@example.com',
secondaryLookup: true
});
const user = await client.getUserByEmail('bob@example.com');
getUserById
Syntax
Summary
Retrieve user by its ID.
READ_USER
Parameters:
-
userId
StringUser ID
Example:
client.getUserById('d353db50-b835-483e-9fce-2b157b2253d3')
.then(user => console.log('User is:', user));
getUsersByEmail
Syntax
Summary
Retrieve users by their email address.
READ_USER
Parameters:
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
Summary
Retrieve users by their ID.
READ_USER
Parameters:
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.
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
Summary
Get the complete whiteboard drawing.
CALLS
Parameters:
-
callId
StringCall ID of the call.
Returns:
A promise containing the whiteboard drawing.
Example:
client.getWhiteboard('8f365bf3-97ea-4d54-acc7-2c4801337521')
.then(board => console.log('Successfully retrieved the whiteboard'));
grantModeratorRights
Syntax
Summary
Grant moderator rights to participants.
WRITE_CONVERSATION
or MODERATE_CONVERSATIONS
Returns:
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
Summary
Check if browser is compatible. Use supports
API for supported features on the current browser.
Returns:
true if browser is compatible
joinCommunity
Syntax
Summary
Join a community.
WRITE_CONVERSATIONS
or MANAGE_CONVERSATIONS
Parameters:
-
convId
StringConversation ID
Returns:
A promise returning the joined community
Example:
client.joinCommunity('35fefd79-6a56-49fd-b585-9a0373253eeb')
.then(community => console.log(Joined community:
, community));
joinConference
Syntax
Summary
Join a conference call from the current device, or optionally from another logged on device.
CALLS
Parameters:
Returns:
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
Summary
Leave a conference call.
CALLS
Parameters:
-
callId
StringcallId of the call to leave.
Returns:
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
Summary
Like an item. Likes will be seen by others.
WRITE_CONVERSATIONS
or UPDATE_CONVERSATION_CONTENT
Parameters:
-
itemId
StringItem ID of item to be liked
Returns:
A promise without data
Example:
client.likeItem('874c528c-1410-4362-b519-6e7d26a2edb2')
.then(() => console.log('Successfully liked item'));
logon
Syntax
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 optionalOptional object with OAuth2 access token, or API token
-
[accessToken]
String optionalOAuth2 access token
-
[prompt]
String optionalIf 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 optionalIf 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 optionalIf set to true, then the app is responsible to obtain and validate access token. Used for native apps like Ionic.
-
[username]
String optionalUsername (email) for Resource Owner Grant Type
-
[password]
String optionalPassword for Resource Owner Grant Type
-
[token]
String optionalAPI token (deprecated)
-
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
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:
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
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 optionalSetting force to true also terminates the Circuit connection of other browser tabs
Returns:
A promise without data
Example:
client.logout();
makeCall
Syntax
Summary
Start a direct call with a user by its email address or user ID.
CALLS
(also requires WRITE_CONVERSATIONS
if a conversation needs to be created)
Parameters:
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
Summary
Mark all items of the specified conversation, before a timestamp as read.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
Returns:
A promise without data
Example:
client.markItemsAsRead('338d2002-ae68-495c-aa5c-1dff3fbc845a')
.then(() => console.log('done'));
moderateConversation
Syntax
Summary
Moderate a conversation.
WRITE_CONVERSATION
or MODERATE_CONVERSATIONS
Parameters:
-
convId
StringConversation ID.
Returns:
A promise without data.
Example:
client.moderateConversation('338d2002-ae68-495c-aa5c-1dff3fbc845a')
.then(() => console.log('Successfully moderated conversation'));
mute
Syntax
Summary
Mute an existing call.
CALLS
Parameters:
-
callId
StringcallId of the call to mute.
Returns:
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
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.
CALLS
Parameters:
-
callId
StringThe call ID of the call
-
[destClientId]
String optionalClientID of device to mute the call. Only web clients supported. If none provided, first webclient found is used.
-
[option]
Object optionalLiteral object with
mic
orspeaker
boolean attributes. Defaults to true for mic and speaker.
Returns:
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
Summary
Mute a remote participant.
CALLS
Returns:
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
Summary
Mute all participants except the current user.
CALLS
Parameters:
-
callId
StringCall ID.
Returns:
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'));
pullRemoteCall
Syntax
Summary
Pull a remote call to the local device.
CALLS
Parameters:
Returns:
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.
USER_TO_USER
Example:
client.removeAppMessageListener('channel1', myHandler);
client.removeAppMessageListener('channel1');
client.removeAppMessageListener();
removeLabels
Syntax
Summary
Unassigns the labels from their conversations and removes the labels.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
labelIds
String[]Array of label Ids to be removed
Example:
client.removeLabels('d353db50-b835-483e-9fce-2b157b2253d3')
.then(labels => console.log(${labels.length} labels have been removed
));
removeParticipant
Syntax
Summary
Remove a participant from a group conversation or community.
WRITE_CONVERSATIONS
or MANAGE_CONVERSATIONS
Returns:
A promise without data
Example:
client.removeParticipant('8fc29770-84ab-4ace-9e85-3269de707499', '874c528c-1410-4362-b519-6e7d26a2edb2')
.then(() => console.log('Successfully removed'));
removeWhiteboardElement
Syntax
Summary
Remove a whiteboard element.
CALLS
Returns:
A promise that is resolved when the drawing has been removed.
Example:
client.addWhiteboardElement('8f365bf3-97ea-4d54-acc7-2c4801337521',
. '
renewSessionToken
Syntax
Summary
Renew the session token of the current user. This is the authentication session, not the OAuth token.
Returns:
A promise without data
Example:
client.renewSessionToken()
.then(() => console.log('Session token renewed'));
renewToken
Syntax
Summary
Renew the OAuth2 access token of the current user.
Example:
client.renewToken()
.then(token => console.log('New access token is: ' + token));
revokeToken
Syntax
Summary
Revoke the OAuth2 access token.
Parameters:
-
[token]
String optionalIf omitted, the internally used token is revoked.
Returns:
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.
USER_TO_USER
Parameters:
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.
USER_TO_USER
Parameters:
Example:
client.sendAppMessageToUser('channel1', 'b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', {
reqId: '1234',
msgName: 'CHAT_REQ',
text: 'Hello World'
})
.then(() => console.log(Message sent
));
sendClickToAnswerRequest
Syntax
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.
CALLS
Parameters:
Returns:
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
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.
CALLS
Parameters:
-
target
Stringemail address or phone number of user to call
-
[mediaType]
String optionalaudio
orvideo
. Defaults to 'audio'. -
[destClientId]
String optionalClientID of device to initiate the call.
-
[noLaunch]
String optionalIf 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:
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
Summary
Send DTMF digits in active local call.
CALLS
Returns:
A promise returning no content.
Example:
client.sendDigits('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', '5')
.then(() => console.log('Digits sent'));
setAudioVideoStream
Syntax
Summary
Set the media stream for audio/video to be transmitted in the active call.
CALLS
Parameters:
-
callId
StringcallId of the call to add/remove a media stream.
-
stream
MediaStreamAudio/Video MediaStream to send.
-
[mediaType]
MediaType optionalMedia type for the call. If not set, audio/video is set based on tracks in stream.
Returns:
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.
USER_TO_USER
, READ_USER
, and READ_CONVERSATIONS
Parameters:
Returns:
Promise A promise without data
Example:
client.setCallForwarding({status: true, number: '15611234567'})
.then(() => console.log('Call forwarding settings updated'));
setCookie
Syntax
setCookie
-
cookie
Summary
Set the authentication cookie to be used for XMLHttpRequests and WebSockets.
Parameters:
-
cookie
StringSet the cookie to be used.
Returns:
Example:
client.setCookie(myCookie);
setMediaDevices
Syntax
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.
CALLS
Parameters:
-
devices
ObjectLiteral object containing the playback, recording, video and ringing device IDs.
-
[playback]
String | String[] optionalPlayback (audio output) media device ID, or array of IDs.
-
[recording]
String | String[] optionalRecording (audio input) media device ID, or array of IDs.
-
[video]
String | String[] optionalVideo (camera) media device ID, or array of IDs.
-
[ringing]
String | String[] optionalRinging media device ID, or array of IDs.
-
Returns:
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
ObjectObject literal containing the OAuth2 configuration parameters
-
[client_id]
String optionalThe OAuth2 client ID you obtain from the Developer Portal. Identifies the client that is making the request.
-
[client_secret]
String optionalThe OAuth2 client secret you obtain from the Developer Portal. Applicable for
client credentials
grant type used for Node.js apps. -
[scope]
String optionalComma-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
Summary
Set the presence of the logged on user.
WRITE_USER_PROFILE
or MANAGE_PRESENCE
Parameters:
-
presence
PresencePresence object
Returns:
A promise without data
Example:
client.setPresence({state: Circuit.Enums.PresenceState.AVAILABLE})
.then(() => console.log('Presence updated'));
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.
WRITE_USER_PROFILE
or MANAGE_PRESENCE
Parameters:
-
statusMessage
StringStatus 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.
WRITE_USER_PROFILE
Parameters:
-
userSettings
UserSettingsUser 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
Summary
Set the background of the whiteboard.
CALLS
Returns:
A promise without data.
Example:
client.setWhiteboardBackground('8f365bf3-97ea-4d54-acc7-2c4801337521', file)
.then(() => console.log('Successfully uploaded and set background'));
startAdvancedUserSearch
Syntax
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.
READ_USER
Parameters:
-
searchTerm
Objectobject literal containing the search parameters.
-
query
StringThe query string that is searched for.
-
[searchContext]
String optionalThe SearchContext which is searched for. e.g USER or MEETING_POINT. Defaults to USER.
-
[searchExactAssignedPhoneNumber]
Boolean optionalIf true, only users with the exact number assigned as ATC (telephony) number are returned. Defaults to false.
-
Returns:
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
Summary
Start an asynchronous basic search returning a search ID. Search results are received with search result events.
Raises basicSearchResults
and searchStatus
events.
READ_USER
, READ_CONVERSATIONS
, or SEARCH_CONVERSATIONS
Parameters:
-
searchTerm
String | ArrayArray of searchTerm objects, or a string for a simple scope search search.
-
searchTerm
StringThe string that is searched for.
-
scope
StringThe scope to search in.
-
[startTime]
Number optionalstart date used for DATE scope. In ms since midnight on January 1, 1970 in UTC
-
[endTime]
Number optionalend date used for DATE scope. In ms since midnight on January 1, 1970 in UTC
-
[rootConnector]
FilterConnector optionalfilter constraints used for FILTER scopes. See getConversationsByFilter for example.
-
Returns:
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
Summary
Start a conference call.
CALLS
Parameters:
Example:
client.startConference('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a', {audio: true, video: false})
.then(call => console.log('New call: ', call));
startRecording
Syntax
Summary
Start recording the active call.
CALL_RECORDING
Parameters:
-
callId
Stringthe ID of the call to start recording for. Only local active calls can be recorded.
-
[mediaTypes]
Object optionala 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 optionalVideo layout to be used for recording with optional pinning of user.
Returns:
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
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.
READ_USER
or SEARCH_CONVERSATIONS
Parameters:
Returns:
Example:
client.startUserSearch('Ro')
.then(searchId => console.log('Search started with ID: ' + searchId));
stopRecording
Syntax
Summary
Stop recording the active call.
CALL_RECORDING
Parameters:
Returns:
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
Summary
Submits a form posted in a message by the SDK
WRITE_CONVERSATION
Returns:
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
Summary
Subscribe to presence notifications of users.
READ_USER
Parameters:
-
userIds
String[]Array of user IDs
Returns:
A promise without data
Example:
client.subscribePresence(['874c528c-1410-4362-b519-6e7d26a2edb2','451e05a7-4649-4887-bfd2-21e70ec47e57'])
.then(() => console.log('Successfully subscribed'));
subscribeTenantPresence
Syntax
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).
READ_USER
and only by tenant admins
Returns:
A promise without data
Example:
client.subscribeTenantPresence()
.then(() => console.log('Successfully subscribed'));
subscribeTypingIndicator
Syntax
Summary
Subscribe to typing indicaticator of a conversation. Raises 'typing' event
WRITE_CONVERSATIONS
or READ_CONVERSATION
Parameters:
-
convId
StringConversation ID
Returns:
A promise without data
Example:
client.subscribeTypingIndicator('2b5a62d4-575a-41bb-afef-87c34a52d70e')
.then(() => console.log('Successfully subscribed'));
supportedFeatures
Syntax
Summary
List supported features for current browser. Only list features are currently text
and rtc
.
Returns:
Object specifying what features are supported.
suspendIncomingWebhook
Syntax
Summary
Suspend a webhook.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
webhookId
StringId of the webhook to be suspended.
Returns:
A promise without data
Example:
client.suspendIncomingWebhook('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
.then(() => console.log('Webhook suspended.'))
.catch(console.error);
switchRecordingLayout
Syntax
Summary
Switch the recording layout of the active call.
CALL_RECORDING
Parameters:
-
callId
StringcallId of the active call
-
videoLayout
VideoLayoutVideo layout to be used for recording with optional pinning of user.
Returns:
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
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.
CALLS
Parameters:
-
callId
StringcallId of the call.
Returns:
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();
}
}
});
toggleVideo
Syntax
Summary
Toggle sending video on an existing call.
CALLS
Parameters:
-
callId
StringcallId of the call to toggle video.
Returns:
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
Summary
Toggle the overlay of the whiteboard.
CALLS
Parameters:
-
callId
StringCall ID of the call.
Returns:
A promise without data.
Example:
client.toggleWhiteboardOverlay('8f365bf3-97ea-4d54-acc7-2c4801337521')
.then(() => console.log('Successfully toggled the overlay'));
typing
Syntax
Summary
Causes a typing event from the user in a given conversation.
WRITE_CONVERSATION
or READ_CONVERSATIONS
Parameters:
Returns:
A promise without data
Example:
client.typing('2b5a62d4-575a-41bb-afef-87c34a52d70e', true)
.then(() => console.log('Successfully sent'));
unarchiveConversation
Syntax
Summary
Unarchive a conversation. Succeeds if conversation is already unarchived.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
convId
StringConversation ID
Returns:
A promise without data
Example:
client.unarchiveConversation('d353db50-b835-483e-9fce-2b157b2253d3')
.then(() => console.log('Conversation unarchived'));
unassignLabels
Syntax
Summary
Unassigns specified labels from the given conversation.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
Returns:
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
Summary
Undo recent changes to the whiteboard.
CALLS
Parameters:
Returns:
A promise without data.
Example:
client.undoWhiteboard('8f365bf3-97ea-4d54-acc7-2c4801337521')
.then(() => console.log('Successfully undone steps'));
unfavoriteConversation
Syntax
Summary
Remove a conversation from the favorite list. Succeeds if conversation is already unfavorited.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
convId
StringConversation ID
Returns:
A promise without data
Example:
client.unfavoriteConversation('d353db50-b835-483e-9fce-2b157b2253d3')
.then(() => console.log('Conversation removed from favorites'));
unflagItem
Syntax
Summary
Clear the flag of an item.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Returns:
A promise without data
Example:
client.unflagItem('8fc29770-84ab-4ace-9e85-3269de707499', '874c528c-1410-4362-b519-6e7d26a2edb2')
.then(() => console.log('Successfully unflagged'));
unlikeItem
Syntax
Summary
Unlike an item.
WRITE_CONVERSATIONS
or UPDATE_CONVERSATION_CONTENT
Parameters:
-
itemId
StringItem ID of item to be unliked
Returns:
A promise without data
Example:
client.unlikeItem('874c528c-1410-4362-b519-6e7d26a2edb2')
.then(() => console.log('Successfully unliked item'));
unmoderateConversation
Syntax
Summary
Unmoderate a conversation.
WRITE_CONVERSATION
or MODERATE_CONVERSATIONS
Parameters:
-
convId
StringConversation ID.
Returns:
A promise without data.
Example:
client.unmoderateConversation('338d2002-ae68-495c-aa5c-1dff3fbc845a')
.then(() => console.log('Successfully unmoderated conversation'));
unmute
Syntax
Summary
Unmute an existing call.
CALLS
Parameters:
-
callId
StringcallId of the call to unmute.
Returns:
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
Summary
Unsubscribe to presence notifications of users.
READ_USER
Parameters:
-
userIds
String[]Array of user IDs
Returns:
A promise without data
Example:
client.unsubscribePresence(['874c528c-1410-4362-b519-6e7d26a2edb2','451e05a7-4649-4887-bfd2-21e70ec47e57'])
.then(() => console.log('Successfully unsubscribed'));
unsubscribeTenantPresence
Syntax
Summary
Unsubscribe to presence notifications of all users in the tenant. API only allowed for Client Credentials apps (bots). API requires tenant admin permissions.
READ_USER
and only by tenant admins
Returns:
A promise without data
Example:
client.unsubscribeTenantPresence()
.then(() => console.log('Successfully unsubscribed'));
unsubscribeTypingIndicator
Syntax
Summary
Unsubscribe to typing indicaticator of a conversation.
WRITE_CONVERSATIONS
or READ_CONVERSATION
Parameters:
-
convId
StringConversation ID
Returns:
A promise without data
Example:
client.unsubscribeTypingIndicator('2b5a62d4-575a-41bb-afef-87c34a52d70e')
.then(() => console.log('Successfully unsubscribed'));
unsuspendIncomingWebhook
Syntax
Summary
Unsuspend a webhook.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
-
webhookId
StringId of the webhook to be unsuspended.
Returns:
A promise without data
Example:
client.unsuspendIncomingWebhookById('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
.then(() => console.log('Webhook unsuspended.'))
.catch(console.error);
updateConversation
Syntax
Summary
Update a conversation or community.
WRITE_CONVERSATIONS
or MANAGE_CONVERSATIONS
Parameters:
Returns:
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
Summary
Update an existing webhook.
WRITE_CONVERSATIONS
or ORGANIZE_CONVERSATIONS
Parameters:
Returns:
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
Summary
Update an existing text message. See addTextItem for RICH text formatting support.
WRITE_CONVERSATIONS
or UPDATE_CONVERSATION_CONTENT
Parameters:
-
content
ObjectContent for text message to be updated.
-
itemId
StringConversation Item ID of item to update.
-
[contentType]
TextItemContentType optionalDefault 'RICH'. Whether the content is rich text (HTML) or plain text.
-
[subject]
String optionalSubject/Title of message. Only supported for parent post (i.e. parentId omitted)
-
[content]
String optionalActual text content.
-
[attachments]
File[] optionalArray of HTML File objects objects.
-
[form]
FormMetadata optionalForm object.
-
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
Summary
Update the logged on user's own user object.
WRITE_USER_PROFILE
Parameters:
-
user
ObjectObject literal containing the user attributes to update
-
userId
StringUserId
-
[firstName]
String optionalFirst name
-
[lastName]
String optionalLast name
-
[phoneNumber]
PhoneNumber[] optionalPhone numbers
-
[emailAddresses]
EmailAddress[] optionalEmail addresses
-
[userLocale]
UserLocale optionalUser Locale
-
[jobTitle]
String optionalJob title
-
[company]
String optionalCompany
-
Returns:
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
WRITE_USER_PROFILE
Parameters:
-
file
FileCustom 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 optionalIf 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
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.
Events
accessTokenRenewed
Syntax
accessTokenRenewed
Summary
Fired when OAuth access token has been renewed.
basicSearchResults
Syntax
basicSearchResults
Summary
Asynchronous search results for startUserSearch or startBasicSearch.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
data
ObjectObject literal containing search ID and its results
-
searchId
StringSearch ID to correlate to the request -
searchResults
ConversationSearchResult[]Array of conversation results -
users
String[]Array of user IDs that match the query
-
-
callEnded
Syntax
callEnded
Summary
Fired when a call is terminated.
callIncoming
Syntax
callIncoming
Summary
Fired when an incoming call is received. I.e. client is alerting
callNetworkQualityChanged (Unified plan enabled)
Syntax
callNetworkQualityChanged (Unified plan enabled)
Summary
Fired when call network quality changes.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
callId
StringID of the call
-
type
StringEvent name
-
data
ObjectCall quality object
-
userId
ObjectUser ID of local user -
audio
ObjectAudio quality object -
audio.qualityLevel
ObjectLow=1, Medium=2, High=3 -
audio.currentPlReceive
ObjectPacket Loss on receiving stream -
audio.currentPlSend
ObjectPacket Loss on sending stream -
audio.firstTimeLowQuality
Objecttrue if this is the first time with low quality on this call
-
-
-
event
ObjectObject literal containing the event properties
callRtpThresholdCleared
Syntax
callRtpThresholdCleared
Summary
Fired when call quality recovered after having reached the threshold.
callRtpThresholdReached
Syntax
callRtpThresholdReached
Summary
Fired when call quality falls below a predefined threshold.
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
ObjectObject literal containing the event properties
-
type
StringEvent name
-
call
ObjectCall object
-
[participant]
Object optionalParticipant object for participant related reasons
-
[participants]
Object optionalParticipants object for participant related reasons
-
[recordingInfo]
Object optionaldata for
callRecording
reasons -
[activeSpeakers]
Object optionaldata for
activeSpeakerChanged
reason -
reason
StringReason 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.
conversationArchived
Syntax
conversationArchived
Summary
Fired when a conversation has been archived for the logged on user
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
ObjectObject literal containing the event properties
-
type
StringEvent name
-
conversation
ConversationConversation being created
-
conversationFavorited
Syntax
conversationFavorited
Summary
Fired when a conversation has been favorited for the logged on user
conversationReadItems
Syntax
conversationReadItems
Summary
Fired when user read items on anohter device
conversationUnarchived
Syntax
conversationUnarchived
Summary
Fired when a conversation has been unarchived for the logged on user
conversationUnfavorited
Syntax
conversationUnfavorited
Summary
Fired when a conversation has been unfavorited for the logged on user
conversationUpdated
Syntax
conversationUpdated
Summary
Fired when an existing conversation is updated, or user has been added to a new conversation.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
conversation
ConversationConversation being updated
-
conversationUserDataChanged
Syntax
conversationUserDataChanged
Summary
Fired when conversation user data changes. E.g. label added/changed/removed
formSubmission
Syntax
formSubmission
Summary
Fired when a user submits a form created by logged on user/bot.
itemAdded
Syntax
itemAdded
Summary
Fired when a new conversation item is received. Note that the sender of an item will also receive this event.
itemFlagged
Syntax
itemFlagged
Summary
Fired when a conversation item is flagged.
itemUnflagged
Syntax
itemUnflagged
Summary
Fired when a conversation item is unflagged.
itemUpdated
Syntax
itemUpdated
Summary
Fired when an existing conversation item is updated.
labelEdited
Syntax
labelEdited
Summary
Fired when an existing label is edited
labelsAdded
Syntax
labelsAdded
Summary
Fired when new labels are added
labelsRemoved
Syntax
labelsRemoved
Summary
Fired when labels are removed
loggedOnUserUpdated
Syntax
loggedOnUserUpdated
Summary
Fired when any attribute on the loggedOnUser changed
mention
Syntax
mention
Summary
Mention notification for logged on user.
Event Payload:
-
event
ObjectObject literal containing the event properties
passwordChanged
Syntax
passwordChanged
Summary
Fired when password has been changed.
reconnectFailed
Syntax
reconnectFailed
Summary
Fired when automatic reconnecting to the server fails.
renewAccessTokenFailed
Syntax
renewAccessTokenFailed
Summary
Fired when renewal of OAuth access token has failed.
renewSessionTokenFailed
Syntax
renewSessionTokenFailed
Summary
Fired when renewal of session token has failed.
searchStatus
Syntax
searchStatus
Summary
Status of a pending search. E.g. Indication a search is FINISHED.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
data
ObjectObject literal
-
status
SearchStatusCodeSearch status -
searchId
StringSearch ID
-
-
sessionClosed
Syntax
sessionClosed
Summary
Fired when session has been forcefully closed by server.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
reason
SessionClosedReasonReason
-
sessionExpiring
Syntax
sessionExpiring
Summary
Fired when session is about to expire.
sessionTokenRenewed
Syntax
sessionTokenRenewed
Summary
Fired when session token has been renewed.
systemMaintenance
Syntax
systemMaintenance
Summary
Fired to inform of an upcoming maintenance event.
typing
Syntax
typing
Summary
Fired when a participant types a message in a conversation the user has subscribed to.
userPresenceChanged
Syntax
userPresenceChanged
Summary
Fired when the presence of a subscribed user changes.
userSettingsChanged
Syntax
userSettingsChanged
Summary
Fired when one or more user settings for the logged on user change.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
settings
UserSettingsUserSettings object
-
userUpdated
Syntax
userUpdated
Summary
Fired when the local user is updated. E.g. I change the jobTitle on my mobile device.
whiteboardBackground
Syntax
whiteboardBackground
Summary
Whiteboard background set or cleared.
Event Payload:
-
event
ObjectObject literal containing the event properties
whiteboardCleared
Syntax
whiteboardCleared
Summary
Whiteboard cleared.
whiteboardConversionFailed
Syntax
whiteboardConversionFailed
Summary
Whiteboard conversion failed event.
whiteboardElement
Syntax
whiteboardElement
Summary
Whiteboard element added, removed or updated.
Event Payload:
-
event
ObjectObject literal containing the event properties
whiteboardEnabled
Syntax
whiteboardEnabled
Summary
Whiteboard enabled/disabled on a call.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
enabled
Booleantrue
if enabled,false
if disabled -
[whiteboard]
Whiteboard optionalThe whiteboard object (only when whiteboard becomes enabled)
-
whiteboardOverlayToggled
Syntax
whiteboardOverlayToggled
Summary
Whiteboard overlay toggled.
whiteboardSync
Syntax
whiteboardSync
Summary
Whiteboard sync event.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
[whiteboard]
Whiteboard optionalThe whiteboard object
-
[possibleUndoOperations]
Number optionalThe number of supported undo operations for the whiteboard.
-