kandy-cpaas-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
config.subscription

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)
getUserInfo()
setTokens(params)
setCredentials(credentials)
getBrowserDetails()
Events
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
UserID
PhoneNumber
Functions
make(destination, media, options?)
reject(callId)
answer(callId, media, options?)
sendRingingFeedback(callId)
ignore(callId)
hold(callId)
unhold(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?)
replaceTrack(callId, trackId, media)
getAvailableCodecs(kind)
setSdpHandlers(sdpHandlers)
states
mediaConnectionStates
restartMedia(callId)
setDefaultDevices()
changeInputDevices()
changeSpeaker()
Events
call:operation
call:start
call:receive
call:stateChange
call:newMedia
call:removedMedia
call:newTrack
call:trackEnded
call:statsReceived
call:trackReplaced
call:availableCodecs
call:mediaConnectionChange
call:mediaRestart

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 for storing the conversations and its messages, and returning conversation objects when requested.

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

Available conversations can be retrieved using the conversation.get or conversation.getAll APIs.

Messaging functions are all part of the 'conversation' namespace. Ex: client.conversation.getAll

conversation
Types
chatTypes
Conversation
Part
Message
Functions
fetch(options?)
get(recipient, options?)
create(recipient, options?)
getAll()
Events
conversations:new
conversations:change
messages:change
messages:error
isTypingList:change

groups

The 'groups' namespace provides an interface for an application to create and manage Groups for a User. Groups are used in conjunction with the Messaging feature to allow for group conversations.

Groups are persisted by the server. When the SDK is initialized, there will be no Group information available, but the groups.fetch API is used to make available any Groups that were created previously.

The creator of a Group is the Group's administrator.

groups
Functions
create(params)
fetch()
getAll()
get(groupId)
getParticipants(groupId)
getInvitations()
leave(groupId)
acceptInvitation(groupId)
rejectInvitation(groupId)
addParticipant(groupId, participant)
removeParticipant(groupId, participant)
delete(groupId)
Events
group:new
group:change
group:delete
group:refresh
group:invitation_received
group: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

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)

services

The 'services' namespace allows an application to manage how they wish the SDK to receive communications from the platform. An application can subscribe to services in order to receive updates about that service for the current user. A feature generally requires a subscription for its service to be fully functional.

The services an application can subscribe to are based on the features included in the SDK. The list of available services can be retrieved using the services.getSubscriptions API. These values can be used with the services.subscribe API.

The channel used for subscriptions is the method for receiving the service updates. The recommended channel is websocket, where the SDK is able to handle receiving the updates internally. Alternate channel methods, if a websocket cannot be used, will be available in the future.

services
Types
ServiceDescriptor
SmsInboundServiceParams
Functions
subscribe(services, options?)
unsubscribe(services, type)
getSubscriptions()
Events
subscription:change
subscription:error
subscription:resub

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, options?)
Events
directory:change
directory:error
users:change
users:error