API Docs for version 1.3.1803

GuestClient

Module: Circuit

Summary

An application creates a GuestClient instance based on a given guest URL. After a successful connection, the other APIs on the client instance can be called. Event listeners are also exposed on the GuestClient instance.

Constructor

GuestClient

Syntax

GuestClient

(
  • config
)

Summary

Parameters:

  • config Object

    Object literal containing configuration parameters

    • client_id String

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

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

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

Methods

addEventListener

Syntax

addEventListener

(
  • type
)
Function

Summary

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

Parameters:

  • type String

    Event type such as itemAdded

Returns:

Function:

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

Example:

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

addWhiteboardElement

Syntax

addWhiteboardElement

(
  • xmlElement
)
Promise

Summary

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

Parameters:

  • xmlElement String

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

Returns:

Promise:

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

Example:

client.addWhiteboardElement(

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

cancelMonitor

Syntax

cancelMonitor

()

Summary

Cancels an ongoing monitoring session

clearWhiteboard

Syntax

clearWhiteboard

(
  • [userId]
  • [preserveBackground]
)
Promise

Summary

Clear a whiteboard.

Parameters:

  • [userId] String optional

    If set only elements of the given user are removed.

  • [preserveBackground] Boolean optional

    If true the background will be preserved

Returns:

Promise:

A promise that is resolved when the action has completed.

Example:

client.clearWhiteboard()
  .then(() => console.log('Successfully cleared whiteboard'));

clearWhiteboardBackground

Syntax

clearWhiteboardBackground

() Promise

Summary

Clear the background of the whiteboard.

Returns:

Promise:

A promise without data.

Example:

client.clearWhiteboardBackground()
  .then(() => console.log('Successfully cleared the background'));

getActiveCall

Syntax

getActiveCall

() Call

Summary

Get local active call.

Returns:

Call:

A promise returning the local active call.

getAudioVideoStats

Syntax

getAudioVideoStats

() Promise

Summary

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

Returns:

Promise:

A Promise containing RTCStatsReport object when successful

Example:

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

getLastRtpStats

Syntax

getLastRtpStats

() RTCStatsReport

Summary

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

Returns:

RTCStatsReport:

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

Example:

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

getLocalAudioVideoStream

Syntax

getLocalAudioVideoStream

() Promise

Summary

Get the local video stream (audio/video)

Returns:

Promise:

A promise containing the MediaStream

Example:

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

getLocalScreenshareStream

Syntax

getLocalScreenshareStream

() Promise

Summary

Get the local video stream for the screenshare.

Returns:

Promise:

A promise containing the MediaStream

Example:

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

getRemoteStreams

Syntax

getRemoteStreams

() MediaStream[]

Summary

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

Returns:

MediaStream[]:

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

Example:

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

getWhiteboard

Syntax

getWhiteboard

() Promise | Whiteboard

Summary

Get the complete whiteboard drawing.

Returns:

Promise | Whiteboard:

A promise containing the whiteboard drawing.

Example:

client.getWhiteboard()
  .then(board => console.log('Successfully retrieved the whiteboard'));

joinConference

Syntax

joinConference

(
  • guestData
  • mediaType
)
Promise

Summary

Join a conference as guest from the current device.

Parameters:

  • guestData Object

    The guest data used to join the conference.

    • token String

      The conference's guest token.

    • firstName String

      The guest's first name.

    • lastName String

      The guest's last name.

  • mediaType MediaType

    Media type for the call.

Returns:

Promise:

A promise that is resolved when the call is joined.

Example:

client.joinConference('someToken', {firstName: 'John', lastName: 'Snow'}, {audio: true, video: false})
  .then(() => console.log('Successfully joined the call'));

leaveConference

Syntax

leaveConference

() Promise

Summary

Leave a conference call.

Returns:

Promise:

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

Example:

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

logout

Syntax

logout

() Promise

Summary

Log this client instance out.

Returns:

Promise:

A promise that is resolved after guest client is logged out.

Example:

client.logout();

monitorSession

Syntax

monitorSession

(
  • token
  • [interval]
  • [duration]
)
Promise

Summary

Monitors the guest conference with the given token until a session is started.

Parameters:

  • token String

    The guest token to be validated

  • [interval] Number optional

    The interval (in seconds) to poll the session status. Default is 5 seconds. Min. value is 5 seconds.

  • [duration] Number optional

    The max. amount of time (in seconds) to wait for the session to start. Default is 1 minute. Max. value is 10 minutes.

Returns:

Promise:

A promise that is resolved when the session has started.

Example:

client.monitorSession('someToken')
.then(() => console.log('Session has started'));

mute

Syntax

mute

() Promise

Summary

Mute an existing call.

Returns:

Promise:

A promise that is resolved when the mute is complete.

Example:

client.mute()
  .then(() => console.log('Successfully muted call'));

muteParticipant

Syntax

muteParticipant

(
  • userId
)
Promise

Summary

Mute a remote participant.

Parameters:

  • userId String

    User ID of the participant to mute.

Returns:

Promise:

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

Example:

client.muteParticipant('874c528c-1410-4362-b519-6e7d26a2edb2')
  .then(() => console.log('Successfully muted participant'));

removeWhiteboardElement

Syntax

removeWhiteboardElement

(
  • xmlId
)
Promise

Summary

Remove a whiteboard element.

Parameters:

  • xmlId String

    SDK generated ID of the SVG elements.

Returns:

Promise:

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

Example:

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

setAudioVideoStream

Syntax

setAudioVideoStream

(
  • stream
  • [mediaType]
)
Promise

Summary

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

Parameters:

  • stream MediaStream

    Audio/Video MediaStream to send.

  • [mediaType] MediaType optional

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

Returns:

Promise:

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

Example:

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

setMediaDevices

Syntax

setMediaDevices

(
  • devices
)
Promise

Summary

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

Parameters:

  • devices Object

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

    • [playback] String | String[] optional

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

    • [recording] String | String[] optional

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

    • [video] String | String[] optional

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

    • [ringing] String | String[] optional

      Ringing media device ID, or array of IDs.

Returns:

Promise:

A promise returning no content.

Example:

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

setScreenshareStream

Syntax

setScreenshareStream

(
  • stream
)
Promise

Summary

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

Parameters:

Returns:

Promise:

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

Example:

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

setWhiteboardBackground

Syntax

setWhiteboardBackground

(
  • file
)
Promise

Summary

Set the background of the whiteboard.

Parameters:

  • file File

    File object for background image.

Returns:

Promise:

A promise without data.

Example:

client.setWhiteboardBackground(file)
  .then(() => console.log('Successfully uploaded and set background'));

toggleRemoteAudio

Syntax

toggleRemoteAudio

() Promise

Summary

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

Returns:

Promise:

A promise that is resolved when the toggle is complete.

Example:

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

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

});

toggleScreenShare

Syntax

toggleScreenShare

() Promise

Summary

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

Returns:

Promise:

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

Example:

client.toggleScreenShare()
  .then(() => console.log('Successfully toggled'));

toggleVideo

Syntax

toggleVideo

() Promise

Summary

Toggle sending video on an existing call.

Returns:

Promise:

A promise that is resolved when the toggle is complete.

Example:

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

toggleWhiteboardOverlay

Syntax

toggleWhiteboardOverlay

() Promise

Summary

Toggle the overlay of the whiteboard.

Returns:

Promise:

A promise without data.

Example:

client.toggleWhiteboardOverlay()
  .then(() => console.log('Successfully toggled the overlay'));

undoWhiteboard

Syntax

undoWhiteboard

(
  • [steps]
  • [userId]
)
Promise

Summary

Undo recent changes to the whiteboard.

Parameters:

  • [steps] Number optional

    Number of steps to undo.

  • [userId] String optional

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

Returns:

Promise:

A promise without data.

Example:

client.undoWhiteboard()
  .then(() => console.log('Successfully undone steps'));

unmute

Syntax

unmute

() Promise

Summary

Unmute an existing call.

Returns:

Promise:

A promise that is resolved when the unmute is complete.

Example:

client.unmute()
  .then(() => console.log('Successfully unmuted call'));

validateToken

Syntax

validateToken

(
  • token
)
Promise

Summary

Validate the given guest token and verify if there is an ongoing session that can be joined.

Parameters:

  • token String

    The guest token to be validated

Returns:

Promise:

A promise that is resolved when the token is validated.

Example:

client.validateToken('someToken')
.then(data => console.log(data));

Properties

connectionState

Syntax

connectionState

ConnectionState

Summary

Connection State

domain

Syntax

domain

String

Summary

Domain connected to.

Default: circuitsandbox.net

supportedEvents

Syntax

supportedEvents

Array

Summary

List of supported events for GuestClient

Events

callEnded

Syntax

callEnded

Summary

Fired when a call is terminated.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • call Object

      Call object

    • replaced Boolean

      True if call has been replaced with a new call

callNetworkQualityChanged (Unified plan enabled)

Syntax

callNetworkQualityChanged (Unified plan enabled)

Summary

Fired when call network quality changes.

Event Payload:

  • event Object

    Object literal containing the event properties

    • callId String

      ID of the call

    • type String

      Event name

    • data Object

      Call quality object

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

    Object literal containing the event properties

    • String

      ID of the call

    • String

      Event name

    • Object

      Network quality level defined in Circuit.Enums.RtpQualityLevel

callRtpThresholdCleared

Syntax

callRtpThresholdCleared

Summary

Fired when call quality recovered after having reached the threshold.

Event Payload:

  • event Object

    Object literal containing the event properties

callRtpThresholdReached

Syntax

callRtpThresholdReached

Summary

Fired when call quality falls below a predefined threshold.

Event Payload:

  • event Object

    Object literal containing the event properties

callStatus

Syntax

callStatus

Summary

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

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • call Object

      Call object

    • [participant] Object optional

      Participant object for participant related reasons

    • [participants] Object optional

      Participants object for participant related reasons

    • [recordingInfo] Object optional

      data for callRecording reasons

    • [activeSpeakers] Object optional

      data for activeSpeakerChanged reason

    • reason String

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

connectionStateChange

Syntax

connectionStateChange

Summary

Fired when the connection state changes.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • state String

      Connection State (Disconnected, Connecting, Reconnecting, Connected)

sessionClosed

Syntax

sessionClosed

Summary

Fired when session has been forcefully closed by server.

Event Payload:

whiteboardBackground

Syntax

whiteboardBackground

Summary

Whiteboard background set or cleared.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • action String

      'set' or 'cleared'

    • [element] WhiteboardElement optional

      Applicable for 'set'. The element for the background

    • [possibleUndoOperations] Number optional

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

whiteboardCleared

Syntax

whiteboardCleared

Summary

Whiteboard cleared.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • [userId] String optional

      userId if only elements for a specific user have been cleared

    • [possibleUndoOperations] Number optional

      The number of supported undo operations for the whiteboard.

whiteboardConversionFailed

Syntax

whiteboardConversionFailed

Summary

Whiteboard conversion failed event.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • callId String

      Call ID of whiteboard session that failed

    • errorText String

      Error text of failed whiteboard conversion

    • lastElements String

      The last svg elements of the whiteboard

whiteboardElement

Syntax

whiteboardElement

Summary

Whiteboard element added, removed or updated.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • action String

      'added', 'removed' or 'updated'

    • [element] WhiteboardElement optional

      element added or updated

    • [elementId] WhiteboardElementId optional

      element removed

    • [possibleUndoOperations] Number optional

      The number of supported undo operations for the whiteboard.

whiteboardEnabled

Syntax

whiteboardEnabled

Summary

Whiteboard enabled/disabled on a call.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • enabled Boolean

      true if enabled, false if disabled

    • [whiteboard] Whiteboard optional

      The whiteboard object (only when whiteboard becomes enabled)

whiteboardOverlayToggled

Syntax

whiteboardOverlayToggled

Summary

Whiteboard overlay toggled.

Event Payload:

  • event Object

    Object literal containing the event properties

whiteboardSync

Syntax

whiteboardSync

Summary

Whiteboard sync event.

Event Payload:

  • event Object

    Object literal containing the event properties

    • type String

      Event name

    • [whiteboard] Whiteboard optional

      The whiteboard object

    • [possibleUndoOperations] Number optional

      The number of supported undo operations for the whiteboard.