The Kandy JS SDK require this library:

<script src="https://kandy-portal.s3.amazonaws.com/public/javascript/kandy/2.12/kandy.js" ></script>

The library, kandy.js, includes the functions you will call to make voice and video calls, manage address books, send/receive instant messages, share data in group sessions, and more. A minified version of kandy.js, kandy.min.js, is available at:

<script src="https://kandy-portal.s3.amazonaws.com/public/javascript/kandy/2.12/kandy.js.min" ></script>

kandy

The kandy namespace contains functions for basic features of Kandy. This includes setting up Kandy, logging in/out,
and getter functions.


Properties

NameTypeDescription
versionStringreadonly. Current version of Kandy.

Methods

kandy.getDevices(userAccessToken, success, failure)

Retrieves devices associated with a user access token.

Parameters

NameTypeDescription
userAccessTokenStringUser Access Token.
successFunctionThe success callback. It receives one parameter.
success.devicesDevice[]An array of device objects.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the result object given to the success callback.


 {
     devices: [
         {
             id: "8E2C0E50D19A45FABCD9F70ABB93AF80",
             nativeID: "55555555555555",
             family: "portal",
             name: "portal",
             osVersion: "6.6.5",
             clientVersion: "1"
         },
         ...
     ]
 }

kandy.getLastSeen(users, success, failure)

Get last seen timestamps for the users passed in.

Parameters

NameTypeDescription
usersArrayArray of users.
successFunctionThe success callback. It receives one parameter.
success.resultObjectThe result object.
success.result.server_timestampNumberThe current server timestamp.
success.result.usersArrayThe array of users and their last seen times.
success.result.users.full_user_idStringThe user's full user ID.
success.result.users.last_seenNumberThe unix timestamp of the last time the user was seen.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the result object given to the success callback.


 {
     server_timestamp: 1442340323747,
     users: [
         {
             full_user_id: "user1@test.kandy.io",
             last_seen: 1442337579648
         },
         ...
     ]
 }

kandy.getLimitedUserDetails(userAccessToken, success, failure)

Retrieves details about a user for a specified user access token.

Parameters

NameTypeDescription
userAccessTokenString
successFunctionThe success callback. It receives one parameter.
success.userUserA User object corresponding to the provided user access token.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.getUserAccessToken(domainApiKey, userName, userPassword, success, failure, options)

Retrieves a user access token for a specified user.

Parameters

NameTypeDescription
domainApiKeyStringThe API key for the domain.
userNameStringThe name of the user.
userPasswordStringThe password of the user.
successFunctionThe success callback. It receives one parameter.
success.user_access_tokenStringThe user access token.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectClient information.
options.client_sw_versionStringSoftware version.
options.client_sw_typeStringSoftware type, 'JS/android/ios'.
options.kandy_device_idStringDevice ID.

kandy.getUserDetails  :  Object

Gets the details for the current user.


{
  fullUserId: "mistygreen@example.kandy.io",
  domainName: "example.kandy.io",
  userAccessToken: "UAT1bce9b65086c5de282f3fe28418dd347",
  email: "mistygreen@example.kandy.io",
  firstName: "Misty",
  lastName: "Green",
  userId: "mistygreen",
  devices: [
    clientVersion: "1",
    family: "portal",
    id: "49DE0134636142E585B0CC9F9BD7945F",
    name: "portal",
    nativeID: "55555555555555",
    osVersion: "6.6.6"
  ]
}

kandy.login(domainApiKey, userName, userPassword, success, failure)

Logs the user into Kandy.

Parameters

NameTypeDescription
domainApiKeyStringThe API key of the user's domain.
userNameStringThe name of the user.
userPasswordStringThe password for the user.
successFunctionThe success callback. It receives one parameter.
success.user_access_tokenStringThe logged-on user's access token.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.loginSSO(userAccessToken, success, failure, password)

Logs the user in with user access token (for single sign-on).

Parameters

NameTypeDescription
userAccessTokenStringUser access token
successFunctionThe success callback. It receives one parameter.
success.resultObjectUser details object.
success.result.user_idStringThe logged-on user's username.
success.result.full_user_idStringThe logged-on username(username@domain).
success.result.user_access_tokenStringThe logged-on user's user_access_token.
success.result.domain_nameStringThe logged-on user's domain name.
failureFunctionThe failure callback. It receives no parameters.
passwordStringThe user's password.

kandy.logout(success)

Logs the user out of Kandy.

Parameters

NameTypeDescription
successFunctionThe success callback. It receives no parameters.

kandy.off(type, listener)

Remove an event listener for a specific Kandy event.

Parameters

NameTypeDescription
typeStringThe event type for which to remove the listener.
listenerFunctionThe listener function to remove from the list of listeners.

kandy.on(type, listener)

Add an event listener for a specific Kandy event.

Parameters

NameTypeDescription
typeStringThe event type for which to register an event listener.
listenerFunctionThe listener function that will be called when the event is emitted with the parameters of the event.
listener....argumentsAnyThe arguments corresponding to the event beingw emitted.

kandy.setup(config)

Prepare Kandy for use; setup configurations and listeners.

Parameters

NameTypeDescription
configObjectConfiguration object used to set up Kandy.
config.remoteVideoContainerHTMLElementElement that will be used as the container to the video of the remote party in a video call.
config.localVideoContainerHTMLElementElement that will be used as the container to the video of the local party in a video call.
config.listenersObjectList of event listeners.
config.autoreconnectBooleanWhether Kandy should autoreconnect if connection is lost.
config.registerforcallsBooleanWhether the user should be registered for calls.
config.loglevelStringLog level to be set, ie. error/warn/info/debug.
config.screenSharingObjectScreensharing options.
config.screenSharing.chromeExtensionIdStringChrome extension ID for the extension to use to enable screen sharing. See the screensharing quickstart for more information.
config.enableAuthChallengeBooleanEnables authentication challenge events to allow the application to recover from an expired authentication token.

kandy.setup({
    remoteVideoContainer: document.getElementById('remote-video'),
    localVideoContainer: document.getElementById('local-video'),
    listeners: {
        callincoming: onCallIncoming
    },
    autoreconnect: true,
    registerforcalls: true,
    loglevel: 'debug'
});

function onCallIncoming(call) {...}

kandy.addressBook

The addressBook namespace contains functions to manage user’s address book as well as to provide search and retrieval
of the Kandy domain’s directory. The address book contains user contacts that can be shared between all the different
devices and Kandy apps.


Methods

kandy.addressBook.addToPersonalAddressBook(contact, success, failure)

Adds a contact to the user's personal address book.

Parameters

NameTypeDescription
contactContactThe contact to add to the address book.
successFunctionThe success callback. It receives one parameter.
success.contactContactThe contact that was added to the address book with it's newly generated contact_id.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.addressBook.removeFromPersonalAddressBook(contactId, success, failure)

Remove a contact from the user's personal address book.

Parameters

NameTypeDescription
contactIdStringThe contact id of the contact to remove.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.addressBook.retrieveDirectory(success, failure)

Retrieves the whole directory.

Parameters

NameTypeDescription
successFunctionThe success callback. It receives one parameter.
success.usersUser[]An array of all users in the directory.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.addressBook.retrievePersonalAddressBook(success, failure)

Retrieves all entries of the user's personal address book.

Parameters

NameTypeDescription
successFunctionThe success callback. It receives one parameter.
success.contactsContact[]An array of all contacts in the user's address book.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.addressBook.searchDirectory(searchString, success, failure)

Full text search of the directory. This will search the first name, last name, user id and phone number. The search is case-sensitive and can be partial.

Parameters

NameTypeDescription
searchStringStringThe string to search for.
successFunctionThe success callback. It receives one parameter.
success.usersUser[]An array of users that correspond to the search criteria.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.addressBook.searchDirectoryByName(name, success, failure)

Search the domain directory by name. The search will be done on both the first name and the last name.

Parameters

NameTypeDescription
nameStringThe name to search for. The name is case sensitive and can be a partial name.
successFunctionThe success callback. It receives one parameter.
success.usersUser[]An array of users that correspond to the search criteria.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.addressBook.searchDirectoryByPhoneNumber(phoneNumber, success, failure)

Search the domain directory by phone number.

Parameters

NameTypeDescription
phoneNumberStringThe phone number to search for. Can be a partial phone number.
successFunctionThe success callback. It receives one parameter.
success.usersUser[]An array of users that correspond to the search criteria.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.addressBook.searchDirectoryByUsername(username, success, failure)

Search the domain directory by username.

Parameters

NameTypeDescription
usernameStringUsername to search for.
successFunctionThe success callback. It receives one parameter.
success.usersUser[]An array of users that correspond to the search criteria.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.call

Kandy call is used to make calls (audio and video) from Kandy users to other Kandy
users, PSTN phones or SIP endpoints.


Properties

NameTypeDescription
mediaErrors{Object} Object with keys for each media error.All possible media errors.
callTypes{Object} Object with keys for each call type.All call types.
callEndReasons{Object} Object with keys for each call end reason.All possible reasons for a call ending.

Methods

kandy.call.answerCall(ID, cameraOn, options)

Answer an incoming call.

Parameters

NameTypeDescription
IDStringof call. This can be obtained by calling getId() on the call object passed to the callincoming event listener.
cameraOnBooleanWhen true, call will be answered with the user's video being sent to caller. Otherwise, the user's video will not be sent.
optionsObjectAdditional options to set for a call.
options.remoteVideoContainerHTMLElementThe container to use for remote video during the call. This is necessary, even for audio calls.
options.localVideoContainerHTMLElementThe container to use for local video during the call.
options.videoResolution.widthNumberThe width of the local video in pixels.
options.videoResolution.heightNumberThe height of the local video in pixels.
options.isAudioEnabledBooleanWhen false, audio negotiation will not be performed and microphone permissions will not be needed to answer the call.

kandy.call.callType(callId)   :  Number

Returns call type which is either incoming or outgoing.

Parameters

NameTypeDescription
callIdStringThe id of the call.

kandy.call.endCall(callId)

Ends a call.

Parameters

NameTypeDescription
callIdStringID of call. This can be obtained from calling getId() on the call object passed to either the callincoming or callinitiated event handlers.

kandy.call.getMediaStream(callId)   :  MediaStream

Retrieves the MediaStream object for a specified call.

Parameters

NameTypeDescription
callIdStringID of the call.

kandy.call.getNativeStats(callId, success, failure)

Retrieves WebRTC statistics about an on-going call. The stats retrived are the native RTCStatsReport objects as specified by WebRTC standards.

Parameters

NameTypeDescription
callIdStringId of the call to retrieve stats for.
successFunctionThe success callback. It receives one parameter.
success.statsArrayArray of RTCStatsReport objects.
failureFunctionThe failure callback. It receives one parameter.
failure.errorObjectFailure object with the error information.
failure.error.messageStringThe error message explaining what failed.

kandy.call.getStats(callId, success, failure)

Retrieves WebRTC statistics about an on-going call. The stats retrieved are a summary of the accumulated stats for the call.

Parameters

NameTypeDescription
callIdStringId of the call to retrieve stats for.
successFunctionThe success callback. It receives one parameter.
success.statsObjectStatistics object for the call.
success.stats.audioWebRTCStatsAudio statistics for the call.
success.stats.videoWebRTCStatsVideo statistics for the call.
failureFunctionThe failure callback. It receives one parameter.
failure.errorObjectFailure object with the error information.
failure.error.messageStringThe error message explaining what failed.

kandy.call.getStatsPeriodically(callId, statsInterval, success, failure)

Starts a timer to periodically retrieve WebRTC statistics about a call. The stats retrieved are a summary of the accumulated stats for the call.

Parameters

NameTypeDescription
callIdStringId of the call to retrieve stats for.
statsIntervalNumberThe time interval, in seconds, to retrieve stats.
successFunctionThe success callback. It receives one parameter.
success.statsObjectStatistics object for the call.
success.stats.audioWebRTCStatsAudio statistics for the call.
success.stats.videoWebRTCStatsVideo statistics for the call.
failureFunctionThe failure callback. It receives one parameter.
failure.errorObjectFailure object with the error information.
failure.error.messageStringThe error message explaining what failed.

kandy.call.holdCall(callId, success, failure)

Place a call on hold.

Parameters

NameTypeDescription
callIdStringID of call. This can be obtained from calling getId() on the call object received by either the callincoming or callinitiated event handler.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives no parameters.

kandy.call.ignoreCall(callId)

Ignore incoming call.

Parameters

NameTypeDescription
callIdStringID of call. This can be obtained from calling getId() on the call object received by the callincoming event handler.

kandy.call.initMedia(success, failure, force, options)

Check whether the browser has native WebRTC support or has the Kandy Plugin installed. If WebRTC is supported either by native support or via the plugin, the success callback will be called with no parameters. If no support is detected, the failure callback will be called with an error code. This function will be called automatically when making or receiving a call but you may want to call it sooner than that in case you need to direct your user to install the Kandy Plugin.

Parameters

NameTypeDescription
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorObjectError object describing error state.
failure.error.typeNumberError code corresponding to the reason WebRTC is not supported. Refer to mediaErrors for possible errors.
failure.error.urlWin32bitStringThe URL you can use to download the Kandy plugin for Windows 32bit.
failure.error.urlWin64bitStringThe URL you can use to download the Kandy plugin for Windows 64bit.
failure.error.urlMacUnixStringThe URL you can use to download the Kandy plugin for Mac.
forceBooleanForce a re-initialization of the media.
optionsObjectAdditional options to set for a call. This overrides `force` to be true.
options.remoteVideoContainerHTMLElementThe container to use for remote video during the call. This is necessary, even for audio calls.
options.localVideoContainerHTMLElementThe container to use for local video during the call.

kandy.call.isIncoming(callId)   :  Boolean

Returns true if the call is incoming and false otherwise.

Parameters

NameTypeDescription
callIdStringThe id of the call.

kandy.call.isMediaInitialized  :  Boolean

Returns true if media is initialized and false otherwise.

kandy.call.isOutgoing(callId)   :  Boolean

Returns true if call is outgoing and false otherwise.

Parameters

NameTypeDescription
callIdStringThe id of the call.

kandy.call.makeCall(fullUserId, cameraOn, callerId, options)

Make an IP call to another Kandy user

Parameters

NameTypeDescription
fullUserIdStringUsername of the intended callee.
cameraOnBooleanWhen true, the user's video will be sent to the callee. Otherwise, the user's video will not be sent.
callerIdStringCaller's identification as it should appear to callee
optionsObjectAdditional options to set for a call.
options.remoteVideoContainerHTMLElementThe container to use for remote video during the call. This is necessary, even for audio calls.
options.localVideoContainerHTMLElementThe container to use for local video during the call.
options.videoResolution.widthNumberThe width of the local video in pixels.
options.videoResolution.heightNumberThe height of the local video in pixels.
options.sendInitialVideoBooleanWhen true, video negotiation will be performed.
options.isAudioEnabledBooleanWhen false, audio negotiation will not be performed and microphone permissions will not be needed to make the call.

kandy.call.makePSTNCall(number, callerId, options)

Make a Public Switched Telephone Network (PSTN) call to a given PSTN phone number.

Parameters

NameTypeDescription
numberStringPSTN phone number to call. It must always be prefixed with its corresponding country code, e.g. 1 for the United States of America and Canada. The outbound International Direct Dialing (IDD) prefix must be omitted. For instance, a valid phone number would be "16131234567".
callerIdStringCaller's phone number as it should appear to callee.
optionsObjectAdditional options to set for a call.
options.remoteVideoContainerHTMLElementThe container to use for remote video during the call. This is necessary, even for audio calls.
options.sendInitialVideoBooleanWhen true, video negotiation will be performed and video permissions will be needed to make the call.

kandy.call.makeSIPCall(number, callerId, options)

Make a SIP trunk call to a given SIP phone number or SIP endpoint URI.

Parameters

NameTypeDescription
numberStringSIP phone number to call
callerIdStringCaller's phone number / username as it should appear to callee
optionsObjectAdditional options to set for a call.
options.remoteVideoContainerHTMLElementThe container to use for remote video during the call. This is necessary, even for audio calls.
options.localVideoContainerHTMLElementThe container to use for local video during the call.
options.sendInitialVideoBooleanWhen true, video negotiation will be performed and video permissions will be needed to make the call.

kandy.call.muteCall(callId)

Stop sending the user's audio to the other party on the call

Parameters

NameTypeDescription
callIdStringID of call. This can be obtained from calling getId() on the call object received by either the callincoming or callinitiated event handler.

kandy.call.rejectCall(callId)

Reject incoming call.

Parameters

NameTypeDescription
callIdStringID of call. This can be obtained from calling getId() on the call object received by the callincoming event handler.

kandy.call.sendDTMF(callId, tones)

Send a tone (Dual Tone Multi Frequency) in a PSTN call.

Parameters

NameTypeDescription
callIdStringID of call. This can be obtained from calling getId() on the call object passed to either the callincoming or callinitiated event handlers.
tonesStringTones to send.

kandy.call.startCallVideo(callId, success, failure)

Start sending the user's video to the other party on the call.

Parameters

NameTypeDescription
callIdStringID of call. This can be obtained from calling getId() on the call object received by either the callincoming or callinitiated event handler.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives no parameters.

kandy.call.startLocalVideo(videoContainer)

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

Parameters

NameTypeDescription
videoContainerHTMLElementThe container to use for local video.

 var container = document.getElementById('local-video');
 kandy.call.startLocalVideo(container);

kandy.call.startScreenSharing(callId, success, failure, options)

Start screen sharing for the specified call. If the call already has video, the screen sharing will replace the video. Note that a screensharing extension has to be present to enable this. See `kandy.setup` for more information.

Parameters

NameTypeDescription
callIdStringId of the call for which to start screen sharing.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorCodeNumberError code for the failure.
optionsObjectOptions for the screen sharing session.
options.widthNumberThe width of the screen to request.
options.heightNumberThe height of the screen to request.
options.frameRateNumberThe number of frames per second to request.

kandy.call.stopCallVideo(callId, success, failure)

Stop sending the user's video to the other party on the call

Parameters

NameTypeDescription
callIdStringID of call. This can be obtained from calling getId() on the call object received by either the callincoming or callinitiated event handler.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives no parameters.

kandy.call.stopLocalVideo

Stops the local video stream created in `startLocalVideo`.

kandy.call.stopPeriodicStats(callId)

Stops an interval for retrieving WebRTC statistics about a call.

Parameters

NameTypeDescription
callIdStringId of the call to retrieve stats for.

kandy.call.stopScreenSharing(callId, success, failure)

Stop screen sharing for the specified call. If the call is set to send video, then the screen sharing will stop and video will resume.

Parameters

NameTypeDescription
callIdStringId of call.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives no parameters.

kandy.call.unHoldCall(callId, success, failure)

Take a call off hold.

Parameters

NameTypeDescription
callIdStringID of call. This can be obtained from calling getId() on the call object received by either the callincoming or callinitiated event handler.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives no parameters.

kandy.call.unMuteCall(callId)

Start sending the user's audio to the other party on the call.

Parameters

NameTypeDescription
callIdStringID of call. This can be gotten from calling getId() on the call object received by either the callincoming or callinitiated event handler.

kandy.coBrowsing

CoBrowsing is used to share a webpage from one user to multiple users. Allows for a user to start and stop sending their webpage, and for users (called Agents herein) to start and stop receiving another user’s webpage. CoBrowsing requires the use of sessions for sending the webpage.


Methods

kandy.coBrowsing.startBrowsingAgent(session, container)

Starts listening for a user sending their webpage in the session. Displays the webpage in the specified container when received.

Parameters

NameTypeDescription
sessionStringThe session ID.
containerHTMLElementElement reference to be used for the agent's view.

kandy.coBrowsing.startBrowsingUser(session)

Starts sending current webpage to the session.

Parameters

NameTypeDescription
sessionStringThe session ID.

kandy.coBrowsing.stopBrowsingAgent

Stops listening for a webpage in the session. Clears the container used for viewing.

kandy.coBrowsing.stopBrowsingUser

Stops sending webpage to the session.


kandy.messaging

Kandy messaging is used to send and receive messages. Messages can be regular chat messages, SMS, files, audio, video, or images. Using messaging you can also manage messaging groups.


Methods

kandy.messaging.addGroupMembers(groupId, members, success, failure)

Add members to the group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
membersArrayThe list of new members to add to the group.
successFunctionThe success callback. It receives one parameter.
success.groupGroupThe updated group object.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the members parameter.


 [
     'user1@test.kandy.io',
     'user2@test.kandy.io'
 ]

kandy.messaging.buildFileThumbnailUrl(uuid, size)   :  String

Builds a Url to retrieve a thumbnail of a previously uploaded image file.

Parameters

NameTypeDescription
uuidStringUUID for file that you would receive in an instant message.
sizeStringThe size of the thumbnail. Values are "small", "medium" and "large". The Default is "large".

kandy.messaging.buildFileUrl(uuid)   :  String

Builds a url to retrieve a previously uploaded file.

Parameters

NameTypeDescription
uuidStringUUID for file that you would receive in an instant message.

kandy.messaging.createGroup(name, image, success, failure, progress)   :  Function

Creates a new group. The user that creates the group is designated as the group owner.

Parameters

NameTypeDescription
nameStringThe name of the group to create.
imageFileThe image file of the group to create.
successFunctionThe success callback. It receives one parameter.
success.groupGroupGroup object that was just created.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

kandy.messaging.deleteConversations(conversationIds, success, failure)

Deletes one or many conversations.

Parameters

NameTypeDescription
conversationIdsString[]A list of fully qualified usernames (e.g. user@domain.com) or group ids.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.messaging.deleteGroup(groupId, success, failure)

Delete a group with a given id. Only the group owner can delete a group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.messaging.deleteMessages(conversationId, messageIds, success, failure)

Deletes one or many messages.

Parameters

NameTypeDescription
conversationIdStringA fully qualified username (e.g. user@domain.com) or group id.
messageIdsString[]A list of message ids (e.g. `Message.UUID`) to delete.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.messaging.forwardMessage(destination, message, success, failure)   :  String

Forwards a message to another Kandy user.

Parameters

NameTypeDescription
destinationStringThe destination, can be a userId or a groupID.
messageMessageMessage to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorMessageStringThe error message explaining what failed.

Here is an example of a result given to the success function.


 {
     "UUID": "E72F1D02-5ED7-4E36-9938-78460ABD286B",
     "contentType": "text",
     "destination": "user1@test.kandy.io"
     "message": {
         "mimeType": "text/plain",
         "text": "this is the text to send"
     },
     "additionalData" {
         ...
     }
 }

kandy.messaging.getConversations(success, failure)

Get a list of conversations for the current user.

Parameters

NameTypeDescription
successFunctionThe success callback. It receives one parameter.
success.conversationsConversation[]An array of conversations.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.messaging.getGroupById(groupId, success, failure)

Gets group with a given group id.

Parameters

NameTypeDescription
groupIdStringThe group id to get group details.
successFunctionThe success callback. It receives one parameter.
success.groupGroupThe requested group object.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.messaging.getGroups(success, failure)

Gets the list of groups of which the current user is a part.

Parameters

NameTypeDescription
successFunctionThe success callback. It receives one parameter.
success.resultObjectObject containing list of groups.
success.result.groupsGroup[]An array of Group objects.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of a result given to the success function.


    {
        groups: [
            Group objects
        ]
 }

kandy.messaging.getIm(success, failure) deprecated

Use kandy.messaging.getConversations and kandy.messaging.getMessages instead.

Retrieves IM messages that were missed while offline. Please listen for the "message" event to receive messages while online.

Parameters

NameTypeDescription
successFunctionThe success callback. It receives one parameter.
success.messagesMessage[]An array of messages
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of a result given to the success function.


 [
     {
         "messageType":"chat",
         "sender":
         {
             "user_id":"972542205056",
             "domain_name":"domain.com",
             "full_user_id":"972542205056@domain.com"
          },
         "UUID":"acd2fa752c3c4edf97de8b0a48f622f0",
         "timestamp":"1400510413",
         "message":
         {
             "mimeType": "text/plain",
             "text": "let's meet tonight"
         }
     }
 ]

kandy.messaging.getMessages(conversationId, options, success, failure)

Get a list of messages from a specific conversation.

Parameters

NameTypeDescription
conversationIdStringThe identification for the conversation to retrieve. This can either be a fully-qualified username or a group id for group conversations.
optionsObjectFilter options to restrict the number of messages retrieved.
options.limitNumberThe maximum number of messages to retrieve.
options.startSequenceNumberThe sequence number from which to retrieve messages.
options.startTimestampNumberThe timestamp (in msec since the epoch) from which to retrieve messages.
options.orderStringThe order in which to retrieve the messages, can be `asc` for ascending or `desc` for descending.
successFunctionThe success callback. It receives one parameter.
success.messagesMessage[]An array of messages.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.messaging.leaveGroup(groupId, success, failure)

Leave a group with a given id. If the owner leaves the group, a group member is assigned as the new owner. If there are no group members when the owner leaves, the group is deleted.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.messaging.muteGroup(groupId, success, failure)

Mute a group with a given id.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
successFunctionThe success callback. It receives one parameter.
success.groupGroupThe updated group object.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.messaging.muteGroupMembers(groupId, members, success, failure)

Mutes group members.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
membersArrayThe list of members to mute in the group.
successFunctionThe success callback. It receives one parameter.
success.groupGroupThe updated group object.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the members parameter.


 [
     'user1@test.kandy.io',
     'user2@test.kandy.io'
 ]

kandy.messaging.removeGroupMembers(groupId, members, success, failure)

Removes members from the group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
membersArrayThe list of members to remove from the group.
successFunctionThe success callback. It receives one parameter.
success.groupGroupThe updated group object.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the members parameter.


 [
     'user1@test.kandy.io',
     'user2@test.kandy.io'
 ]

kandy.messaging.sendGroupIm(groupId, text, success, failure, options)   :  Function

Sends a message to all the members in the group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
textStringThe message to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.

kandy.messaging.sendGroupImWithAudio(groupId, file, success, failure, options, progress)   :  Function

Sends an audio file to all the members in the group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
fileFileThe audio file object to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

kandy.messaging.sendGroupImWithContact(groupId, vCard, success, failure, options, progress)   :  Function

Sends a contact file to all the members in the group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
vCardFileThe contact file object to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

kandy.messaging.sendGroupImWithFile(groupId, file, success, failure, options, progress)   :  Function

Sends a file to all the members in the group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
fileFileThe file object to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

kandy.messaging.sendGroupImWithImage(groupId, file, success, failure, options, progress)   :  Function

Sends an image to all the members in the group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
fileFileThe image file object to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

kandy.messaging.sendGroupImWithLocation(groupId, location, success, failure, options)   :  String

Sends a location object to all the members in the group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
locationObjectThe location object to send.
location.longitudeStringLocation's longitude
location.latitudeStringLocation's latitude
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.

kandy.messaging.sendGroupImWithVideo(groupId, file, success, failure, options, progress)   :  Function

Sends a video file to all the members in the group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
fileFileThe video file object to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

kandy.messaging.sendGroupJSON(groupId, object, success, failure, options)   :  String

Sends a JSON object to all the members in the group.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
objectObjectThe JSON object to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.

kandy.messaging.sendIm(fullUserId, message, success, failure, options)   :  String

Sends an instant message to another Kandy user.

Parameters

NameTypeDescription
fullUserIdStringUsername of the intended recipient.
messageStringMessage to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.

Here is an example of a result given to the success function.


 {
     "UUID": "E72F1D02-5ED7-4E36-9938-78460ABD286B",
     "contentType": "text",
     "destination": "user1@test.kandy.io"
     "message": {
         "mimeType": "text/plain",
         "text": "this is the text to send"
     },
     "additionalData" {
         ...
     }
 }

kandy.messaging.sendImWithAudio(fullUserId, file, success, failure, options, progress)   :  Function

Sends an audio file via instant message.

Parameters

NameTypeDescription
fullUserIdStringFull user Id of the intended recipient.
fileFileAudio file to be sent
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

Here is an example of a result given to the success function.


 {
     "UUID": "E72F1D02-5ED7-4E36-9938-78460ABD286B",
     "contentType": "audio",
     "destination": "user1@test.kandy.io"
     "message": {
         content_name: "audio_file.mp3",
         content_uuid: "738814CB-1019-4482-9200-56CB3FA033D9",
         mimeType: "audio/mp3"
     },
     "additionalData" {
         ...
     }
 }

kandy.messaging.sendImWithContact(fullUserId, vCard, success, failure, options, progress)   :  Function

Sends a contact object via instant message.

Parameters

NameTypeDescription
fullUserIdStringFull user Id of the intended recipient.
vCardFileContact object to be sent
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.
options.contact_display_nameObjectContact name sent alongside vCard file.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

Here is an example of a result given to the success function.


 {
     "UUID": "E72F1D02-5ED7-4E36-9938-78460ABD286B",
     "contentType": "contact",
     "destination": "user1@test.kandy.io"
     "message": {
         contact_display_name: "Example Contact Name",
         content_name: "contact_file.vcf",
         content_uuid: "738814CB-1019-4482-9200-56CB3FA033D9",
         mimeType: "text-vcard"
     },
     "additionalData" {
         ...
     }
 }

kandy.messaging.sendImWithFile(fullUserId, file, success, failure, options, progress)   :  Function

Sends a File via instant message.

Parameters

NameTypeDescription
fullUserIdStringFull user Id of the intended recipient.
fileFileFile object to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

Here is an example of a result given to the success function.


 {
     "UUID": "E72F1D02-5ED7-4E36-9938-78460ABD286B",
     "contentType": "file",
     "destination": "user1@test.kandy.io"
     "message": {
         mimeType: "application/pdf",
         content_name: "file.pdf",
         content_uuid: "738814CB-1019-4482-9200-56CB3FA033D9"
     },
     "additionalData" {
         ...
     }
 }

kandy.messaging.sendImWithImage(fullUserId, file, success, failure, options, progress)   :  Function

Sends an image file via instant message.

Parameters

NameTypeDescription
fullUserIdStringFull user Id of the intended recipient.
fileFileImage file to be sent
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

Here is an example of a result given to the success function.


 {
     "UUID": "E72F1D02-5ED7-4E36-9938-78460ABD286B",
     "contentType": "image",
     "destination": "user1@test.kandy.io"
     "message": {
         content_name: "image.jpg",
         content_uuid: "738814CB-1019-4482-9200-56CB3FA033D9",
         mimeType: "image/jpeg"
     },
     "additionalData" {
         ...
     }
 }

kandy.messaging.sendImWithLocation(fullUserId, location, success, failure, options)   :  String

Sends a location object via instant message.

Parameters

NameTypeDescription
fullUserIdStringFull user Id of the intended recipient.
locationObjectLocation object to be sent
location.longitudeStringLocation's longitude
location.latitudeStringLocation's latitude
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.

Here is an example of a result given to the success function.


 {
     "UUID": "E72F1D02-5ED7-4E36-9938-78460ABD286B",
     "contentType": "location",
     "destination": "user1@test.kandy.io
     "message": {
         locationLongitude: "45.298834",
         locationLatitude: "-75.913328",
         mimeType: "location/utm"
     },
     "additionalData" {
         ...
     }
 }

kandy.messaging.sendImWithVideo(fullUserId, file, success, failure, options, progress)   :  Function

Sends an video file via instant message.

Parameters

NameTypeDescription
fullUserIdStringFull user Id of the intended recipient.
fileObjectVideo file to be sent
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

Here is an example of a result given to the success function.


 {
     "UUID": "E72F1D02-5ED7-4E36-9938-78460ABD286B",
     "contentType": "video",
     "destination": "user1@test.kandy.io"
     "message": {
         content_name: "video_file.avi",
         content_uuid: "738814CB-1019-4482-9200-56CB3FA033D9",
         mimeType: "video/avi"
     },
     "additionalData" {
         ...
     }
 }

kandy.messaging.sendJSON(fullUserId, object, success, failure, options)   :  String

Sends arbitrary JSON object via instant message.

Parameters

NameTypeDescription
fullUserIdStringFull user Id of the intended recipient.
objectObjectArbitrary JSON object to send.
successFunctionThe success callback. It receives one parameter.
success.messageMessageThe message that was sent.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
optionsObjectObject of options for the message.
options.additionalDataObjectObject with arbitrary metadata about the IM.

Here is an example of a result given to the success function.


 {
     "UUID": "E72F1D02-5ED7-4E36-9938-78460ABD286B",
     "contentType": "text",
     "destination": "user1@test.kandy.io"
     "message": {
         mimeType: "application/json",
         json: "{"key":"value"}"
     },
     "additionalData" {
         ...
     }
 }

kandy.messaging.sendSMS(number, sender, text, success, failure)

Sends an SMS message.

Parameters

NameTypeDescription
numberStringPhone number to which SMS message will be sent. It must always be prefixed with its corresponding country code, e.g. 1 for the United States of America and Canada. The outbound International Direct Dialing (IDD) prefix must be omitted. For instance, a valid phone number would be "16131234567".
senderStringA description of the sender (could be name or phone number).
textStringText of message to send.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.messaging.unmuteGroup(groupId, success, failure)

Unmute a group with a given id.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
successFunctionThe success callback. It receives one parameter.
success.groupGroupThe updated group object.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.messaging.unmuteGroupMembers(groupId, members, success, failure)

Unmutes group members.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
membersArrayThe list of members to unmute in the group.
successFunctionThe success callback. It receives one parameter.
success.groupGroupThe updated group object.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the members parameter.


 [
     'user1@test.kandy.io',
     'user2@test.kandy.io'
 ]

kandy.messaging.updateGroup(groupId, name, image, success, failure, progress)

Update group with new information.

Parameters

NameTypeDescription
groupIdStringThe id of the group.
nameStringThe name of the group.
imageFileThe image file of the group.
successFunctionThe success callback. It receives one parameter.
success.groupGroupThe updated group object.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.
progressFunctionThe progress callback. Triggers periodically as the file is uploaded.
progress.nameStringThe name of the file being uploaded.
progress.totalNumberThe total size of the file being uploaded (in bytes).
progress.loadedNumberThe amount of the file that has uploaded so far (in bytes).

kandy.session

The Session namespace provides functionality for using sessions. It allows for creation and management of a session,
retrieval of information about sessions, user management for a session, and sending data over the session.


Methods

kandy.session.acceptJoinRequest(sessionId, fullUserId, success, failure)

Accepts a join request for a session. Only the session administrator can accept join requests.

Parameters

NameTypeDescription
sessionIdStringId of session the user is requesting to join.
fullUserIdStringFull user Id of the user sending the join request.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.session.activate(sessionId, success, failure)

Activates an existing session, allowing for data to be sent to all users. Only the session administrator can activate the session.

Parameters

NameTypeDescription
sessionIdStringId of the session to be activated.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.session.bootUser(sessionId, fullUserId, bootReason, success, failure)

Removes a user from the session. Only the session administrator can boot a user.

Parameters

NameTypeDescription
sessionIdStringSession Id of the session the user should be removed from.
fullUserIdStringFull user Id of the user to be removed.
bootReasonStringReason for removing the user.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.session.create(sessionConfig, success, failure)

Creates a session using specified configurations. The user that creates a session is the session administrator. A newly created session is inactive by default.

Parameters

NameTypeDescription
sessionConfigObjectConfiguration object used for creating the session.
sessionConfig.session_typeStringType of session to be created. Session type is not restricted in its value; it can be defined as need be.
sessionConfig.session_nameStringName of the session to be created.
sessionConfig.session_descriptionStringDescription of the session to be created.
sessionConfig.user_nicknameStringNickname of the user creating the session.
sessionConfig.user_first_nameStringFirst name of the user creating the session.
sessionConfig.user_last_nameStringLast name of the user creating the session.
sessionConfig.user_phone_numberStringPhone number of the user creating the session.
sessionConfig.user_emailStringEmail of the user creating the session.
successFunctionThe success callback. It receives one parameter.
success.resultObjectThe result object.
success.result.session_idStringThe session ID of the created session.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.session.getOpenSessions(success, failure)

Gets a list of all open sessions.

Parameters

NameTypeDescription
successFunctionThe success callback. It receives one parameter.
success.resultObjectInformation about the session.
success.result.sessionsArrayThe list of sessions.
success.result.sessions.session_idStringThe session ID.
success.result.sessions.session_nameStringThe name of the session.
success.result.sessions.session_statusStringThe status of the session.
success.result.sessions.session_typeStringThe type of the session.
success.result.sessions.session_descriptionStringThe description of the session.
success.result.sessions.admin_full_user_idStringThe full user ID of the admin of the session.
success.result.sessions.creation_timestampNumberThe time at which the session was created.
success.result.sessions.domain_nameStringThe domain name of the session.
success.result.sessions.expiry_timestampNumberThe expiry time of the session.
success.result.sessions.participantsArrayThe list of participants in the session.
success.result.sessions.participants.full_user_idArrayThe full user ID of the participant.
success.result.sessions.participants.profileArrayThe profile of the participant.
success.result.sessions.participants.statusArrayThe status of the participant.
success.result.sessions.participants.typeArrayThe type of the participant.
success.result.sessions.participants.statusArrayThe status of the participant.
success.result.sessions.participants.user_emailArrayThe email of the participant.
success.result.sessions.participants.user_first_nameArrayThe first name of the participant.
success.result.sessions.participants.user_last_nameArrayThe last name of the participant.
success.result.sessions.participants.user_nicknameArrayThe nickname of the participant.
success.result.sessions.participants.user_phone_numberArrayThe phone number of the participant.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the result.


 {
     sessions: [
         {
             session_id: "70efdb80a067439481f7dbfb99619a78",
             session_name: "Session Name",
             session_status: "inactive",
             session_type: "Sesstion Type",
             session_description: "A description of the session",
             admin_full_user_id: "user1@test.kandy.io",
             creation_timestamp: 1440598570170,
             domain_name: "test.kandy.io",
             expiry_timestamp: 981003600000,
             participants: [
                 {
                     full_user_id: "user1@test.kandy.io",
                     profile: "registered",
                     status: "approved",
                     type: "admin",
                     user_email: "user1@test.kandy.io",
                     user_first_name: "User",
                     user_last_name: "One",
                     user_nickname: "Onesie",
                     user_phone_number: "1111111111"
                 },
                 ...
             ]
         }
     ]
}

kandy.session.getOpenSessionsByType(sessionType, success, failure)

Gets a list of open sessions with a given session type.

Parameters

NameTypeDescription
sessionTypeStringType of session for which to search.
successFunctionThe success callback. It receives one parameter.
success.resultObjectInformation about the session.
success.result.sessionsArrayThe list of sessions.
success.result.sessions.session_idStringThe session ID.
success.result.sessions.session_nameStringThe name of the session.
success.result.sessions.session_statusStringThe status of the session.
success.result.sessions.session_typeStringThe type of the session.
success.result.sessions.session_descriptionStringThe description of the session.
success.result.sessions.admin_full_user_idStringThe full user ID of the admin of the session.
success.result.sessions.creation_timestampNumberThe time at which the session was created.
success.result.sessions.domain_nameStringThe domain name of the session.
success.result.sessions.expiry_timestampNumberThe expiry time of the session.
success.result.sessions.participantsArrayThe list of participants in the session.
success.result.sessions.participants.full_user_idArrayThe full user ID of the participant.
success.result.sessions.participants.profileArrayThe profile of the participant.
success.result.sessions.participants.statusArrayThe status of the participant.
success.result.sessions.participants.typeArrayThe type of the participant.
success.result.sessions.participants.statusArrayThe status of the participant.
success.result.sessions.participants.user_emailArrayThe email of the participant.
success.result.sessions.participants.user_first_nameArrayThe first name of the participant.
success.result.sessions.participants.user_last_nameArrayThe last name of the participant.
success.result.sessions.participants.user_nicknameArrayThe nickname of the participant.
success.result.sessions.participants.user_phone_numberArrayThe phone number of the participant.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the result.


 {
     sessions: [
         {
             session_id: "70efdb80a067439481f7dbfb99619a78",
             session_name: "Session Name",
             session_status: "inactive",
             session_type: "Sesstion Type",
             session_description: "A description of the session",
             admin_full_user_id: "user1@test.kandy.io",
             creation_timestamp: 1440598570170,
             domain_name: "test.kandy.io",
             expiry_timestamp: 981003600000,
             participants: [
                 {
                     full_user_id: "user1@test.kandy.io",
                     profile: "registered",
                     status: "approved",
                     type: "admin",
                     user_email: "user1@test.kandy.io",
                     user_first_name: "User",
                     user_last_name: "One",
                     user_nickname: "Onesie",
                     user_phone_number: "1111111111"
                 },
                 ...
             ]
         }
     ]
}

kandy.session.getOpenSessionsCreatedByUser(success, failure)

Gets a list of sessions created by the current user.

Parameters

NameTypeDescription
successFunctionThe success callback. It receives one parameter.
success.resultObjectInformation about the session.
success.result.sessionsArrayThe list of sessions.
success.result.sessions.session_idStringThe session ID.
success.result.sessions.session_nameStringThe name of the session.
success.result.sessions.session_statusStringThe status of the session.
success.result.sessions.session_typeStringThe type of the session.
success.result.sessions.session_descriptionStringThe description of the session.
success.result.sessions.admin_full_user_idStringThe full user ID of the admin of the session.
success.result.sessions.creation_timestampNumberThe time at which the session was created.
success.result.sessions.domain_nameStringThe domain name of the session.
success.result.sessions.expiry_timestampNumberThe expiry time of the session.
success.result.sessions.participantsArrayThe list of participants in the session.
success.result.sessions.participants.full_user_idArrayThe full user ID of the participant.
success.result.sessions.participants.profileArrayThe profile of the participant.
success.result.sessions.participants.statusArrayThe status of the participant.
success.result.sessions.participants.typeArrayThe type of the participant.
success.result.sessions.participants.statusArrayThe status of the participant.
success.result.sessions.participants.user_emailArrayThe email of the participant.
success.result.sessions.participants.user_first_nameArrayThe first name of the participant.
success.result.sessions.participants.user_last_nameArrayThe last name of the participant.
success.result.sessions.participants.user_nicknameArrayThe nickname of the participant.
success.result.sessions.participants.user_phone_numberArrayThe phone number of the participant.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the result.


 {
     sessions: [
         {
             session_id: "70efdb80a067439481f7dbfb99619a78",
             session_name: "Session Name",
             session_status: "inactive",
             session_type: "Sesstion Type",
             session_description: "A description of the session",
             admin_full_user_id: "user1@test.kandy.io",
             creation_timestamp: 1440598570170,
             domain_name: "test.kandy.io",
             expiry_timestamp: 981003600000,
             participants: [
                 {
                     full_user_id: "user1@test.kandy.io",
                     profile: "registered",
                     status: "approved",
                     type: "admin",
                     user_email: "user1@test.kandy.io",
                     user_first_name: "User",
                     user_last_name: "One",
                     user_nickname: "Onesie",
                     user_phone_number: "1111111111"
                 },
                 ...
             ]
         }
     ]
}

kandy.session.getSessionInfoById(sessionId, success, failure)

Gets session details for a given session Id.

Parameters

NameTypeDescription
sessionIdStringId of session for which to get info.
successFunctionThe success callback. It receives one parameter.
success.resultObjectInformation about the session.
success.result.session_idStringThe session ID.
success.result.session_nameStringThe name of the session.
success.result.session_statusStringThe status of the session.
success.result.session_typeStringThe type of the session.
success.result.session_descriptionStringThe description of the session.
success.result.admin_full_user_idStringThe full user ID of the admin of the session.
success.result.creation_timestampNumberThe time at which the session was created.
success.result.domain_nameStringThe domain name of the session.
success.result.expiry_timestampNumberThe expiry time of the session.
success.result.participantsArrayThe list of participants in the session.
success.result.participants.full_user_idArrayThe full user ID of the participant.
success.result.participants.profileArrayThe profile of the participant.
success.result.participants.statusArrayThe status of the participant.
success.result.participants.typeArrayThe type of the participant.
success.result.participants.statusArrayThe status of the participant.
success.result.participants.user_emailArrayThe email of the participant.
success.result.participants.user_first_nameArrayThe first name of the participant.
success.result.participants.user_last_nameArrayThe last name of the participant.
success.result.participants.user_nicknameArrayThe nickname of the participant.
success.result.participants.user_phone_numberArrayThe phone number of the participant.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the result.


 {
     session_id: "70efdb80a067439481f7dbfb99619a78",
     session_name: "Session Name",
     session_status: "inactive",
     session_type: "Sesstion Type",
     session_description: "A description of the session",
     admin_full_user_id: "user1@test.kandy.io",
     creation_timestamp: 1440598570170,
     domain_name: "test.kandy.io",
     expiry_timestamp: 981003600000,
     participants: [
         {
             full_user_id: "user1@test.kandy.io",
             profile: "registered",
             status: "approved",
             type: "admin",
             user_email: "user1@test.kandy.io",
             user_first_name: "User",
             user_last_name: "One",
             user_nickname: "Onesie",
             user_phone_number: "1111111111"
         },
         ...
     ]
 }

kandy.session.getSessionInfoByName(sessionName, success, failure)

Gets session details with a given a session name.

Parameters

NameTypeDescription
sessionNameStringName of session for which to get info.
successFunctionThe success callback. It receives one parameter.
success.resultObjectInformation about the session.
success.result.session_idStringThe session ID.
success.result.session_nameStringThe name of the session.
success.result.session_statusStringThe status of the session.
success.result.session_typeStringThe type of the session.
success.result.session_descriptionStringThe description of the session.
success.result.admin_full_user_idStringThe full user ID of the admin of the session.
success.result.creation_timestampNumberThe time at which the session was created.
success.result.domain_nameStringThe domain name of the session.
success.result.expiry_timestampNumberThe expiry time of the session.
success.result.participantsArrayThe list of participants in the session.
success.result.participants.full_user_idArrayThe full user ID of the participant.
success.result.participants.profileArrayThe profile of the participant.
success.result.participants.statusArrayThe status of the participant.
success.result.participants.typeArrayThe type of the participant.
success.result.participants.statusArrayThe status of the participant.
success.result.participants.user_emailArrayThe email of the participant.
success.result.participants.user_first_nameArrayThe first name of the participant.
success.result.participants.user_last_nameArrayThe last name of the participant.
success.result.participants.user_nicknameArrayThe nickname of the participant.
success.result.participants.user_phone_numberArrayThe phone number of the participant.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Here is an example of the result.


 {
     session_id: "70efdb80a067439481f7dbfb99619a78",
     session_name: "Session Name",
     session_status: "inactive",
     session_type: "Sesstion Type",
     session_description: "A description of the session",
     admin_full_user_id: "user1@test.kandy.io",
     creation_timestamp: 1440598570170,
     domain_name: "test.kandy.io",
     expiry_timestamp: 981003600000,
     participants: [
         {
             full_user_id: "user1@test.kandy.io",
             profile: "registered",
             status: "approved",
             type: "admin",
             user_email: "user1@test.kandy.io",
             user_first_name: "User",
             user_last_name: "One",
             user_nickname: "Onesie",
             user_phone_number: "1111111111"
         },
         ...
     ]
 }

kandy.session.inactivate(sessionId, success, failure)

Inactivates an existing session, preventing data being sent to all users. Only the session administrator can inactivate the session.

Parameters

NameTypeDescription
sessionIdStringId of the session to be activated.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.session.join(sessionId, userInfo, success, failure)

Requests permission from the session administrator to join a session with a given Id.

Parameters

NameTypeDescription
sessionIdStringId of the session to requeset to join.
userInfoObjectExtra, optional, user info that will be visisble in session information.
userInfo.user_emailStringThe user's email.
userInfo.user_first_nameStringThe user's first name.
userInfo.user_last_nameStringThe user's last name.
userInfo.user_nicknameStringThe user's nickname.
userInfo.user_phone_numberStringThe user's phone number.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.session.leave(sessionId, leaveReason, success, failure)

Removes the current user from a session.

Parameters

NameTypeDescription
sessionIdStringId of the session to leave.
leaveReasonStringReason why we are leaving the session.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.session.rejectJoinRequest(sessionId, Full, rejectReason, success, failure)

Rejects a join request for a session. Only the session administrator can reject join requests.

Parameters

NameTypeDescription
sessionIdStringSession Id of the join request.
FullStringuser Id of the user sending the join request.
rejectReasonStringReason for rejecting the join request.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

kandy.session.sendData(sessionId, data, success, failure, destination)

Sends data to session users. Requires the session to be active.

Parameters

NameTypeDescription
sessionIdStringId of session to send data through.
dataObjectData to be sent to the session users.
successFunctionsuccess Function called when the data is sent successfully.
failureFunctionfailure Function called when an error occurs while sending data.
destinationStringFull user id for the destination (if none provided, sends to all users).

kandy.session.setListeners(sessionId, listeners)

Registers listeners for events.

Parameters

NameTypeDescription
sessionIdStringId of the session to listen on.
listenersObjectSet of listeners be to set up.
listeners.onDataFunctionFired when a participant sends data with sendData().
listeners.onActiveFunctionFired when a session is activated.
listeners.onUserJoinRequestFunctionFired when a participant sends a join request for a session.
listeners.onUserJoinFunctionFired when a participant joins a session.
listeners.onJoinApproveFunctionFired when a participant's join request has been approved.
listeners.onJoinRejectFunctionFired when a participant's join request has been rejected.
listeners.onUserLeaveFunctionFired when a participant leaves a session.
listeners.onUserBootFunctionFired when a participant is booted by an admin.
listeners.onBootFunctionFired when a participant is booted by an admin.
listeners.onInactiveFunctionFired when a session is inactivated.
listeners.onTerminationFunctionFired when a session is terminated.

    var sessionId = "b39ba65691af47bba43c6e19b6d334d3";
    kandy.session.setListeners(sessionId, {
        onData: function(data) {...}
    });

kandy.session.terminate(sessionId, success, failure)

Terminates an existing session. Only the session administrator can terminate the session.

Parameters

NameTypeDescription
sessionIdStringId of session to delete.
successFunctionThe success callback. It receives no parameters.
failureFunctionThe failure callback. It receives one parameter.
failure.errorFailureErrorObject containing information about the failure.

Call

The call interface contains information about a call. It is used only during call events.


Properties

NameTypeDescription
calleeNumberStringThe username or number of the callee for the call.
callerNameStringCaller first and last name of the call.
callerNumberStringThe number or full user id (username@domainname.com) of the caller for the call.
isRemotePSTNBooleanFlag for whether the remote side of an incoming call is PSTN.

Methods

getId()

Returns the id of the call.

Returns: String (Id of the call.)

getRemoteVideoState()

Returns a string that corresponds to the remote video state.

Returns: String (Can be "sendrecv", "sendonly", "recvonly", "inactive" or "notfound")


Contact

The Contact interface represents a contact stored in a user’s personal address book. Note that
a contact does not have any formal references to a Kandy user. An application can manage such a reference
by using one of the fields provided, or add new fields as needed.


Properties

NameTypeDescription
contact_idreadonly. The id of the contact. This is a read-only property generated by Kandy.
nameStringoptional. The name of the contact.
nicknameStringoptional. The nickname of the contact.
firstNameStringoptional. The first name of the contact.
lastNameStringoptional. The last name of the contact.
emailStringoptional. The email of the contact.
homePhoneStringoptional. The home phone number of the contact.
businessPhoneStringoptional. The business phone number of the contact.
mobilePhoneStringoptional. The mobile phone number of the contact.
faxStringoptional. The fax number of the contact.

Device

Interface representing a device.


Properties

NameTypeDescription
idStringThe device's id.
nativeIDStringThe device's native id.
familyStringThe device's family.
nameStringThe device's name.
osVersionStringThe device's OS version.
clientVersionStringThe device's client version.

FailureError

The Failure Error interface describes the error returned from a “failure” callback.


Properties

NameTypeDescription
messageStringThe textual message of the error that occured.
errorCodeNumberThe error's code.

Group

The group interface represents a group that can contain one or many users. Users can join and leave
groups in order to send and receive messages posted to the group for all members to see. The
creator of the group is the admin and they can do things like add group members or mute them.


Properties

NameTypeDescription
group_idStringreadonly. The id of the group. This is a read-only property generated by Kandy.
group_nameStringoptional. The name of the group assigned or updated by the creator.
group_imageStringoptional. The image of the group assigned or updated by the creator.
max_membersNumberoptional. The maximum number of members allowed to join the group.
ownersoptional. An array of member objects for members who are owners of the group.
creation_timeoptional. A unix timestamp of the time the date and time the group was created.
membersMember[]optional. An array of member objects corresponding to the members in the group.
mutedoptional. A boolean property that is true when the group is muted and false otherwise. When a group is muted, none of its members can send messages.

Member

The Member interface represents a user who is part of a group.


Properties

NameTypeDescription
full_user_idStringreadonly. The user id for the member.
mutedBooleanoptional. A boolean property that is true when the member is muted and false otherwise. Muted members cannot send messages.

Message

The Message interface represents a message between 2 targets including envelope and metadata information.


Properties

NameTypeDescription
UUIDStringThe unique id of the message.
contentTypeStringThe type of content for this message. Can be one of: 'text', 'file', 'video', 'audio', 'image', 'location', 'contact'
destinationStringThe destination of the message as a fully qualified username. This field is only used for personal chat or SMS messages.
group_idStringThe id of the group this message belongs to. This field is only used for group chat event messages.
group_nameStringThe name of the group. This field is only used for group chat event messages.
inviterStringThe user that is inviting other users. This field is only used for `chatGroupInvite` event messages.
inviteesString[]The users being invited to a group chat. This field is only used for `chatGroupInvite` event messages. This is an array of full user ids.
booterStringThe user that is booting other users. This field is only used for `chatGroupBoot` event messages.
bootedString[]The users being removed from a group chat. This field is only used for `chatGroupBoot` event messages. This is an array of full user ids.
updaterStringThe user updating the group chat. This field is only used for `chatGroupUpdate` event messages.
eraserStringThe user deleting the group chat. This field is only used for `chatGroupDelete` event messages.
messageTypeStringThe type of message that this represents. Can be one of: - chat: Personal chat message. - groupChat: Group chat message. - chatGroupInvite: All chat members receive the chatGroupInvite event message when someone is invited. - chatGroupBoot: All chat member recieve the chatGroupBoot event message when someone is booted. - chatGroupLeave: All chat members receive the chatGroupLeave event message when someone leaves the group. - chatGroupUpdate: All chat members receive the chatGroupUpdate event message when someone updates the group via updateGroup(). - chatGroupDelete: All chat members receive the chatGroupDelete event message when the group is deleted. - chatRemoteAck: The sender of a message receives the chatRemoteAck event message when the message was acknowledged.
senderMessageSenderThe sender of a message.
timestampnumberA timestamp that represents the time that the message was sent in milliseconds since the unix epoch time.
scnnumberA sequence number that represents the order in which this message was sent compared to other messages within the same conversation.
messageMessagePayloadThe payload of the message.

MessagePayload

Describes the payload of a message. Note that some fields are only used with certain
content types.


Properties

NameTypeDescription
textStringThe text sent with the message. Used only for the 'text' content type.
mimeTypeStringThe mime type of the message payload.
content_nameStringDescribes the name of a file that is attached with this message. Used for 'file', 'video', 'audio', 'image' and 'contact' content types.
content_uuidStringThe unique identifier of a file that is attached with this message. This id can be used to retrieve the file with `kandy.messaging.buildFileUrl` and `kandy.messaging.buildFileThumbnailUrl`.Used for 'file', 'video', 'audio', 'image' and 'contact' content types.
contact_display_nameStringDisplay name for a sent contact. Only used for the 'contact' content type.
locationLongitudeStringLongitude coordinate of a sent location. Only used for 'location' content type.
locationLatitudeStringLatitude coordinate of a sent location. Only used for 'location' content type.

MessageSender

Describes the sender of a message


Properties

NameTypeDescription
domain_nameStringDomain name of the sender.
user_idStringSimple username of the sender.
full_user_idStringFull user id of the sender.

User

The User interface represents a user and it’s properties. It is used as part of the address book APIs.


Properties

NameTypeDescription
user_idStringThe user id without the domain (e.g. "john.smith").
domain_nameStringThe user's domain name.
full_user_idStringThe user's full user id including the domain (e.g. "john.smith@domain.com")
user_first_nameStringThe user's first name.
user_last_nameStringThe user's last name.
user_emailStringThe user's email.
user_phone_numberStringThe user's phone number.

WebRTCStats

The WebRTCStats interface represents statistics for a WebRTC call. The statistics are either for the audio or video of the call.


Properties

NameTypeDescription
bytesReceivedNumberThe number of bytes received so far for the call.
bytesSentNumberThe number of bytes sent so far for the call.
codecStringThe codec used for this media type of the call.
jitterStringPacket jitter measured in seconds. In audio stats only.
packetsLostNumberNumber of packets lost so far for the call.
packetsSentNumberNumber of packets sent so far for the call.
peerAddressStringAddress of the connected peer for the call.
rttStringThe round trip time computed by the STUN connectivity checks.

kandy


kandy.authChallenge

Fired when an authentication token becomes expired and provides a chance to the application to retry the failed request by providing a new user access token.

Parameters

NameTypeDescription
retryFunctionA retry function that allows the user to specify a new user access token and retry the request.
cancelFunctionCancel the challenge and fail the original request that triggered the challenge with the original error.

kandy.callAnswerFailed

Fired when answering an incoming call fails.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.callAnswered

Fired when a call is answered.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.callEndFailed

Fired when a call fails to end.

Parameters

NameTypeDescription
callCallCurrent active call.
errorCodeStringError code of the reason for the failure.

kandy.callEnded

Fired when an outgoing or incoming call has ended.

Parameters

NameTypeDescription
callCallThe call object that was ended.
dataObjectThe data about the event.

kandy.callEstablished

Fired when a call has been established.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.callHold

Fired when the remote party puts the call on hold.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.callIgnoreFailed

Fired when an incoming call ignore fails.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.callIgnored

Fired when an incoming call is ignored.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.callIncoming

Fired when an incoming call is received.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.callInitiateFailed

Fired when an attempt to initiate an outgoing call fails.

Parameters

NameTypeDescription
reasonTextStringThe reason for the failure or empty string.

kandy.callInitiated

Fired when an outgoing call is initiated.

Parameters

NameTypeDescription
outgoingCallCallCurrent active call.
numberStringThe Kandy user being called.

kandy.callRejectFailed

Fired when an incoming call rejection fails.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.callRejected

Fired when an incoming call is rejected.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.callScreenStopped

Fired when a user stops a screensharing session using the browser provided controls or by calling `kandy.call.stopScreenSharing`.

Parameters

NameTypeDescription
callCallCall for which the screen sharing was stopped.

kandy.callStateChanged

Fired during a call when the state of the call changes. For example whether the other side is no longer sending video.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.callTransferFailed

Fired when a call transfer fails.

Parameters

NameTypeDescription
callCallCall that was attempted to be transferred.

kandy.callTransferred

Fired when a call is transferred to a third-party.

Parameters

NameTypeDescription
callCallCall that was transferred.

kandy.callUnhold

Fired when the remote party releases hold the on call.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.chatGroupBoot

Fired when a user (or multiple users) is removed from a group. All group members receive the event.

Parameters

NameTypeDescription
messageMessageThe group boot message.

kandy.chatGroupDelete

Fired when a group is deleted. All group members receive the event.

Parameters

NameTypeDescription
messageMessageThe group delete message

kandy.chatGroupInvite

Fired when a user is added to a group. All group members, including the newly added member, receive the event.

Parameters

NameTypeDescription
messageMessageThe group invite message.

kandy.chatGroupLeave

Fired when a user leaves a group. All group members receive the event.

Parameters

NameTypeDescription
messageMessageThe group leave message

kandy.chatGroupMessage

Fired when a message is received in a group. All group members except the sender receive the event message.

Parameters

NameTypeDescription
messageMessageThe received message.

kandy.chatGroupUpdate

Fired when a group is updated. All group members receive the event.

Parameters

NameTypeDescription
messageMessageThe group update message

kandy.chatRemoteAck

Fired when a message was acknowledged to be received by the other party.

Parameters

NameTypeDescription
messageMessageThe chat ack message.

kandy.loginFailed

Fired when login failed.

Parameters

NameTypeDescription
messageStringError message for loginfailed.

kandy.loginSuccess

Fired when the user logs in.

Parameters

NameTypeDescription
userUserThe logged on user object

kandy.media

Fired when an error occurs when initiating media.

Parameters

NameTypeDescription
errorInfoObjectInformation about the media error.

kandy.message

Fired when a new message is received.

Parameters

NameTypeDescription
messageObjectThe chat message to be handled.

kandy.onConnectionLost

Fired when the connection to Kandy server dies.

kandy.oncall deprecated

Use a callestablished and/or callstatechanged instead.

Fired when a call is established or a call parameter changes.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.remotehold deprecated

Use the ‘callHold’ event instead.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.remoteunhold deprecated

Use the ‘callUnhold’ event instead.

Parameters

NameTypeDescription
callCallCurrent active call.

kandy.session


kandy.session.onActive

Fired when a session is activated. This is received by all participants.

Parameters

NameTypeDescription
dataObjectData object containing message details.

kandy.session.onBoot

Fired when a participant is booted by an admin. This is only received by booted participant.

Parameters

NameTypeDescription
dataObjectData object containing message details.

kandy.session.onData

Fired when a participant sends data with sendData(). This is received by all participants except the sender. The only exception is that if a particular user is given to sendData() then only that participant will receive it.

Parameters

NameTypeDescription
dataObjectData object containing message details.

kandy.session.onInactive

Fired when a session is inactivated. This is received by all participants.

Parameters

NameTypeDescription
dataObjectData object containing message details.

kandy.session.onJoinApprove

Fired when a participant's join request has been approved. This is received by the participant who made the request.

Parameters

NameTypeDescription
dataObjectData object containing message details.

kandy.session.onJoinReject

Fired when a participant's join request has been rejected. This is received by the participant who made the request.

Parameters

NameTypeDescription
dataObjectData object containing message details.

kandy.session.onTermination

Fired when a session is terminated. This is received by all participants.

Parameters

NameTypeDescription
dataObjectData object containing message details.

kandy.session.onUserBoot

Fired when a participant is booted by an admin. This is received all participants except the participant that was booted.

Parameters

NameTypeDescription
dataObjectData object containing message details.

kandy.session.onUserJoin

Fired when a participant joins a session. This is received by all participants.

Parameters

NameTypeDescription
dataObjectData object containing message details.

kandy.session.onUserJoinRequest

Fired when a participant sends a join request for a session. Only administrators of the session will receive this event.

Parameters

NameTypeDescription
dataObjectData object containing message details.

kandy.session.onUserLeave

Fired when a participant leaves a session. This is received by all of the participants in the session.

Parameters

NameTypeDescription
dataObjectData object containing message details.