kandy-uc-js-sdk

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

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?)
connect(credentials, options?)
connect(credentials, options?)
disconnect()
updateToken(credentials)
updateToken(credentials)
getUserInfo()
getConnection()
getServices()
subscriptionStates
disconnectReasons
setCredentials(credentials)
getBrowserDetails()
Events
auth:change
auth:error
auth:resub
auth:credentialsSet
request:error

call

The 'call' namespace (within the 'api' type) 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.

call
Types
CallObject
MediaConstraint
MediaOffered
BandwidthControls
DSCPControls
RTCPeerConnectionConfig
IceServer
IceCollectionInfo
IceCollectionCheckFunction(iceCollectionInfo, iceTimeouts)
IceCollectionCheckResult
SdpHandlerInfo
SdpHandlerFunction(newSdp, info, originalSdp)
MediaObject
TrackObject
DevicesObject
DeviceInfo
CustomParameter
SIP_URI
TEL_URI
Functions
make(destination, media, options?)
reject(callId)
answer(callId, media, options?)
sendRingingFeedback(callId)
ignore(callId)
hold(callId)
unhold(callId)
setCustomParameters(callId, customParameters)
sendCustomParameters(callId)
getAll()
getById(callId)
end(callId)
addMedia(callId, media, options = {})
removeMedia(callId, tracks, options = {})
startVideo(callId, videoOptions?, options?)
stopVideo(callId)
startScreenshare()
stopScreenshare()
sendDTMF(callId, tone, duration, intertoneGap)
getStats(callId, trackId?)
forward(callId, destination)
consultativeTransfer(callId, otherCallId)
directTransfer(callId, destination)
join(callId, otherCallId)
replaceTrack(callId, trackId, media)
getAvailableCodecs(kind)
setSdpHandlers(sdpHandlers)
states
mediaConnectionStates
restartMedia(callId)
setDefaultDevices()
changeInputDevices()
changeSpeaker()
Events
call:operation
call:start
call:join
call:receive
call:stateChange
call:newMedia
call:removedMedia
call:newTrack
call:trackEnded
call:statsReceived
call:trackReplaced
call:customParameters
call:availableCodecs
call:mediaConnectionChange
call:mediaRestart

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

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
fetch(options?)
get(destination, options?)
create(recipient, type, options)
Events
conversations:new
conversations:change
messages:change
messages:error

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 'media' namespace provides an interface for interacting with Media that the SDK has access to. Media is used in conjunction with the Calls feature to manipulate and render the Tracks sent and received from a Call.

Media and Track objects are not created directly, but are created as part of Call operations. Media and Tracks will either be marked as "local" or "remote" depending on whether their source is the local user's machine or a remote user's machine.

The Media feature also keeps track of media devices that the user's machine can access. Any media device (eg. USB headset) connected to the machine can be used as a source for media. Available devices can be found using the media.getDevices API.

media
Functions
getDevices()
getById(mediaId)
getTrackById(trackId)
initializeDevices(constraints?)
renderTracks(trackIds, cssSelector, options?)
removeTracks(trackIds, cssSelector)
muteTracks(trackIds)
unmuteTracks(trackIds)
Events
devices:change
devices:error
media:muted
media:unmuted
media:sourceMuted
media:sourceUnmuted
media:trackRendered

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

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)

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

user

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

user
Types
User
UserID
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