kandy

4.10.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 refered 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
getConfig()
updateConfig(newConfigValues)
on(type, listener)
off(type, listener)
subscribe(listener)
unsubscribe(listener)
getBrowserDetails()
connect(credentials)
connect(credentials)
disconnect()
updateConnection(connection)
getUserInfo()
getConnection()
getServices()
subscriptionStates
disconnectReasons
Events
auth:change
auth:error
auth:resub

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
BandwidthControls
MediaConstraint
CallObject
MediaObject
SdpHandlerInfo
SdpHandlerFunction(newSdp, info, originalSdp)
CustomParameter
DevicesObject
IceServer
DeviceInfo
TrackObject
TEL_URI
SIP_URI
Functions
make(destination, media, options?)
reject(callId)
answer(callId, media, options?)
ignore(callId)
hold(callId)
unhold(callId)
setCustomParameters(callId, customParameters)
sendCustomParameters(callId)
getAll()
getById(callId)
end(callId)
addMedia(callId, media, options = {})
removeMedia(callId, tracks, options = {})
stopScreenshare()
stopVideo()
startVideo()
startScreenshare()
sendDTMF(callId, tone, duration, intertoneGap)
getStats(callId, trackId?)
forward(callId, destination)
consultativeTransfer(callId, otherCallId)
directTransfer(callId, destination)
join(callId, otherCallId)
replaceTrack(callId, trackId, media)
states
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

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
Functions
getSocketState(platform)
enableConnectivityChecking(enable)
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
Message
Conversation
Functions
get(destination, options?)
Events
conversations:new
conversations:change
messages:change
messages:error

logger

The internal logger is used to provide information about the SDK's behaviour. The logger can provide two types of logs: basic logs and action logs. Basic logs are simple lines of information about what the SDK is doing during operations. Action logs are complete information about a specific action that occurred within the SDK, providing debug information describing it. The amount of information logged can be configured as part of the SDK configuration. See config.logs .

logger
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)
renderTracks(trackIds, cssSelector, options?)
removeTracks(trackIds, cssSelector)
muteTracks(trackIds)
unmuteTracks(trackIds)
Events
devices:change
media:muted
media:unmuted

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?)
registerPush(params)
deregisterPush()
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
Functions
statuses
activities
update(status, activity, note?)
get(user)
getAll()
getSelf()
fetch(user)
subscribe(users)
unsubscribe(users)
Events
presence:change
presence:selfChange
presence:error

proxy

The 'proxy' namespace allows for a secondary mode for making calls: proxy mode. When proxy mode is enabled, the SDK will redirect webRTC / media operations from the current machine to a remote machine using a channel. This is an advanced feature that enables support for Calls in particular scenarios that would otherwise not support them.

proxy
Types
Channel
Functions
setProxyMode(value)
getProxyMode()
getProxyDetails()
setChannel(channel)
initializeRemote(config)
Events
proxy:change
proxy:error

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. They can be provided during SDK instantiation to be used for all calls.

sdpHandlers
Example
import { create, sdpHandlers } from 'kandy';
const codecRemover = sdpHandlers.createCodecRemover(['VP8', 'VP9'])
const client = create({
  call: {
    sdpHandlers: [ <Your-SDP-Handler-Function>, ...]
  }
})
Functions
createCodecRemover(codecs)

sip

The 'sip' namespace allows a user to subscribe to, and receive notifications for, sip events.

SipEvents functions are all part of this namespace.

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