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 Authentication feature.

Configuration options for the call feature.

Configuration options for the Connectivity feature. Can use pingPong (default) or keepAlive as the connectivity check.

Ping Pong: The responsibleParty (default 'client') sends "ping" messages to the other party (default 'server') on the websocket at regular intervals, and the other party is expected to respond with a "pong" message. This lets both sides know that the connection is still valid and that they can receive messages from each other.

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

Keep Alive is the older/simpler method where only one side (the server) has logic for handling the connection. The server knows that if it doesn't receive the keepalive messages, the client is gone and it should clean-up the connection/websocket. In Ping pong, both sides can handle the connection. Both sides can determine if the connection is gone because they will miss the ping or pong message from the other side. The benefit of ping pong is that both sides learn of possible issues sooner.

For more information on these methods refer to these documents:

https://en.wikipedia.org/wiki/Ping-pong_scheme

https://en.wikipedia.org/wiki/Keepalive

Configuration options for the notification feature.

Configuration options for the Subscription 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 'kandy'
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 updating the call.removeH264Codecs configuration will not immediately change the SDP handlers used for a call. If you want to add or remove the h264 codec remover sdp handler you should follow this procedure:

1. Update the config for removeH264Codecs using the updateConfig API.

2. Update the sdp handler list using the setSdpHandlers API and provide any client defined SDP handler functions.

   NOTE: You can get the currently defined SDP handler functions with the getConfig API.

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.

• Error: Invalid event type

// 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.

• Error: Invalid event type

Adds a global event listener to SDK instance.

• Error: Listener not a function

Removes a global event listener from SDK instance.

• Error: Listener not a function

Retrieves information about the current user.

Sets the authentication tokens necessary to make requests to the platform. The access token provided establishes what can be accessed by the SDK. The identity token represents who is authenticated.

client.setTokens({
  accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  idToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
})

Sets the authentication tokens necessary to make requests to the platform. The bearerAccessToken provided establishes what can be accessed by the SDK. The identity token represents who is authenticated.

client.setCredentials({
  bearerAccessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  idToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
});

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}.`)

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.

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 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

The User ID ie: joe@test.3s5j.att.com

Type: string

The Phone Number ie: +18885559876

Type: string

Starts an outgoing call to a UserID or a PhoneNumber.

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 (e.g. 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.

// 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 })

Rejects an incoming call.

The specified call to reject 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 be notified, through their own call:stateChange event, that the call was rejected.

Answers an incoming call.

The specified call to answer must be in Initiated or 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.

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.

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.

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.

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.

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.

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:newTrack 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:trackEnded event for both the local and remote users to indicate that a track has been removed.

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

The latest SDK release (v4.X+) has not yet implemented this API in the same way that it was available in previous releases (v3.X). In place of this API, the SDK has a more general API that can be used for this same behaviour.

The call.addMedia API can be used to perform the same behaviour as startScreenshare. {@link call.addMedia} is a general-purpose API for adding media to a call, which covers the same functionality as startScreenshare. Selecting only screen options when using call.addMedia will perform the same behaviour as using startScreenshare.

// Select media options for adding only screenshare.
const media = {
   audio: false,
   video: false,
   screen: true,
   screenOptions: { ... }
}

// Add the selected media to the call.
client.call.addMedia(callId, media)

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

The latest SDK release (v4.X+) has not yet implemented this API in the same way that it was available in previous releases (v3.X). In place of this API, the SDK has a more general API that can be used for this same behaviour.

The call.removeMedia API can be used to perform the same behaviour as stopScreenshare. {@link call.removeMedia} is a general-purpose API for removing media from a call, which covers the same functionality as stopScreenshare. Specifying only the screen track when using call.removeMedia will perform the same behaviour as using stopScreenshare.

There is a caveat that if a Call has multiple video tracks (for example, both a video and a screen track), the SDK itself cannot yet differentiate one from the other. The application will need to know which track was the screen track in this scenario.

const call = client.call.getById(callId)
// Get the ID of any/all video tracks on the call.
const videoTracks = call.localTracks.filter(trackId => {
   const track = call.media.getTrackById(trackId)
   // Both video and screen tracks have kind of 'video'.
   return track.kind === 'video'
})

// Pick out the screen track.
const screenTrack = videoTracks[0]

// Remove screen from the call.
client.call.removeMedia(callId, [ screenTrack ])

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 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.

client.on('call:statsReceived', function (params) {
   // Iterate over each individual statistic inside the RTCPStatsReport.
   params.result.forEach(stats => {
       // Handle the data on its own or collate with previously gathered stats
       //    for analysis.
       ...
   })
})

// Get a snapshot of the Call's stats.
//   This may be done on a regular interval to collect data over time.
client.call.getStats(callId)

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
})

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(). Firefox browser does not currently support this method. Therefore, this API will not work on Firefox.

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
  }
}

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 {@link call.event:call:mediaConnectionChange 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.

The setDefaultDevices API from previous SDK releases (3.X) has been deprecated in the latest releases (4.X+). The SDK no longer keeps track of "default devices" on behalf of the application.

The devices used for a call can be selected as part of the APIs for starting the call. Microphone and/or camera can be chosen in the call.make and call.answer APIs, and speaker can be chosen when the audio track is rendered with the media.renderTracks API.

Changes the camera and/or microphone used for a Call's media input.

The latest SDK release (v4.X+) has not yet implemented this API in the same way that it was available in previous releases (v3.X). In place of this API, the SDK has a more general API that can be used for this same behaviour.

The same behaviour as the changeInputDevices API can be implemented using the general-purpose call.replaceTrack API. This API can be used to replace an existing media track with a new track of the same type, allowing an application to change certain aspects of the media, such as input device.

const call = client.call.getById(callId)
// Get the ID of the Call's video track.
const videoTrack = call.localTracks.find(trackId => {
   const track = client.media.getTrackById(trackId)
   return track.kind === 'video'
})

// Select the new video options.
const media = {
   video: true,
   videoOptions: {
       deviceId: 'cameraId'
   }
}

// Change the call's camera by replacing the video track.
client.call.replaceTrack(callId, videoTrack, media)

Changes the speaker used for a Call's audio output. Supported on browser's that support HTMLMediaElement.setSinkId().

The latest SDK release (v4.X+) has not yet implemented this API in the same way that it was available in previous releases (v3.X). In place of this API, the SDK has a more general API that can be used for this same behaviour.

The same behaviour as the changeSpeaker API can be implemented by re-rendering the Call's audio track. A speaker can be selected when rendering an audio track, so changing a speaker can be simulated by unrendering the track with media.removeTracks, then re-rendering it with a new speaker with media.renderTracks.

const call = client.call.getById(callId)
// Get the ID of the Call's audio track.
const audioTrack = call.localTracks.find(trackId => {
   const track = client.media.getTrackById(trackId)
   return track.kind === 'audio'
})

// Where the audio track was previously rendered.
const audioContainer = ...

// Unrender the audio track we want to change speaker for.
client.media.removeTrack([ audioTrack ], audioContainer)
// Re-render the audio track with a new speaker.
client.media.renderTrack([ audioTrack ], audioContainer, {
   speakerId: 'speakerId'
})

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

Information about ongoing call operations are stored with the call information (see the call.getById API). This event indicates that an operation's information has been changed.

Local call operations will be tracked from start to finish. An operation may be updated as it progresses, based on the status of the operation. The operation status may be ongoing or pending, depending if the operation is waiting on activity on the local or remote end of the call, respectively.

Except in the case of slow-start operations, remote operations will only be tracked as a "finish", to indicate that it occurred.

An outgoing 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.

client.on('call:receive', function(params) {
    // We have received a call, prompt the user to respond.
    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) {
   // Iterate over each individual statistic inside the RTCPStatsReport Map.
   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)
})

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.

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 {@link 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
     ...
   }
})

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.

Triggers a reset in the connection to the WebSocket being used for notifications. This can be used in scenarios where a network issue (undetectable by the SDK) is detected by an application.

If there is no WebSocket currently connected, this function has no effect. Calling this function will trigger all the normal WebSocket and connectivity lifecycle events as well as trigger re-connection processing that follows the configuration of the SDK. Calling this function always has the potential of causing some events being lost by the SDK and preventing proper operation.

The websocket to the server has changed state.

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()
   ...
})

Possible types of conversations.

Type: Object

// Use the chat types to fetch group conversations.
client.conversation.fetch({type: client.conversation.chatTypes.GROUP}) {

A Conversation object represents a conversation either between two users, or between a user and a group. A user can create a Conversation using conversation.create Messaging API.

A Conversation can be used to create messages to send using the Conversation and Messaging APIs Conversation.createMessage and Message.send functions.

Once a sender sends the initial message (within a conversation) to a recipient, there will be a conversation object saved in both sender and recipient's state.

Type: Object

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

A Part is a custom object representing a section of the payload of a message. Messages can have one or many Parts.

Type: Object

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

Creating and sending a message:

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

Messages have Parts which represent pieces of a message, such as a text part, a json object part or a file part. 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

Fetches chat conversations that the current user is part of. This will refresh the available information with any new information from the server.

If successful, the event conversations:change will be emitted.

Available conversation information can be retrieved using the conversation.get or conversation.getAll Messaging APIs.

Retrieves a conversation object matching the User ID and Type provided if available.

Conversations are made available using the conversation.fetch or conversation.create Messaging APIs.

Creates and return a new conversation object. Any messages being sent through this Conversation object will be sent to the destination provided.

If successful, the event conversations:new will be emitted.

Retrieves all available conversations for the current user.

Conversations are made available using the conversation.fetch or conversation.create Messaging APIs.

A new conversation has been created.

A change has occurred in the conversation list.

A change has occurred in a specific conversation's message list. If a single message was created/edited, messageId will be present.

An error occurred with messaging.

The list of users that are currently typing has changed.

Creates a Group.

The SDK will emit a group:new event locally when the operation completes. This event will include a Group ID that is used to uniquely identify the group.

Remote users added to the Group during creation will receive a group:invitation_received event, which will include information about the Group. Group participants can be managed after creation using the groups.addParticipant and groups.removeParticipant APIs.

Group information will become available after the operation completes using the groups.get and groups.getAll APIs.

Fetches information about all Groups that the current user is a member of. This will refresh the available Groups with any new information from the server.

The SDK will emit a group:refresh event when the operation completes.

Information about an available Group can be retrieved using the groups.getAll or groups.get APIs.

Retrieves information about all available Groups.

Retrieves information about a single Group, if available.

Retrieves the list of participants from an available Group.

Retrieves information about all Group invitations available.

The group:invitation_received event indicates that a new Group invitation is available.

Leaves a Group.

The SDK will emit a group:change event when the operation completes.

Accepts an invitation to a Group.

The SDK will emit a group:change event when the operation completes.

Rejects an invitation to a Group.

The SDK will emit a group:change event when the operation completes.

Adds participant to a Group.

The SDK will emit a group:change event when the operation completes. The participant being added will receive a group:invitation_received event.

Removes a participant from a Group.

The SDK will emit a group:change event when the operation completes.

Deletes a Group.

The Group will no longer be available using the groups.get and groups.getAll APIs.

The SDK will emit a group:delete event for all participants in the Group.

A new Group has been created and its information is now available.

Information about an available Group can be retrieved using the groups.getAll or groups.get APIs.

// Set an event listener for new Groups being created.
client.on('group:new', params => {
   const group = client.groups.get(params.groupId)
   // Use the new group.
})

An existing Group has been modified and the new information is available.

A Group has been deleted and is no longer available.

The latest information about the Group is provided as part of the event.

The list of Groups has been refreshed.

Any previously available Groups may have had their information updated, and any otherwise unknown Groups may now be available.

Information about an available Group can be retrieved using the groups.getAll or groups.get APIs.

An invitation to a Group has been received.

Information about a Group invitation can be retrieved using the groups.getInvitations API.

An error occurred with a Group operation.

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.

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 })

Render Media Tracks in a container.

The container is specified by providing a CSS selector string that corresponds to the HTMLElement to act as the container.

// When a Call receives a new track, render it.
client.on('call:newTrack', function (params) {
   const track = client.media.getTrackById(params.trackId)
   const container = params.local ? localContainer : remoteContainer

   // Render the Call's new track when it first becomes available.
   client.media.renderTracks([ track.trackId ], container)
})

Remove Media Tracks from a container.

The container is specified by providing a CSS selector string that corresponds to the HTMLElement to act as the container.

Mutes the specified Tracks.

This API prevents the media of the specified Tracks from being rendered. Audio Tracks will become silent and video Tracks will be a black frame. This does not stop media from being received by those Tracks. The media simply cannot be used by the application while the Track is muted.

If a local Track being sent in a Call is muted, the Track will be noticeably muted for the remote user. If a remote Track received in a call is muted, the result will only be noticeable locally.

This mute operation acts on those specified Tracks directly. It does not act on the active Call as a whole.

The SDK will emit a media:muted event when a Track has been muted.

Unmutes the specified Tracks.

Media will resume its normal rendering for the Tracks. Like the 'muteTracks' API, this unmute operation acts on those specified Tracks directly. Therefore it does not act on active Call as a whole.

The SDK will emit a media:unmuted event when a Track has been unmuted.

The media devices available for use have changed.

Information about the available media devices can be retrieved using the media.getDevices API.

// Listen for changes to available media devices.
client.on('devices:change', function () {
   // Retrieve the latest media device lists.
   const devices = client.media.getDevices()
})

An error occurred while trying to access media devices.

The most common causes of this error are when the browser does not have permission from the end-user to access the devices, or when the browser cannot find a media device that fulfills the MediaConstraint(s) that was provided.

The specified Tracks have been muted.

A Track can be muted using the media.muteTracks API.

The specified Tracks have been unmuted.

A Track can be unmuted using the media.unmuteTracks API.

The specified Track has had its media source muted.

The Track is still active, but is not receiving media any longer. An audio track will be silent and a video track will be a black frame. It is possible for the track to start receiving media again (see the media:sourceUnmuted event).

This event is generated outside the control of the SDK. This will predominantely happen for a remote track during network issues, where media will lose frames and be "choppy". This may also happen for a local track if the browser or end-user stops allowing the SDK to access the media device, for example.

The specified Track has started receiving media from its source once again.

The Track returns to the state before it was muted (see the media:sourceMuted event), and will be able to display video or play audio once again.

This event is generated outside the control of the SDK, when the cause of the media source being muted had been undone.

The specified Track has been rendered into an element.

A local Track has ended unexpectedly. The Track may still be part of a Call but has become disconnected from its media source and is not recoverable.

This event is emitted when an action other than an SDK operation stops the track. The most comon scenarios are when a device being used for a Call disconnects, any local tracks (such as audio from a bluetooth headset's microphone or video from a USB camera) from that device will be ended. Another scenario is for screensharing, where some browsers provide the ability to stop screensharing directly rather than through an SDK operation.

When a local track ends this way, it will still be part of the Call but will not have any media. The track can be removed from the call with the call.removeMedia API so the remote side of the Call knows the track has stopped, or the track can be replaced with a new track using the call.replaceTrack API to prevent any interruption.

The PresenceStatus type defines the user's current status in terms of the user's availability to communicate/respond to other users in the network. An instance of this type can be obtained by invoking the presence.get function.

Reporting when a user is on the phone is enabled (by default), which means that presence update notifications will be sent whenever a user is in a call, as well as when the call has ended. This is a user preference enabled or disabled on server side, and it can only be changed on the server side.

The status is set to open as soon as a user subscribes for the presence service.

Type: Object

Possible presence status values.

Type: Object

const { statuses, activities } = client.presence
// Use the values when updating presence.
client.presence.update(statuses.OPEN, activities.AVAILABLE)

Possible presence activity values.

Type: Object

const { statuses, activities } = client.presence
// Use the values when updating presence.
client.presence.update(statuses.OPEN, activities.AVAILABLE)

Updates the presence information for the current user.

See presence.statuses and presence.activities for valid values.

The SDK will emit a presence:selfChange event when the operation completes. The updated presence information is available and can be retrieved with presence.getSelf.

Other users subscribed for this user's presence will receive a presence:change event.

Fetches presence information for the given users. This will refresh the available information with any new information from the server.

Available presence information an be retrieved using the presence.get or presence.getAll APIs.

Subscribe to another User's presence updates.

When the User updates their presence information, the SDK will emit a presence:change event.

Unsubscribe from another User's presence updates.

Retrieves the presence information for specified users, if available.

Retrieves the presence information for all available users.

Retrieves the presence information for the current user.

This information is set using the presence.update API.

A presence update about a subscribed user has been received.

This event is generated as a result of presence.fetch or presence.update operations.

For the latter operation, the current user receives a presence update of another user that the current user is subscribed to.

The changed information can be retrieved using the presence.get API.

The current user's presence information has changed.

The changed information can be retrieved using the presence.getSelf API.

An update (as a result of subscribing to a specific user's presence) has been received.

An update (as a result of unsubscribing to a specific user's presence) has been received.

An error occurred with presence.

Send a request to the underlying REST service with the appropriate configuration and authentication. This is a wrapper on top of the browser's fetch API and behaves very similarly but using SDK configuration for the base URL and authentication as well as SDK logging.

// Send a REST request to the server
// Create a request options object following [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/fetch)
const requestOptions = {
  method: 'POST',
  body: JSON.stringify({
    test: 123
  })
}

// Note that you will need to subscribe for the `custom` service in order to
// receive notifications from the `externalnotification` service.
const response = await client.request.fetch('/rest/version/1/user/xyz@test.com/externalnotification', requestOptions)

An object that represents a selector to match codecs of an RTP map in SDP.

Type: Object

This function creates an SDP handler that will remove codecs matching the selectors specified for SDP offers and answers.

In some scenarios it's necessary to remove certain codecs being offered by the SDK to remote parties. For example, some legacy call services limit the SDP length (usually to 4KB) and will reject calls that have SDP size above this amount.

While creating an SDP handler would allow a user to perform this type of manipulation, it is a non-trivial task that requires in-depth knowledge of WebRTC SDP.

To facilitate this common task, the createCodecRemover function creates a codec removal handler that can be used for this purpose. Applications can use this codec removal handler in combination with the call.getAvailableCodecs function in order to build logic to determine the best codecs to use for their application.

import { create, sdpHandlers } from 'kandy';

const codecRemover = sdpHandlers.createCodecRemover([
  // Remove all VP8 and VP9 codecs.
  'VP8',
  'VP9',

  // Remove all H264 codecs with the specified FMTP parameters.
  {
    name: 'H264',
    fmtpParams: ['profile-level-id=4d0032', 'packetization-mode=1']
  }
])

const client = create({
  call: {
    sdpHandlers: [codecRemover]
  }
})

The ServiceDescriptor type defines the format for specifying how to subscribe for a certain service. This is the service configuration object that needs to be passed (as part of an array of configuration objects) when calling the services.subscribe function. Only some plugins (call, messaging and presence) support such configuration object that needs to be passed to the subscribe function.

Type: Object

// Subscribe to chat, presence & call services on a WebSocket channel.
client.services.subscribe([
   {service: 'chat'},
   {service: 'presence'},
   {service: 'call'},
], 'websocket')

The SmsInboundServiceParams type defines the additional information when subscribing to SMS inbound service. This is the configuration object that needs to be passed as the value for the ServiceDescriptor.params property.

Type: Object

// Subscribe to smsinbound service on a WebSocket channel.
client.services.subscribe([
   {service: 'smsinbound', params: {destinationAddress: '+18001234567'}}
], 'websocket')

Subscribes to platform notifications for an SDK service.