Configuration options for the Logs feature.

Configuration options for the Authentication feature.

Configuration options for the call feature.

Configuration options for the Connectivity feature.

Configuration options for the notification feature.

Gets the current configuration Object

Update values in the global Config section of the store.

Connect by providing an OAuth token.

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

Connect by providing a refresh token.

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

Connect by providing an access token. You can optionally provide a refresh token and the SDK will automatically get new access tokens.

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

Connect with user credentials.

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

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.

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

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.

Retrieves information about the current user.

Get the connection state.

Retrieves the services that the user is subscribed for.

Possible subscription states of the user.

Possible reasons for disconnecting.

Authentication state has changed. You can get the new state by calling getConnection().

There was an error with authentication.

An attempt to extend the current user's subscription was made.

In a failure scenario, the current user is still connected, and further resubscription attempts will be made, but may become disconnected if the session expires.

Fetches the list of call logs and stores them locally. The API getCallLogs 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 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();
});

Gets the cached call history data and returns stringified data.

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

Call history state has been updated. See getCallLogs() to retrieve new state.

An error occured while performing a call history operation.

Call history cached state has been updated

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

Type: Object

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.

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

Type: Object

Type: Object

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

Type: Function

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

Contains information about a device.

Type: Object

A collection of media devices and their information.

Type: Object

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

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

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

Get a report about low-level call statistical information.

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

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

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. Both remote participants will see their call be unheld, and will be connected to one another after the operation. Both calls for the current user will be ended.

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 "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 calls for the current user will be ended after the 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.

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

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.

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.

// 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) {
     // Render call media ...
   }
})

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.

A new Track has been added to the Call.

The Track may have been added by either the local user or remote user using the call.addMedia API.

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

A Track has been removed from a Call.

The Track may have been removed by either the local user or remote user using the call.removeMedia API. Tracks are also removed from Calls automatically while the Call is on hold.

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

See the call.getStats API for more information.

A Track has been replaced on the Call.

A Track is replaced by the local user using the call.replaceTrack API.

This event is similar to the call:newTrack event, where the call has a new Track, except that an existing Track has been removed at the same time. The event includes information about the Track that was replaced to help an application replace it seamlessly.

Attempts to establish a call between two specified devices

Gets all local clickToCall calls

ClickToCall has successfully started.

ClickToCall had an error.

Get the state of the websocket.

Enables or disables connectivity checking.

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

Add an event listener for the specified event type.

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

• Error: Invalid event type

Adds a global event listener

• Error: Listener not a function

Removes a global event listener

• Error: Listener not a function

Possible levels for the SDK logger.

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.

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 an outgoing call is accepted, render the Media used for the call.
client.on('call:accepted', function (params) {
    // Get the information about the call.
    const call = client.call.getById(params.callId)

    // Render the call's local and remote media in their respective containers.
    client.media.render(call.localMedia[0], localContainer)
    client.media.render(call.remoteMedia[0], remoteContainer)
})

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 at their media source.

Prevents media from being received for the Tracks. Audio Tracks will become silent and video Tracks will be a black frame.

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.

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

Unmutes the specified Tracks.

Media will resume as normal for the Tracks.

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

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.

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 represents an individual message. Messages have parts which represent pieces of a message, such as a text part or a file part. Once all the desired parts have been added, a message can be sent with the send() function.

Type: Object

Attempts to retrieve a list of conversations that the current user is a part of. These conversations can then be retrieved from the store using get().

Get a conversation object matching the user IDs provided. If successful, the event 'conversations:change' will be emitted. Multi-user conversations have a destination comprised of multiple user IDs.

Create and return a new conversation object. Any messages being sent through this conversation object will be sent to the destinations provided

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

A change has occured in the conversation list.

A change has occured 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 occured with messaging.

Provides an external notification to the system for processing.

Registers a device token for push notifications.

Deregisters for push notifications.

Enables, or disables, the processing of websocket notifications.

Push notifications registration state has changed.

An error occured with push notifications.

Possible status values.

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

Possible activity values.

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.

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 presnece.update API.

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.

A presence update about a subscribed user has been received.

The current user's presence information has changed.

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

An error occurred with presence.

In some scenarios it's necessary to remove certain codecs being offered by the SDK to the remote party. 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 SDK provides a codec removal handler creator that can be used for this purpose.

The SDP handlers are exposed on the entry point of the SDK. They need to be added to the list of SDP handlers via configuration on creation of an instance of the SDK.

import { create, sdpHandlers } from 'kandy';
const codecRemover = sdpHandlers.createCodecRemover(['VP8', 'VP9'])
const client = create({
  call: {
    sdpHandlers: [codecRemover]
  }
})

Subscribe for a sip event.

Update a subscription for a sip event.

Unsubscribe from a sip event.

Retrieve information about a specified sip event.

A change in SIP event subscriptions has occurred.

An error occurred while performing a SIP event action.

A SIP event notification has been received.

The User data object.

Type: Object

Fetches information about a User.

The SDK will emit a directory:change event after the operation completes. The User's information will then be available.

Information about an available User can be retrieved using the user.get API.

Fetches information about the current User from directory. Compared to user.fetch API, this API retrieves additional user related information.

The SDK will emit a directory:change event after the operation completes. The User's information will then be available.

Information about an available User can be retrieved using the user.get API.

Retrieves information about a User, if available.

See the user.fetch and user.search APIs for details about making Users' information available.

Retrieves information about all available Users.

See the user.fetch and user.search APIs for details about making Users' information available.

Searches the domain's directory for Users.

The SDK will emit a directory:change event after the operation completes. The search results will be provided as part of the event, and will also be available using the user.get and user.getAll APIs.

The directory has changed.

An error occurred while performing a directory operation.

Attempts to retrieve voicemail information from the server. A voicemail:new event is emitted upon completion.

Returns voicemail data from the store.

A voicemail event has been received.

An error has occured while attempting to retrieve voicemail data.