Configuration options for the Logs feature.

The SDK will log information about the operations it is performing. The amount of information will depend on how the Logs feature is configured.

The format of logs can also be customized by providing a LogHandler. This function will receive a LogEntry which it can handle as it sees fit. By default, the SDK will log information to the console. For more information, see the Logs feature description.

Configuration options for the Connectivity feature. The SDK can only use keepalive as the connectivity check.

Keep Alive: The client sends "keepalive" messages (to the server) on the websocket at regular intervals. This lets the server know that the client is still connected, and that it should "keep the connection alive".

For more information on keepalive see here: https://en.wikipedia.org/wiki/Keepalive

Configuration options for the notification feature.

Configurable options for the Request plugin.

The SDK uses the Request plugin to make REST requests to the Gateway.

Configuration options for the Authentication feature.

Configuration options for the Subscription feature.

Configuration options for the call feature.

The Basic Error object. Provides information about an error that occurred in the SDK.

Type: Object

Returns the current version of the API.

Destroys the SDK, and removes its state, rendering the SDK unusable. Useful when a user logs out and their call data needs to be destroyed. The SDK must be recreated to be usable again. The destroy command is async, and will happen on the next tick so as not to interfere with any ongoing events.

// Instantiate the SDK.
import { create } from '@rbbn/webrtc-js-sdk'
const config = {
    authentication: { ... },
    logs: { ... },
    ...
}
let client = create(config);
client.on( ... )
// Use the SDK
...
// Destroy the SDK, then recreate on the next step
client.destroy()
client = create(config)
client.on( ... )

Gets the current configuration Object. This is the object that is initially set as part of SDK creation using 'create' function.

Update the configuration values for the SDK to use.

This API will only modify the configurations provided, leaving other configurations as they were originally set, by performing a merge of the new values into the previous values.

Please note that the object provided to the updateConfig API may be different than the object retrieved from the getConfig API. This may happen when a format change has happened and the SDK modifies the provided format to alleviate backwards-compatibility issues. We recommend ensuring the configurations you provide are as described by the config section.

// Instantiate the SDK with certain configs.
const client = create({
  authentication: { ... },
  logs: { ... },
  ...
})

// Modify a subsection of the configs at a later time.
// This will only update the specified configurations.
client.updateConfig({
    logs: {
      loglevel: 'DEBUG'
    }
})

Add an event listener for the specified event type. The event is emitted by the SDK instance.

// Listen for events of a specific type emitted by the SDK.
client.on('dummy:event', function (params) {
   // Handle the event.
})

Removes an event listener for the specified event type. The event is emitted by the SDK instance.

Adds a global event listener to SDK instance.

Removes a global event listener from SDK instance.

Retrieve information about the browser being used.

Browser information being defined indicates that the browser supports basic webRTC scenarios.

const details = client.getBrowserDetails()

log(`Browser in use: ${details.browser}, version ${details.version}.`)

Retrieves information about the current user.

Sets the user credentials necessary to make requests to the platform.

The SDK will emit an auth:change event when the credentials are set. If there was an issue with the credentials, an auth:error event will be emitted instead.

The currently set user information can be retrieved using the getUserInfo API.

If credentials have previously been set, they cannot be set again if there is an active subscription. An auth:error will be emitted in this scenario.

client.setCredentials({
  username: 'alfred@example.com',
  password: '********'
  authname: '********'
});

Sets the user credentials necessary to make requests to the platform, using HMAC token authentication.

An HMAC token is used to verify a user via the user's authorization within an of organization. HMAC tokens are generated by using the HmacSHA1 algorithm and a key on a data object containing an authenticationTokenRequest object with the following properties:

• subscriberId - The user's subscriber ID in the organization.
• organizationId - The ID of the organization the user is a part of.

The SDK will emit an auth:change event when the credentials are set. If there was an issue with the credentials, an auth:error event will be emitted instead.

The currently set user information can be retrieved using the getUserInfo API.

If credentials have previously been set, they cannot be set again if there is an active subscription. An auth:error will be emitted in this scenario.

const hmacToken = HmacSHA1Algorithm({
  authenticationTokenRequest: {
    subscriberId: 'alfred',
    organizationId: 'example.com'
  }
}, key)

client.setCredentials({
  username: 'alfred@example.com',
  hmacToken
});

Sets the user credentials necessary to make requests to the platform, using bearer token authentication.

The bearerAccessToken provided establishes what can be accessed by the SDK. The bearerAccessToken can be set again after subscription as long as the subscribed username is passed with the updated bearerAccessToken.

The SDK will emit an auth:change event when the credentials are set. If there was an issue with the credentials, an auth:error event will be emitted instead.

The currently set user information can be retrieved using the getUserInfo API.

If credentials have previously been set, they cannot be set again if there is an active subscription. An auth:error will be emitted in this scenario.

client.setCredentials({
  username: 'alfred@example.com',
  bearerAccessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
});

An error occurred with server authorization.

This event will be emitted anytime a REST request to the server is rejected due to an authorization issue. This may occur for invalid credentials or expired tokens, depending on which form of authentication the application has chosen to use.

The authentication credentials have changed.

This event is triggered after calling the setCredentials API.

The current user information can be retrieved using the getUserInfo API.

There was an error with authentication credentials.

This event is triggered after calling the setCredentials API.

The SIP URI ie: sip:joe@domain.com

Type: string

The TEL URI ie: tel:+18885559876

Type: string

Information about a Call.

Can be retrieved using the call.getAll or call.getById APIs.

Type: Object

The MediaConstraint type defines the format for configuring media options. Either the exact or ideal property should be provided. If both are present, the exact value will be used.

When the exact value is provided, it will be the only value considered for the option. If it cannot be used, the constraint will be considered an error.

When the ideal value is provided, it will be considered as the optimal value for the option. If it cannot be used, the closest acceptable value will be used instead.

A string value can be provided directly instead of using the MediaConstraint format. Using a string directly is not recommended, since behaviour may differ depending on browser and media property. For most properties, a direct string value will be handled as ideal behaviour, but some properties may follow the exact behaviour (eg. deviceId).

Type: Object

// Specify video resolution when making a call.
client.call.make(destination, {
   audio: true,
   video: true,
   videoOptions: {
     // Set height and width constraints to ideally be 1280x720.
     height: { ideal: 720 },
     width: { ideal: 1280 }
   }
})

The AudioOptions type defines the format for specifying audio-related constraints.

Type: Object

// Specify what specific microphone device to use by providing its device ID.
client.call.make(destination, {
   audio: true,
   audioOptions: { deviceId: 'some unique device ID' }
})

The VideoOptions type defines the format for specifying video-related constraints.

Type: Object

client.call.make(destination, {
   video: true,
   videoOptions: {
     deviceId: 'some unique device ID',
     // Set height and width constraints to exactly be 1280x720.
     height: { exact: 720 },
     width: { exact: 1280 },
     frameRate: { exact: 24 }
   }
})

The ScreenOptions type defines the format for specifying screen capturing-related constraints.

Type: Object

client.call.make(destination, {
   screen: true,
   screenOptions: {
     // Set height and width constraints to exactly be 1280x720.
     height: { exact: 720 },
     width: { exact: 1280 },
     frameRate: { exact: 24 }
   }
})

The MediaOffered type defines what media capabilities are offered by the person making a call. This is an optional property and therefore may be null if it is not known or if it's associated with caller's side of the call.

Type: Object

The BandwidthControls type defines the format for configuring media and/or track bandwidth options. BandwidthControls only affect received remote tracks of the specified type.

Type: Object

// Specify received remote video bandwidth limits when making a call.
client.call.make(destination, mediaConstraints,
 {
   bandwidth: {
     video: 5
   }
 }
)

The DSCPControls type defines the format for configuring network priorities (DSCP marking) for the media traffic.

If DSCPControls are not configured for a call the network priority of the traffic for all media kinds will be the default (i.e., "low").

Type: Object

Configuration options for an RTCPeerConnection. It represents an RTCPeerConfiguration dictionary, whose parameters are documented here.

Type: Object

Type: Object

This object is provided to the IceCollectionCheckFunction, and contains the necessary information about the call (i.e., call ID, current call operation), and information about the ongoing ICE collection, such as the list of all ICE candidates collected so far and the ICE gathering state.

Type: Object

The form of the ICE collection check function, the arguments that it receives, and the outputs expected.

This function is provided the necessary details of the current WebRTC session and ICE collection (IceCollectionInfo), which it can use to dictate how to proceed with a call. The function can be invoked for three different reasons: a new ICE candidate was collected, the ICE gathering state changed, or a scheduled call based on the wait time set after an initial invocation of the function.

The function must then return an appropriate result object in the format of IceCollectionCheckResult which will dictate how the call will proceed. An incorrect return object, or result type, will cause the call to end with an error.

[Default] The default IceCollectionCheckFunction uses the following algorithm to determine if the call can proceed to negotiation:

1. If the iceGatheringState is "complete" at any stage, then:
   • Proceed with the negotiation if any ICE candidates are collected.
   • Or, end the call if there are no ICE candidates collected.
2. Otherwise, if before the ideal ICE collection timeout:
   • If every media has a relay ICE candidate for every configured TURN server, proceed with negotiation.
   • Else, wait until the ideal timeout, or when invoked for another reason.
3. Otherwise, if before the max ICE collection timeout, but after the ideal ICE collection timeout:
   • If every media has atleast one relay ICE candidate, proceed with negotiation.
   • Else, wait until max timeout, or when invoked for another reason.
4. Otherwise, if we are at, or past, the max ICE collection timeout:
   • If there are any ICE candidates collected, proceed with negotiation.
   • Else, end the call with an error.

The ideal and max timeouts can be configured with the idealIceCollectionTimeout and maxIceCollectionTimeout properties of the call config.

Type: Function

function isRelayCandidate (candidate) {
// NOTE: This would need to be different for Firefox since the `.type` property doesn't exist
// and we would need to parse it ourselves in the `.candidate` property.
  return candidate.type === 'relay'
}

function myIceCollectionCheck ({ iceGatheringState, iceCandidates }, iceTimeouts) {
  if (iceGatheringState === 'complete') {
    if (iceCandidates.some(isRelayCandidate)) {
      return { type: 'StartCall' }
    } else {
      return { type: 'Error', error: new Error('Failed to start call because there is no relay candidates.') }
    }
  } else {
    return { type: 'Wait' }
  }
}

Type: Object

Type: Object

The form of an SDP handler function and the expected arguments that it receives.

Type: Function

The state representation of a Media object. Media is a collection of Track objects.

Type: Object

A Track is a stream of audio or video media from a single source. Tracks can be retrieved using the Media module's getTrackById API and manipulated with other functions of the Media module.

Type: Object

A collection of media devices and their information.

Type: Object

Contains information about a device.

Type: Object

Custom SIP headers can be used to convey additional information to a SIP endpoint.

These parameters must be configured on the server prior to making a request, otherwise the request will fail when trying to include the parameters.

These parameters can be specified with the call.make and call.answer APIs. They can also be set after a Call is established using the call.setCustomParameters API, and sent using the call.sendCustomParameters API.

Custom headers may be received anytime throughout the duration a call. A remote endpoint may send custom headers when starting a call, answering a call, or during call updates such as hold/unhold and addition/removal of media in the call. When these custom headers are received, the SDK will emit a call:customParameters event which will contain the custom parameters that were received.

A Call's custom parameters are stored on the Call's CallObject, which can be retrieved using the call.getById or call.getAll APIs. These are the parameters that will be sent to the remote endpoint of the Call. Parameters received from a Call are not stored as part of the CallObject and are only provided via the call:customParameters event.

Type: Object

// Specify custom parameters when making a call.
client.call.make(destination, mediaConstraints,
 {
   customParameters: [
     {
       name: 'X-GPS',
       value: '42.686032,23.344565'
     }
   ]
 }
)

Starts an outgoing call to a SIP_URI or a TEL_URI.

The call will be tracked by a unique ID that is returned by the API. The application will use this ID to identify and control the call after it has been initiated.

The call.getById API can be used to retrieve the current information about the call.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:start event locally when the operation completes. When the remote participant receives the call, a call:receive event will be emitted remotely for them.

The SDK requires access to the machine's media devices (eg. microphone) in order to make a call. If it does not already have permissions to use the devices, the user may be prompted by the browser to give permissions.

Detached media can be used when starting a call. Detached media is created locally outside of a call and must be managed by the application. It can be used when making a call by passing an array of detached track ids in the media object. You can start a call with a mixture of detached and requested media, however, you can only use one of each type (audio, video, screen). For example, you could include a detached track id for video, and set MediaConstraint.audio: true, but you can't set MediaConstraint.video: true if you have passed in a detached track id of kind video.

// Listen for the event emitted after making a call.
client.on('call:start', function (params) {
  const { callId, error } = params
  if (error) {
    // Call failed to initialize.
  } else {
    // Call was initialized, and the recipient user will be notified.
  }
})
// Make an audio-only call.
const newCallId = client.call.make(destination, { audio: true })

Answers an incoming call.

The specified call to answer must be in a ringing state with an incoming direction. The call will become connected as a result of the operation.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:stateChange event locally when the operation completes. This indicates that the call has connected with the remote participant. The call.getById API can be used to retrieve the latest call state after the change. Further events will be emitted to indicate that the call has received media from the remote participant. See the call:newTrack event for more information about this.

The SDK requires access to the system's media devices (eg. microphone) in order to answer a call. If it does not already have permissions to use the devices, the user may be prompted by the browser to give permissions.

Rejects an incoming call.

The specified call to reject must be in a ringing or initiated state with an incoming direction. The call will be ended as a result of the operation.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:stateChange event locally when the operation completes. The remote participant will be notified, through their own call:stateChange event, that the call was rejected.

Ignores an incoming call.

The specified call to ignore must be in a ringing state with an incoming direction. The call will be ended as a result of the operation.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:stateChange event locally when the operation completes. The remote participant will not be notified that the call was ignored.

Forwards an incoming call to another user.

The specified destination will receive the Call instead of the current user.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:stateChange event after the operation completes.

Ends an ongoing call.

The SDK will stop any/all local media associated with the call. Events will be emitted to indicate which media tracks were stopped. See the call:trackEnded event for more information.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:stateChange event locally when the operation completes. The remote participant will be notified, through their own call:stateChange event, that the call was ended.

Puts a call on hold.

The specified call to hold must not already be locally held. Any/all media received from the remote participant will stop being received, and any/all media being sent to the remote participant will stop being sent.

Some call operations cannot be performed while the call is on hold. The call can be taken off hold with the call.unhold API.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:stateChange event locally when the operation completes. The remote participant will be notified of the operation through a call:stateChange event as well.

Takes a call off hold.

The specified call to unhold must be locally held. If the call is not also remotely held, call media will be reconnected as it was before the call was held.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:stateChange event locally when the operation completes. The remote participant will be notified of the operation through a call:stateChange event as well.

Add new media tracks to an ongoing call. Will get new media tracks from the specific sources to add to the call.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:newTrack event both for the local and remote users to indicate a track has been added to the Call.

Remove tracks from an ongoing call.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:trackEnded event for both the local and remote users to indicate that a track has been removed.

Adds local video to an ongoing Call, to start sending to the remote participant.

Can only be used in a basic media scenario, where the Call does not already have video. For more advanced scenarios, the call.addMedia API can be used.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:tracksAdded event both for the local and remote users to indicate a track has been added to the Call.

Removes local video from an ongoing Call, stopping it from being sent to the remote participant.

Can only be used in a basic media scenario, where the Call has only one video track. For more advanced scenarios, the call.removeMedia API can be used.

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:tracksRemoved event for both the local and remote users to indicate that a track has been removed.

Replace a call's track with a new track of the same media type.

The operation will remove the old track from the call and add a new track to the call. This effectively allows for changing the track constraints (eg. device used) for an ongoing call.

Because it completely replaces an old track with a new one, the old track's state characteristics are not carried over in the new track's state. (e.g. if an old track's state was 'muted' and replacement of this track has occured, the new track's state will be 'unmuted', as this is its default state)

The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:trackReplaced event locally when the operation completes. The newly added track will need to be handled by the local application. The track will be replaced seamlessly for the remote application, which will not receive an event.

const callId = ...
// Get the video track used by the call.
const videoTrack = ...

// Replace the specified video track of the call with a new
//    video track.
client.call.replaceTrack(callId, videoTrack.id, {
  // The track should be replaced with a video track using
  //    a specific device. This effectively changes the input
  //    device for an ongoing call.
  video: true,
  videoOptions: {
    deviceId: cameraId
  }
})

const callId = ...
// Get the video track used by the call.
const videoTrack = ...

// Can also replace the specified video track of the call with a new
// screen sharing track because screen sharing is delivered as a video stream to remote peer.
// User will then be prompted to pick a specific screen to share and thus the device id will be selected.
client.call.replaceTrack(callId, videoTrack.id, {
  // The track should be replaced with a screen sharing track.
  // Note that 'screenOptions' property is not mandatory, as API will use default values
  // for properties like: width, height, frameRate.
  screen: true
})

Attempt to re-establish a media connection for a call.

This API will perform a "refresh" operation on the call with the intention of resolving media issues that may have been encountered. This API is only necessary after the Call's mediaConnectionState has entered the failed state, but may be used in other scenarios.

After the operation completes successfully, the Call will be re-establishing its media connection. By this time, or shortly after, the Call's mediaConnectionState should have transitioned to checking (via a call:mediaConnectionChange event) to signify the re-establishment. It will then transition to either connected or failed state, similar to during the initial Call establishment.

If this operation fails, then the Call will not attempt the re-establishment and will remain in the failed mediaConnectionState.

Behaviour during the operation may differ slightly based on the browser. Notably, Firefox will always transition to the checking mediaConnectionState no matter what the previous state was. Whereas Chrome will skip the checking state, transitioning directly to either connected or failed. This has the implication for Chrome that if the state does not change (for example, the Call is in the failed state before the media restart operation, and media re-establishment fails), then there will be no call:mediaConnectionChange event emitted. For this reason, Chrome-based applications may need a short delay after receiving the call:mediaRestart event before checking the Call's updated mediaConnectionState to ensure the application is acting on the "latest" state.

The SDK will emit a call:mediaRestart event when the operation completes.

The progress of the operation will be tracked via the call:operation event.

Plays an audio file to the remote side of the Call. This API will temporarily replace the Call's local audio track with an audio file for the duration of the audio file.

The Call must be in Connected state and have a local audio track for this operation.

This API will not affect media other than the local audio track. Other media on the Call, such as local video or remote audio, can be muted or unrendered during this operation if desired.

This operation will use the browser's Audio constructor to read in the audio file. The filePath parameter will be used directly with Audio, so can be either a relative file path to your audio file or a URL pointing to a file.

This API returns a promise that can be used to track the progress of the operation. The promise will resolve after the operation completes or reject if an error is encountered. Additionally, an extra onPlaying callback is provided on the Promise to indicate when the audio file actually begins to play. See the code example below for a sample.

The SDK will emit call:operation events locally as the operation progresses. The remote endpoint will not receive an event for this operation.

If an error is encountered during the operation and the SDK is unable to replace the original local audio track, then that track will be forcibly ended and an media:trackEnded event will be emitted for it. This will release the microphone and avoid losing access to the track while it is active, allowing the application to resolve the scenario by using the call.replaceTrack API to revert the local audio track.

// The API returns a promise which will provide feedback about the operation.
client.call.playAudioFile(callId, filePath)
   .then(() => {
     // Audio file has finished playing; call has reverted to previous audio.
   })
   .catch(err => {
     // An error has occurred during the operation.
   })

// The returned promise can optionally provide feedback midway through the
//   operation. A chainable `onPlaying` method denotes when the audio file has
//   started to play and the Call's audio has been replaced.
client.call.playAudioFile(callId, filePath)
   .onPlaying(({ duration }) => {
     // Audio file has started playing; call audio is now the file.
     // Note: Calling `onPlaying` must be done before `then` and `catch` for it
     //    to be chainable.
   })
   .then(() => { ... })
   .catch(err => { ... })

Performs a "direct" transfer on a call (also known as an unannounced or blind transfer). This allows the current user to transfer the remote participant of a call to another user, similar to a "forward" operation.

The specified call must be locally held. After the operation, this call will be ended, as indicated by a call:stateChange event.

The "destination" user will receive an incoming call, and when answered, they will be connected with the remote participant of the specified call.

The progression of the operation will be tracked via the call:operation event. The remote participant being transferred will receive it as if it were a "remote unhold" operation.

Performs a "consultative" transfer between two ongoing calls (also known as an announced or warm transfer). This allows the current user to transfer the remote participant of a call to another user, after having spoken to both users.

Both calls used for the transfer must be locally held. After the operation, these calls will be ended, as indicated by a call:stateChange event.

Both remote participants will see their call be unheld by the operation, as indicated by a call:stateChange event, and will be connected to one another afterwards.

The progression of the operation will be tracked via the call:operation event. Both local calls will receive this event, since it is an operation on both calls, and the remote calls will receive it as if it were a "remote unhold" operation.

Performs a "join" on two ongoing calls. This allows the current user to establish a call with audio with two remote users.

Both specified calls must be locally held. The new, "joined" call will be audio-only, even if either previous call had video. Video cannot be added to the "joined" call. Both remote participants will see their call taken off hold, and will receive additional audio from other participants after the operation. Both previous calls for the current user will be ended after the operation, as indicated by a call:stateChange event.

If the first call specified has custom parameters set, these parameters will be carried over to the new call.

The progress of the operation will be tracked via the call:operation event. Both remote participants will also receive this event as if it were a "remote unhold" operation.

Retrieves the information of all calls made during the current session.

let calls = client.call.getAll()
let currentCalls = calls.filter(call => {
    return call.state === client.call.states.CONNECTED
})

Retrieves the information of a single call with a specific call ID.

Sends the "ringing feedback" notification to the remote participant of a call.

When using the 'manual' ringingFeedbackMode configuration, the application is responsible for transitioning the call into the Ringing state. This API will notify both ends of the call to enter Ringing state at the same time. The application may decide not to send the "ringing feedback" notification by not using this API. The ringingFeedbackMode configuration must be set to 'manual' to use this API.

The specified call must be an incoming call in Initiated state. The call will enter Ringing state as a result of the operation.

The SDK will emit a call:stateChange event locally when the operation completes. The remote participant will be notified of the operation through a call:stateChange event as well.

Set the Custom Parameters of a Call, to be provided to the remote endpoint.

The specified parameters will be saved as part of the call's information throughout the duration of the call. All subsequent call operations will include these custom parameters. Therefore, invalid parameters, or parameters not previously configured on the server, will cause subsequent call operations to fail.

A Call's custom parameters are a property of the Call's CallObject, which can be retrieved using the call.getById or call.getAll APIs.

The custom parameters set on a call can be sent directly with the call.sendCustomParameters API.

Custom parameters can be removed from a call's information by setting them as undefined (e.g., call.setCustomParameters(callId)). Subsequent call operations will no longer send custom parameters.

Send the custom parameters on an ongoing call to the server. The server may either consume the headers or relay them to another endpoint, depending on how the server is configured.

A Call's custom parameters are a property of the Call's CallObject, which can be retrieved using the call.getById or call.getAll APIs.

Before sending custom parameters, they need to be first set on the existing Call. To set, change or remove the custom parameters on a call, use the call.setCustomParameters API.

Send DTMF tones to a call's audio.

The provided tone can either be a single DTMF tone (eg. '1') or a sequence of DTMF tones (eg. '123') which will be played one after the other.

The specified call must be either in Connected, Ringing, or Early Media state, otherwise invoking this API will have no effect.

The tones will be sent as out-of-band tones if supported by the call, otherwise they will be added in-band to the call's audio.

The progress of the operation will be tracked via the call:operation event.

Retrieve a snapshot of the low-level information of the Call through statistical report.

The data retrieved is a RTCStatsReport object, which contains many individual RTCStats. These are advanced statistics gathered by the browser providing insights into the Call at a certain point in time. Aggregating reports over a period of time would allow a low-level analysis of the Call for that period. As an example, this could be done to determine the media quality during the Call.

A Track ID can optionally be provided to get a report for a specific local Track of the Call.

This API will return a promise which, when resolved, will contain the report of the particular call. The progress of the operation will be tracked via the call:operation event.

The SDK will emit a call:statsReceived event, after the operation completes, that has the report.

// Get a snapshot of the Call's stats.
//   This may be done on a regular interval to collect data over time.
try {
   // The API will return a promise that resolves with the stats.
   const result = await client.call.getStats(callId)
   result.forEach(stats => {
       // Handle the data on its own or collate with previously gathered stats
       //    for analysis.
       ...
   })
} catch (err) {
   // Handle the error.
   const { code, message } = err
   ...
}

Retrieve the list of available and supported codecs based on the browser's capabilities for sending media.

This API will return a promise which, when resolved, it will contain the list of available and supported codecs. In addition, the SDK emits a call:availableCodecs event upon retrieving that list of codecs.

This API is a wrapper for the static method RTCRtpSender.getCapabilities().

try {
   // The API will return a promise that resolves with the codecs.
   const result = await client.call.getAvailableCodecs('audio')
   result.forEach(codec => {
       // Inspect the codec supported by browser by looking at its properties.
       ...
   })
} catch (err) {
   // Handle the error.
   const { code, message } = err
   ...
}

Retrieve the call metrics report for a call.

The object returned from this API will be in JSON format. The top level object is the report and will include a timeline of events that were recorded during a call as well as a map object containing computed metrics.

Any event in a timeline will have it's own timeline that may have recorded events. Events in a timeline are scoped to that timelines event or report.

The report and some events may have additional data included in a data property.

See event documentation here. See metrics documentation here.

Set SDP Handler Functions that will be run as part of a pipeline for all future calls. This will replace any SDP Handlers that were previously set.

SDP handlers can be used to make modifications to the SDP (e.g., removing certain codecs) before they are processed or sent to the other side.

This is an advanced feature, changing the SDP handlers mid-call may cause unexpected behaviour in future call operations for that call.

Possible states that a Call can be in.

A Call's state describes the current status of the Call. An application should use the state to understand how the Call, and any media associated with the Call, should be handled. Which state the Call is in defines how it can be interacted with, as certain operations can only be performed while in specific states, and tells an application whether the Call currently has media flowing between users. Unless stated otherwise, the Call's state pertains to both caller & callee.

The Call's state is a property of the CallObject, which can be retrieved using the call.getById or call.getAll APIs.

The SDK emits a call:stateChange event when a Call's state changes from one state to another.

Type: Object

// Use the call states to know how to handle a change in the call.
client.on('call:stateChange', function (params) {
   const call = client.call.getById(params.callId)
   // Check if the call now has media flowing.
   if (call.state === client.call.states.CONNECTED) {
     // The call is now active, and can perform midcall operations.
   }
})

Possible states that a Call's media connection can be in.

A Call's media connection state describes the current status of media within the call. An application should use this state to understand whether the Call participants are able to see/hear each other or may be experiencing connection issues. The media connection state can be used alongside the Call state to determine if media issues are occurring while the participants are expecting to be connected.

An important state to check for is the FAILED state. This state signifies that there is no media connection between the call participants and an action must be taken to resolve the problem. Using the call.restartMedia API will attempt to reconnect the media. See the call.restartMedia API description for more information.

These states are direct reflections of the possible RTCPeerConnection.iceConnectionState values.

The Call's media connection state is a property of the CallObject, which can be retrieved using the call.getById or call.getAll APIs.

The SDK emits a call:mediaConnectionChange event when a Call's media connection state changes from one state to another.

Type: Object

// Use the media connection states to check the status of the media connection of the Call.
client.on('call:mediaConnectionChange', function (params) {
  // Retrieve the state of the Call this event is for.
  const call = client.call.getById(params.callId)
  const mediaConnectionStates = client.call.mediaConnectionStates

  // Check the mediaConnectionState to determine which scenario the call is in.
  switch (call.mediaConnectionState) {
    case mediaConnectionStates.CONNECTED:
    case mediaConnectionStates.COMPLETED:
      // Media established: The Call's media is connected. The Call's participants
      //    are able to see/hear each other.
      // These states will occur after Call establishment.
      ...
      break
    case mediaConnectionStates.NEW:
    case mediaConnectionStates.CHECKING:
    case mediaConnectionStates.DISCONNECTED:
      // Media pending: The Call's media is not connected. The Call is working
      //    to connect media automatically.
      // These states will occur during Call establishment and may occur midcall if there are
      //    connection issues (eg. poor network quality) or a Call participant has changed (eg. transfer).
      ...
      break
    case mediaConnectionStates.FAILED:
     // Media has failed. The call requires a media refresh to reestablish.
     // This state will occur after the `DISCONNECTED` state is encountered.
     ...
      break
    case mediaConnectionStates.CLOSED:
      // Media ended due to the Call being ended.
      // This state will occur after Call establishment.
      ...
      break
  }
}

Events used in the SDK's call reports.

As a call progresses, the operation(s)/function(s) being performed throughout the duration of a call are recorded as events in a call report. The call report can be retrieved via the call.getReport API. An application can use these event names to find the associated event(s) in the call report for more information on the event. See Call Reports tutorial for more information on call reports and events.

Type: Object

const report = client.call.getReport('callId')
const getAvailableCodecsEvent = report.timeline.find(event => event.type === client.call.reportEvents.GET_AVAILABLE_CODECS)
log(`Took ${getAvailableCodecsEvent.end - getAvailableCodecsEvent.start}ms to get available codecs.`)

List of metrics available as part of a Call Report. Metrics are calculated only for the successful scenarios.

As a call progresses, timings are calculated for the duration of operations and other events. They are recorded in a call report that can be retrieved via the call.getReport API.

Type: Object

const report = client.call.getReport(callId)
const callDuration = report.metrics.find(metric => metric.type === client.call.metrics.CALL_DURATION)
log(`Call duration was ${callDuration.data}ms.`)

A call operation has either started, been updated, or finished.

Information about ongoing call operations are stored on the CallObject. This event indicates that an operation's information has changed.

The status of an operation indicates whether the local or remote side of the call is currently processing it, with values being 'ONGOING' or 'PENDING', respectively. All operations will begin as 'ONGOING' status with an event indicating the 'START' transition. Operations that require a response from the remote side will have an 'UPDATE' transition to the 'PENDING' status once it starts to wait for the response. Once complete, an event will indicate a 'FINISH' transition and the operation will be removed from the call state.

client.on('call:operation', (params) => {
   const { callId, operationId } = params

   // Get the operation from the call's state that this event is about.
   const call = client.call.getById(callId)
   const operation = call.currentOperations.find(op => op.id === operationId)
   log(`${operation.type} operation is now ${operation.status} for call ${callId}.`)
})

An outgoing call has been started.

Information about the Call can be retrieved using the call.getById API.

A new joined call has been started.

Information about the Call can be retrieved using the call.getById API.

A new incoming call has been received.

Information about the Call can be retrieved using the call.getById API.

NOTE: Upon receiving this notification the call is in "Initiating" state. In order to answer calls, they must be in either "Ringing" or "Initiated" states. Therefore, this event should not be used to prompt the user to respond. Instead, the call:stateChange event should be used for this purpose.

client.on('call:receive', function(params) {
    // We have received a call
    promptUser(client.call.getById(params.callId));
});

A Call's state has changed.

See call.states for information about call states.

client.on('call:stateChange', function (params) {
    const call = client.call.getById(params.callId)
    const prevState = params.previous.state
    log(`Call changed from ${prevState} to ${call.state} state.`)

    // Handle the event depending on the new call state.
    switch (call.state) {
        case client.call.states.CONNECTED:
            // Handle being on call with media.
            break
        case client.call.states.ENDED:
            // Handle call ending.
            break
        ...
    }
})

New media has been added to the call.

Media has been removed from the call.

Tracks have been added to the Call after an SDK operation. Both sides of the Call are now able to render these tracks.

Tracks are added to a Call when either the local or remote user adds new media to the Call, using the call.addMedia API for example, or when the Call is unheld with the call.unhold API.

Remote tracks are similarly added to a Call when new tracks are added by the remote user or either user unholds the call.

This event can indicate that multiple tracks have been removed by the same operation. For example, if the remote user added video to the call, this event would indicate a single, remote video track was added. If the local user unheld the call, this event would indicate that any tracks previously on the call have been re-added, both local and remote.

Information about a Track can be retrieved using the media.getTrackById API.

client.on('call:tracksAdded', function (params) {
   // Get the information for each track.
   const tracks = params.trackIds.map(client.media.getTrackById)
   tracks.forEach(track => {
     const { id, kind, isLocal } = track
     // Handle the track depending whether it is audio vs. video and local vs. remote.
     ...
   })
})

Tracks have been removed from the Call after an SDK operation. The tracks may still exist, but the media is not available to both sides of the Call any longer.

Tracks are removed from a Call when either the local or remote user stops the tracks, by using the call.removeMedia API for example, or when the Call is held with the call.hold API.

This event can indicate that multiple tracks have been removed by the same operation. For example, if the remote user removed video from the call, this event would indicate a single, remote video track was removed. If the local user held the call, this event would indicate that all tracks on the call have been removed, both local and remote.

Information about a Track can be retrieved using the media.getTrackById API.

client.on('call:tracksRemoved', function (params) {
   // Get the information for each track.
   const tracks = params.trackIds.map(client.media.getTrackById)
   tracks.forEach(track => {
     const { id, kind, isLocal } = track
     // Handle the track depending whether it is audio vs. video and local vs. remote.
     ...
   })
})

Stats have been retrieved for a Call or specific Track of a Call.

See the call.getStats API for more information.

client.on('call:statsReceived', function (params) {
   if (params.error) {
     // Handle the error from the operation.
     const { code, message } = params.error
     ...
   } else {
     // Iterate over each individual statistic inside the RTCPStatsReport Map.
     // Handle the data on its own or collate with previously gathered stats
     //    for analysis.
     params.result.forEach(stat => {
       ...
     })
   }
})

A local Track has been replaced by the call.replaceTrack API.

This event is a combination of a track being removed from the Call and a new track being added to the Call. The previous Track's media is no longer available, similar to the call:tracksRemoved event, and the new Track is available in its place, similar to the call:tracksAdded event. The event includes information about the Track that was replaced to help an application replace it seamlessly.

client.on('call:trackReplaced', function (params) {
  const { callId, oldTrack, newTrackId } = params

  // Unrender the removed track.
  handleTrackGone(oldTrack, callId)

  // Render the added track.
  const track = client.media.getTrackById(newTrackId)
  handleTrackAdded(track, callId)
})

Custom Parameters have been received for a Call.

These are parameters set by the remote endpoint of the Call. Please refer to CustomParameter for more information.

The list of available and supported codecs by the browser have been retrieved.

This event is emitted as a result of the call.getAvailableCodecs API. Please refer to the API for more information.

client.on('call:availableCodecs', function (codecs) {
   // Iterate over each codec.
   codecs.forEach(codec => {
       // Handle the data by analysing its properties.
       // Some codec instances may have the same name, but different characteristics.
       // (i.e. for a given audio codec, the number of suported channels may differ (e.g. mono versus stereo))
       ...
   })
})

A Call's media connection state has been changed.

This event is emitted as a result of changes to the media connection of the Call. These state changes occur during call establishment, connection loss/re-establishment, call completion, etc.

To check the media connection state of a call, retrieve the call's information using the call.getById API, and check the mediaConnectionState property of the call. See call.mediaConnectionStates for the list of possible values and descriptions.

A media restart operation for a Call has been attempted.

This event is emitted as a result of the call.restartMedia API being called. See the description for call.restartMedia for information about its usage.

The call:mediaConnectionChange event will also be emitted alongside this event when the media restart operation is successful.

client.on('call:mediaRestart', function (params) {
   if (params.error) {
     // The operation failed. May want to determine whether to re-attempt the
     //    operation (if the failure was simply a connectivity issue) or to
     //    consider the call's media irrecoverable.
     ...
   } else {
     // The call should be re-establishing media, with the call's
     //    `mediaConnectionState` being updated.
     const mediaState = client.call.getById(params.callId).mediaConnectionState
     ...
   }
})

Gets the list of call logs cached locally. The event callHistory:changed is used to indicate the local state of logs has been updated.

client.on('callHistory:change', function() {
    // Get all call logs when they've been updated.
    let callLogs = client.call.history.get();
});

Fetches the list of call logs and stores them locally. The API CallHistory.get can then be used to get the logs from local state after it has been updated.

Deletes the specified call log.

Deletes all call logs.

Gets the cached call history data and returns stringified data.

The data is provided in a format that can be used directly with the call.history.setCache API. This allows an application to persist the information across SDK instances when the backend environment does not support the CallHistory feature.

Sets the cached call history data, expects stringified data as it will be parsed.

The data can be retrieved from the call.history.getCache API. This allows an application to persist the information across SDK instances when the backend environment does not support the CallHistory feature.

Call history state has been updated. See CallHistory.get to retrieve new state.

An error occurred while performing a call history operation.

Call history cached state has been updated

Attempts to establish a call between two specified devices.

Gets all local clickToCall calls

ClickToCall has successfully started.

ClickToCall had an error.

Information about a websocket connection.

Can be retrieved using the connection.getSocketState API.

Type: Object

Get the state of the websocket.

Enables or disables connectivity checking.

This API will change the connectivity.checkConnectivity configuration set during SDK initialization. If there was a connected websocket while it is changed, the change will take affect immediately.

Resets the connected websocket by manually disconnecting then reconnecting.

This API will simulate the SDK receiving a websocket disconnect from the browser, which will trigger its recovery functionality. This API can be used if the application is aware of a network issue before the SDK is notified by the browser.

If there is no websocket connected, this API has no effect. If the SDK is not configured to autoreconnect (see connectivity.autoReconnect configuration property), then this API will not attempt to reconnect the websocket automatically.

The normal websocket and lifecycle events will be emitted during this operation, notably the ws:change event.

The WebSocket to the server has changed state.

This event is only emitted when the WebSocket is connected, or has lost connection.

Add a contact to a user's personal address book. Will trigger the contacts:new event.

Retrieves local information about a contact.

Retrieves local information about all contacts.

Refreshes the local information about contacts. This will get new contacts from the platform. Will trigger the contacts:change event.

Remove a contact from a personal address book. Will trigger the contacts:change event.

Update a contact from the user's personal address book. Will trigger the contacts:change event.

Fetch a contact from the user's personal address book. Will trigger the contacts:change event.

A new contact has been added to the address book.

An error occurred while performing a contact operation.

The contacts list has changed.

client.on('contacts:change', function () {
   // Get the updated list of contacts.
   const contacts = client.contacts.getAll()
   ...
})

A Conversation object represents a conversation between two users. A Conversation can create messages via the conversation's createMessage() function.

Type: Object

conversation.createMessage({type: 'text', text: 'This is the message'});

A Message object is a means by which a sender can deliver information to a recipient.

Creating and sending a message:

A message object can be obtained through the Conversation.createMessage API on an existing conversation.

Messages have Parts which represent pieces of a message. Currently, only a 'text' part is suported. Once all the desired parts have been added to the message using the Message.addPart function, the message can then be sent using the Message.send function.

Once the sender sends a message, this message is saved in sender's state as an object. Similarly, once the recipient gets a message, this message is saved in recipient's state.

Retrieving a delivered message:

Once a message is delivered successfully, it can be obtained through the Conversation.getMessages or Conversation.getMessage API on an existing conversation.

Below are the properties pertaining to the message object, returned by Conversation.getMessage(s) APIs, for either sender or recipient.

Type: Object

Get a conversation object matching the user ID provided in the 'destination' parameter. If successful, the event 'conversations:change' will be emitted.

This API will retrieve a conversation already existing in the store.

Returns all conversations currently tracked by the SDK

A new conversation has been created and added to the state.

A change has occurred in the conversation list.

A change has occurred in a specific conversations message list. If a single message was affected/created, messageId will be present as part of the event argument.

An error occurred with messaging.

A LogEntry object is the data that the SDK compiles when information is logged. It contains both the logged information and meta-info about when and who logged it.

A LogHandler provided to the SDK (see config.logs) will need to handle LogEntry objects.

Type: Object

function defaultLogHandler (logEntry) {
  // Compile the meta info of the log for a prefix.
  const { timestamp, level, target } = logEntry
  let { method } = logEntry
  const logInfo = `${timestamp} - ${target.type} - ${level}`

  // Assume that the first message parameter is a string.
  const [log, ...extra] = logEntry.messages

  // For the timer methods, don't actually use the console methods.
  //    The Logger already did the timing, so simply log out the info.
  if (['time', 'timeLog', 'timeEnd'].includes(method)) {
    method = 'debug'
  }

  console[method](`${logInfo} - ${log}`, ...extra)
}

A LogHandler can be used to customize how the SDK should log information. By default, the SDK will log information to the console, but a LogHandler can be configured to change this behaviour.

A LogHandler can be provided to the SDK as part of its configuration (see config.logs). The SDK will then provide this function with the logged information.

Type: Function

// Define a custom function to handle logs.
function logHandler (logEntry) {
  // Compile the meta info of the log for a prefix.
  const { timestamp, level, target } = logEntry
  let { method } = logEntry
  const logInfo = `${timestamp} - ${target.type} - ${level}`

  // Assume that the first message parameter is a string.
  const [log, ...extra] = logEntry.messages

  // For the timer methods, don't actually use the console methods.
  //    The Logger already did the timing, so simply log out the info.
  if (['time', 'timeLog', 'timeEnd'].includes(method)) {
    method = 'debug'
  }

  console[method](`${logInfo} - ${log}`, ...extra)
}

// Provide the LogHandler as part of the SDK configurations.
const configs = { ... }
configs.logs.handler = logHandler
const client = create(configs)

Possible levels for the SDK logger.

The SDK will provide Log Entries to the Log Handler for all logs at or above the set log level. 'debug' is considered the lowest level and 'silent' the highest level. For example, if the current level is 'info', then the Log Handler will receive Log Entries for logs at 'info', 'warn', and 'error', but not for the 'debug' level.

Detached Media is a special type of call.MediaObject that is created outside the scope of a call. A DetachedMedia object is a call.MediaObject that is wrapped with the contained call.TrackObject's media type for convenience.

The APIs for managing detached media are available in the media namespace. They are media.createLocalMedia, media.getLocalMedia, and media.disposeLocalMedia. Unlike media that is created as part of a call, the application is responsible for the lifecycle for a detached media object.

Accessing local media before a call is made can be used to implement a "media preview" feature, allowing an end-user to check their media devices before joining a call.

Detached Media can also be used as part of a call, rather than new media being created as part of the call operations. This can be done as an optimization, to avoid the overhead of creating new media objects during the call setup process. The same Detached Media objects can be used for multiple calls, as well.

Type: Object

// Create new detached media objects.
const medias = await client.media.createLocalMedia({ audio: true, video: true })
// medias === [ { type: 'audio', media: <call.MediaObject> }, { type: 'video', media: <call.MediaObject> } ]
// where medias[x].type === client.media.getTrackById(medias[x].media.tracks[0].id).type)

// Render the local video as a preview.
client.media.renderTracks([ medias[1].media.tracks[0].id ], '#localVideoPreview')

// Use the Detached Media in a call, instead of creating new media for it.
const call = client.call.make('destination', { audio: false, video: false, medias: medias })

Retrieves the available media devices for use.

The devices:change event will be emitted when the available media devices have changed.

Retrieves an available Media object with a specific Media ID.

Retrieve an available Track object with a specific Track ID.

Requests permission to access media devices on the end-user's machine.

This API will trigger the browser to ask the end-user for permission to access their camera and/or microphone. These permissions are needed for the SDK to read information about the devices (the label, for example) and for using the devices for a call.

If the browser does not yet have permission, it will prompt the end-user with a small pop-up window, giving the user a chance to allow/deny the permissions. The behaviour of this pop-up window differs slightly based on the browser; it may automatically save the user's decision (such as in Chrome and Safari) or it may require the user to choose whether their decision should be saved (such as in Firefox).

This API is not required for proper usage of media and/or calls, but helps to prepare a user before a call is made or received. It allows an application to prompt the user for device permissions when it is convenient for them, rather than during call setup. If the user saves their decision, they will not be prompted again when the SDK accesses those devices for a call.

For device information, the media.getDevices API will retrieve the list of media devices available for the SDK to use. If this list is empty, or is missing information, it is likely that the browser does not have permission to access the device's information. We recommend using the media.initializeDevices API in this scenario if you would like to allow the end-user to select which device(s) they would like to use when they make a call, rather than using the system default.

The SDK will emit a devices:change event when the operation is successful or a devices:error event if an error is encountered.

// The SDK will ask for both audio and video permissions by default.
client.media.initializeDevices()

// The SDK will only ask for audio permissions.
client.media.initializeDevices({ audio: true, video: false })

Create local media Tracks.