kandy-link-js-sdk-3.x

3.40.0

create

The SDK creation factory. Create an instance of the SDK by calling this factory with the desired configurations. The SDK instance will be referred as 'api' throughout the rest of the documentation content.

create(config: config): api
Parameters
config (config) The configuration object.
Returns
api: The SDK instance.
Example
// Instantiate the SDK.
import { create } from 'kandy'
const client = create({
    authentication: { ... },
    logs: { ... },
    ...
});
// Use the SDK's API.
client.on( ... );

config

The configuration object. This object defines what different configuration values you can use when instantiating the SDK using the create function.

config
Configurations By Feature
config.logs
config.authentication
config.call
config.connectivity
config.notifications

devices:change

Available media devices have been changed.

devices:change
Parameters
params (Object)
Name Description
params.devices Object The devices, separated by device type.

devices:defaultsChange

A change has been made to default devices used for calls.

devices:defaultsChange
Parameters
params (Object)
Name Description
params.devices Object The devices now set as default.

media:initialize

Media support has been checked.

media:initialize
Parameters
params (Object)
Name Description
params.result Object Results of initializing media.
params.result.error boolean Whether the initialization was successful or not.
params.result.code number A unique code describing the result scenario.
params.result.message string Human readable message of the result.

videoPreview:change

The status of previewing local video has changed.

videoPreview:change
Parameters
params (Object)
Name Description
params.displaying boolean Whether the local video preview is being displayed or not.

videoPreview:error

An error has occurred when changing local video preview status.

videoPreview:error
Parameters
params (Object)
Name Description
params.error api.BasicError Information about the error.

api

The 'api' is the type returned by the create function. It contains various top-level functions that pertain to SDK global instance as well as several nested namespaces that pertain to various features (e.g. call, contacts, presence, etc).

api
Types
BasicError
Functions
getVersion()
destroy()
getConfig()
updateConfig(newConfigValues)
on(type, listener)
off(type, listener)
subscribe(listener)
unsubscribe(listener)
connect(credentials, options?)
connect(credentials, options?)
disconnect()
updateConnection(connection)
getUserInfo()
getConnection()
getServices()
subscriptionStates
disconnectReasons
setCredentials(credentials)
setCredentials(credentials)
Events
auth:change
auth:error
auth:resub
auth:credentialsSet

AudioBridge

The audio bridge feature allows multiple audio calls to be bridged together for a local three-way call.

Audio bridge functions are all part of the 'audioBridge' namespace.

AudioBridge
Functions
create()
close(bridgeId)
addCall(bridgeId, callId)
removeCall(bridgeId, callId)
mute(bridgeId)
unmute(bridgeId)
silence(bridgeId)
unsilence(bridgeId)
getAll()
getBridgeCalls(bridgeId)
Events
audioBridge:change
audioBridge:error

callHistory

The 'call.history' namespace is used to retrieve and inspect the authenticated users call logs.

Functions below are all part of this namespace.

callHistory
Functions
fetch(amount, offset)
remove(recordId)
clear()
get()
getCache()
setCache(data)
Events
callHistory:change
callHistory:error
callHistoryCache:change

Calls

The Calls feature is used to make audio and video calls to and from SIP users and PSTN phones.

Call functions are all part of the 'call' namespace.

Whenever 'user' is mentioned as input parameter within this API, it needs to be provided in the user@domain format.

Calls
Functions
getAll()
getById(callId)
changeInputDevices(callId)
changeSpeaker(speakerId)
states
mediaStates
make(callee, options?)
answer(callId, options?)
ignore(callId)
reject(callId)
end(callId)
mute(callId)
unmute(callId)
silence(callId)
unsilence(callId)
getCustomParameters(callId)
setCustomParameters(callId, customParameters)
startVideo(callId, options?)
stopVideo(callId)
hold(callId)
unhold(callId)
startScreenshare(callId, options)
stopScreenshare(callId)
sendDTMF(callId, tone)
sendCustomParameters(callId)
forwardCall(callId, destination)
directTransfer(callId, destination)
consultativeTransfer(callId, destinationCallId)
join(callId, destinationCallId)

clickToCall

The clickToCall namespace is used to bridge a call between two specified devices

clickToCall
Functions
make(caller, callee)
get()
Events
clickToCall:start
clickToCall:error

connection

The 'connection' namespace is used to connect and maintain connections between the SDK and one or more backend servers.

connection
Types
WSConnectionObject
Functions
getSocketState(platform)
enableConnectivityChecking(enable)
resetConnection()
Events
ws:change

contacts

The 'contacts' namespace allows users to store personal contacts to their account.

contacts
Functions
add(contact)
get(contactId)
getAll()
refresh()
remove(id)
update(contact)
fetch(contactId)
Events
contacts:new
contacts:error
contacts:change

conversation

The messaging feature revolves around a 'conversation' namespace. It is responsible to store the conversations and its messages, and return conversation objects when requested.

See the "Conversation" and "Message" sections of the documentation for more details.

Messaging functions are all part of the 'conversation' namespace. Ex: client.conversation.get('id').

conversation
Types
Conversation
Message
Functions
get(destination, options?)
getAll()
Events
conversations:new
conversations:change
messages:change
messages:error

DEVICE_ERROR

An error occurred while performing a device operation.

DEVICE_ERROR

Type: string

Parameters
params (Object)
Name Description
params.error api.BasicError The Basic error object.

getDevices

Retrieves the available media devices for use.

getDevices()

logger

The SDK has an internal logging system for providing information about its behaviour. The SDK will generate logs, at different levels for different types of information, which are routed to a "Log Handler" for consumption. An application can provide their own Log Handler (see config.logs) to customize how the logs are handled, or allow the default Log Handler to print the logs to the console.

The SDK's default Log Handler is merely a thin wrapper around the browser's console API (ie. window.console). It receives the log generated by the SDK, called a "Log Entry", formats a human-readable message with it, then uses the console to log it at the appropriate level. This is important to be aware of, since your browser's console may affect how you see the SDK's default log messages. Since the default Log Handler uses the console's levels, the browser may filter which messages are shown depending on which levels it has configured. For a user that understands console log levels, this can be helpful for filtering the logs to only the relevant information. But it can equally be a hindrance by hiding the more detailed log messages (at the 'debug' level), since browser can have this level hidden by default. For this reason, we recommend providing a custom Log Handler to the SDK that is better suited for your application and its users.

logger
Types
LogEntry
LogHandler(LogEntry)
Functions
levels()

Media

The SDK's media features are used to control WebRTC Media Devices.

Media functions are all part of the 'media' namespace.

Media

notification

The 'notification' namespace allows user to register/deregister for/from push notifications as well as enabling/disabling the processing of websocket notifications.

notification
Functions
process(notification, channel?)
registerApplePush(params)
registerAndroidPush(params)
unregisterApplePush(registrationInfo)
unregisterAndroidPush(registrationInfo)
enableWebsocket(enable)
Events
notifications:change
notifications:error

presence

The 'presence' namespace provides an interface for an application to set the User's presence information and to track other Users' presence information.

Presence information is persisted by the server. When the SDK is initialized, there will be no information available. Presence information will become available either by using presence.fetch or by subscribing for updates about other Users, using presence.subscribe.

Available presence information can be retrieved using presence.get or presence.getAll.

presence
Types
PresenceStatus
Functions
statuses
activities
update(status, activity, note?)
get(user)
getAll()
getSelf()
fetch(user)
subscribe(users)
unsubscribe(users)
Events
presence:change
presence:selfChange
presence:subscribe
presence:unsubscribe
presence:error

promptUserMedia

Prompt the user for permission to use their audio and/or video devices.

promptUserMedia(options: Object?)
Parameters
options (Object?)
Name Description
options.video boolean? Whether to get permission for video.
options.audio boolean? Whether to get permission for audio.

request

The 'request' namespace (within the 'api' type) is used to make network requests to the server.

request
Functions
fetch(resource, init)

sdpHandlers

A set of SdpHandlerFunctions for manipulating SDP information. These handlers are used to customize low-level call behaviour for very specific environments and/or scenarios.

Note that SDP handlers are exposed on the entry point of the SDK. They can be added during initialization of the SDK using the config.call.sdpHandlers configuration parameter. They can also be set after the SDK's creation by using the call.setSdpHandlers function.

sdpHandlers
Example
import { create, sdpHandlers } from 'kandy';
const codecRemover = sdpHandlers.createCodecRemover(['VP8', 'VP9'])
const client = create({
  call: {
    sdpHandlers: [ codecRemover, <Your-SDP-Handler-Function>, ...]
  }
})
// Through the Call API post-instantiation
client.call.setSdpHandlers([ codecRemover, <Your-SDP-Handler-Function>, ...])
Types
CodecSelector
Functions
createCodecRemover(codecs)

setDefaultDevices

Sets the selected devices as the default devices. They will be used for audio output for future calls. Changing speaker is supported on browser's that support HTMLMediaElement.setSinkId().

setDefaultDevices(devices: Object)
Parameters
devices (Object)
Name Description
devices.camera string? The ID of the camera to set as default.
devices.microphone string? The ID of the microphone to set as default.
devices.speaker string? The ID of the speaker to set as default.
Example
// Set only the default microphone and camera.
client.media.setDefaultDevices({
    camera: 'abc123...',
    microphone: 'def456...'
});

sip

The SIP Events feature allows an application to communicate with a SIP network integrated with their Kandy Link instance. The SIP network may generate custom events intended for an application, which can be handled with the SDK's sip namespace.

Usage of SIP Events is dependent on your Kandy Link instance. The types of SIP Events can be different based on configurations and components, often being part of a custom solution. As such, the SIP Events feature is presented in a generic manner to be flexible for any possible events.

An example of a common SIP event is "SIP presence". When a user is connected to a SIP phone, the network may generate "phone presence" events when the user starts and ends a call (eg. 'On Call', 'Available'). Applications can subscribe to receive these events for specific users.

A SIP event may either be solicited or unsolicited. Solicited events, such as the "presence" example above, requires the application to subscribe for the event. See the sip.subscribe API for more information about solicited events. Unsolicited events have no prerequisites for being received.

sip
Functions
subscribe(eventType, subscribeUserList, clientCorrelator, customParameters?)
update(eventType, userLists, customParameters?)
unsubscribe(eventType)
getDetails(eventType?)
Events
sip:subscriptionChange
sip:error
sip:eventsChange

startPreviewVideo

Starts the local video stream and displays it to the user.

startPreviewVideo(videoContainer: HTMLElement?)
Parameters
videoContainer (HTMLElement?) The container to use for local video.
Example
``` javascript
 var container = document.getElementById('local-video');
 client.media.startPreviewVideo(container);
```

stopPreviewVideo

Stops the local video stream created in startPreviewVideo.

stopPreviewVideo()

user

The 'user' namespace allows access to user information for users within the same domain.

user
Types
User
Functions
fetch(userId)
fetchSelfInfo()
get(userId)
getAll()
search(filters)
Events
directory:change
directory:error
users:change
users:error

voicemail

The 'voicemail' namespace is used to retrieve and view voicemail indicators.

Voicemail functions are all part of this namespace.

voicemail
Functions
fetch()
get()
Events
voicemail:change
voicemail:error