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

Configuration options for the Authentication feature.

Configuration options for the call feature.

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.

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

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

Connect with user credentials to any backend services that the SDK instance deals with.

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

Connect by providing an access token to any backend services that the SDK instance deals with.

client.connect({
  username: 'alfred@example.com',
  accessToken: 'AT0V1fswAiJadokx1iJMQdG04pRf',
  expires: 3600
});

Connect by providing a username and HMAC token. This connects to any backend services that the SDK instance deals with. An HMAC token is used to verify a user via the user's authorization within an 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.

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

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

Connect by providing a bearer access token to any backend services that the SDK instance deals with.

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

Disconnects from the backend. This will close the websocket and you will stop receiving events.

If you're authenticating with tokens that expire and have not provided a refresh token to the connect function, you can update your access token with updateToken before it expires to stay connected.

If you're authenticating with tokens that expire, you can update your access token with updateToken before it expires to stay connected.

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

Retrieves information about the current user.

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

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

Sets the username and HMAC token necessary to make requests to the platform. 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.

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

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

Provides a bearerAccessToken to any backend services that the SDK instance deals with. The bearerAccessToken provided establishes what can be accessed by the SDK.

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

Provides an access token to any backend services that the SDK instance deals with. The access token provided establishes what can be accessed by the SDK.

client.setCredentials({
  username: 'alfred@example.com',
  accessToken: 'ATgtBl8QAoJaeeJU!zhARKBYaN2BUxFQsc8F...'
});

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

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

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

Type: string

The TEL URI ie: tel:+18885559876

Type: string

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.

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

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.

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.

To change or remove the custom parameters on a call, use the call.setCustomParameters API.

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)

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.

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

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

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

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.

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

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.

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

A Conversation object represents a conversation between either two users, or a user and a group. 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, 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

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.

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.

Provides an external notification to the system for processing.

Registers with Apple push notification service. Once registration is successful, the application will be able to receive standard and/or voip push notifications. It can then send these notifications to the SDK with api.notifications.process in order for the SDK to process them.

Registers with Google push notification service. Once registration is successful, the application will be able to receive standard and/or voip push notifications. It can then send these notifications to the SDK with api.notifications.process in order for the SDK to process them.