3.41.1
The SDK creation factory. Create an instance of the SDK by calling this factory with the desired configurations. The SDK instance will be referred as 'api' throughout the rest of the documentation content.
(config)
The configuration object.
api
:
The SDK instance.
// Instantiate the SDK.
import { create } from 'kandy'
const client = create({
authentication: { ... },
logs: { ... },
...
});
// Use the SDK's API.
client.on( ... );
The configuration object. This object defines what different configuration values you can use when instantiating the SDK using the create function.
Configuration options for the Logs feature.
The SDK will log information about the operations it is performing. The amount of information will depend on how the Logs feature is configured.
The format of logs can also be customized by providing a LogHandler. This function will receive a LogEntry which it can handle as it sees fit. By default, the SDK will log information to the console. For more information, see the Logs feature description.
(Object)
Logs configs.
Name | Description |
---|---|
logs.logLevel string
(default 'debug' )
|
Log level to be set. See logger.levels . |
logs.handler logger.LogHandler?
|
The function to receive log entries from the SDK. If not provided, a default handler will be used that logs entries to the console. |
logs.enableFcsLogs boolean
(default true )
|
Enable the detailed call logger for v3.X. Requires log level debug. |
logs.logActions (Object | boolean)
(default false )
|
Options specifically for action logs when logLevel is at DEBUG+ levels. Set this to false to not output action logs. |
logs.logActions.handler logger.LogHandler?
|
The function to receive action log entries from the SDK. If not provided, a default handler will be used that logs actions to the console. |
logs.logActions.actionOnly boolean
(default false )
|
Only output information about the action itself. Omits the SDK context for when it occurred. |
logs.logActions.collapsed boolean
(default false )
|
Whether logs should be minimized when initially output. The full log is still output and can be inspected on the console. |
logs.logActions.diff boolean
(default false )
|
Include a diff of what SDK context was changed by the action. |
logs.logActions.level string
(default 'debug' )
|
Log level to be set on the action logs |
logs.logActions.exposePayloads boolean
(default true )
|
Allow action payloads to be exposed in the logs, potentially displaying sensitive information. |
Configuration options for the Authentication feature.
(Object)
Authentication configs.
Name | Description |
---|---|
authentication.subscription Object
|
|
authentication.subscription.server string
|
Hostname of the server to be used for subscription requests. |
authentication.subscription.protocol string
(default https )
|
Protocol to be used for subscription requests. |
authentication.subscription.port Number
(default 443 )
|
Port to be used for subscription requests. |
authentication.subscription.version string
(default 1 )
|
Version of the REST API to be used. |
authentication.subscription.expires Number
(default 3600 )
|
Time duration, in seconds, until a subscription should expire. |
authentication.subscription.service Array?
|
Services to subscribe to for notifications. |
authentication.websocket Object
|
|
authentication.websocket.server string
|
Hostname of the server to be used for websocket notifications. |
authentication.websocket.protocol string
(default wss )
|
Protocol to be used for websocket notifications. |
authentication.websocket.port Number
(default 443 )
|
Port to be used for websocket notifications. |
Configuration options for the call feature.
(Object)
The call configuration object.
Name | Description |
---|---|
call.callDefaults Object?
|
Default options to be used when making/answering a call. |
call.callDefaults.isAudioEnabled boolean
(default true )
|
Specifies whether audio is enabled or not. |
call.callDefaults.isVideoEnabled boolean
(default true )
|
Specifies whether video is enabled or not. |
call.callDefaults.sendInitialVideo boolean
(default false )
|
Specifies whether to send an initial video stream or not. |
call.callDefaults.remoteVideoContainer Object?
|
Specifies the container where video (coming from remote party) is rendered. |
call.callDefaults.localVideoContainer Object?
|
Specifies the container where video (coming from local party) is rendered. |
call.chromeExtensionId string?
|
ID of the screenshare extension being used for screenshare of Google Chrome. |
call.recordCallStats boolean
(default false )
|
Whether to enable the recording of call statistics as part of app's local storage. |
call.earlyMedia boolean
(default false )
|
Whether to use early media (e.g. for playing incoming tones) as part of an outgoing call. |
call.callAuditTimer number
(default 30000 )
|
Audit time value for calls, as a positive number in milliseconds. |
call.activeCallTimeoutMS number
(default 120000 )
|
Timeout for an existing ringing call before it gets terminated, as a positive number in milliseconds. |
call.ringingFeedback boolean?
|
When enabled, inform Spidr that RingingFeedback is supported. |
call.codecsToReplace string?
|
Specifies alternative audio/video codecs to use for a given call. It has been deprecated so pipeline parameter should be used instead. |
call.videoInactiveOnHold boolean
(default false )
|
Sets the video as "inactive" instead of "sendonly" when holding a call. |
call.forceDisableMediaOnHold boolean
(default false )
|
Disables any type of media (e.g. Comfort Noise) from transmitting when call is held locally. |
call.iceCandidateCollectionTimeoutInterval number
(default 3000 )
|
When provided (in milliseconds), ice candidate collection is assumed to be completed if at least one candidate is received within the interval. |
call.relayCandidateCollectionTimeoutCycle boolean
(default false )
|
When enabled, iceCandidateCollectionTimeoutInterval is restarted until receiving first relay candidate. If the provided cycle limit is reached, ice candidate collection assumed to be completed. |
call.recordCallStats boolean
(default false )
|
When enabled, call statistics are recorded in app's localstorage after the call is terminated. |
call.callConstraints Object?
|
Custom RTCPeerConnection constraints to use for calls. Will cause errors if malformed. |
call.callConstraints.chrome Object?
|
Custom constraints to be used on Google Chrome. |
call.callConstraints.firefox Object?
|
Custom constraints to be used on Mozilla Firefox. |
call.bundlePolicy string
(default 'DISABLED' )
|
The bundle policy to use for peer connections. Value can be fcs.SDP_CONSTANTS.BUNDLE_POLICY.MAX_COMPAT, fcs.SDP_CONSTANTS.BUNDLE_POLICY.MAX_BUNDLE, fcs.SDP_CONSTANTS.BUNDLE_POLICY.BALANCED or fcs.SDP_CONSTANTS.BUNDLE_POLICY.DISABLED. The DISABLED option means that bundle group lines will be removed from every SDP. |
call.opusConfig Object?
|
Bandwidth controls to add for Opus audio codec. |
call.opusConfig.maxPlaybackRate number?
|
Maximum playback rate, in bits per second. Must be a positive value between 8000 and 48000. |
call.opusConfig.maxAverageBitrate number?
|
A bitrate encoding value between 6000 and 510000 bits per second. |
call.opusConfig.fec number?
|
Specifies whether Forward Error Correction is enabled or not. When enabled, FEC provides robustness against packet loss. Acceptable values can only be 0 or 1. |
call.opusConfig.dtx number?
|
Specifies whether Discontinuous Transmission mode is enabled or not. When enabled, DTX reduces the bitrate during silence or background noise. Acceptable values can only be 0 or 1. |
call.opusConfig.ptime number?
|
Packet (i.e. frame) duration in milliseconds. Frames will be combined into packets to achieve the maximum of 120 ms duration. A positive value between 2.5 and 120. |
call.webrtcLogCollectionInterval number
(default 3000 )
|
Interval at which to collect WebRTC logs for calls, in milliseconds. |
call.useRelay boolean
(default false )
|
Whether we should force connection through the relay candidates (i.e. TURN server). Mostly used for testing. |
call.trickleIceSupport string
(default 'none' )
|
Whether we should advertise and use Trickle ICE. Accepted value is one of: 'none', 'half' or 'full'. |
call.continuity boolean
(default false )
|
Whether an existing voice call can be persisted, as a mobile phone moves between circuit switched and packet switched domains (e.g. GSM to WiFi). |
call.resyncOnConnect boolean
(default false )
|
Whether all active calls should be resynched upon connecting or reconnecting to the websocket (requires Kandy Link 4.7.1+). |
Configuration options for the Connectivity feature. The SDK can only use keepalive as the connectivity check.
Keep Alive: The client sends "keepalive" messages (to the server) on the websocket at regular intervals. This lets the server know that the client is still connected, and that it should "keep the connection alive".
For more information on keepalive see here: https://en.wikipedia.org/wiki/Keepalive
(Object)
Connectivity configs.
Name | Description |
---|---|
connectivity.pingInterval Number
(default 30000 )
|
Time in between websocket ping attempts (milliseconds). |
connectivity.reconnectLimit Number
(default 5 )
|
Number of failed reconnect attempts before reporting an error. Can be set to 0 to not limit reconnection attempts. |
connectivity.reconnectDelay Number
(default 5000 )
|
Base time between websocket reconnect attempts (milliseconds). |
connectivity.reconnectTimeMultiplier Number
(default 1 )
|
Reconnect delay multiplier for subsequent attempts. The reconnect delay time will be multiplied by this after each failed reconnect attempt to increase the delay between attempts. eg. 5000ms then 10000ms then 20000ms delay if value is 2. |
connectivity.reconnectTimeLimit Number
(default 640000 )
|
Maximum time delay between reconnect attempts (milliseconds). Used in conjunction with the reconnect time multiplier to prevent overly long delays between reconnection attempts. |
connectivity.autoReconnect Boolean
(default true )
|
Flag to determine whether the SDK will attempt to automatically reconnect after connectivity disruptions. |
connectivity.maxMissedPings Number
(default 3 )
|
Maximum pings sent (without receiving a response) before reporting an error. |
connectivity.checkConnectivity Boolean
(default true )
|
Flag to determine whether the SDK should check connectivity. |
connectivity.webSocketOAuthMode string
(default query )
|
query will send the bearer access token to authenticate the websocket and none will not send it. |
Configuration options for the notification feature.
(Object)
The notifications configuration object.
Name | Description |
---|---|
notifications.idCacheLength number
(default 100 )
|
Default amount of event ids to remember for de-duplication purposes. |
notifications.incomingCallNotificationMode string
(default 'any-channel' )
|
Communication channel mode used for incoming call notifications. Supported values are 'any-channel' or 'push-channel-only'. |
notifications.pushRegistration Object?
|
Object describing the server to use for push services. |
notifications.pushRegistration.server string?
|
Hostname for the push registration server. |
notifications.pushRegistration.port string?
|
Port for the push registration server. |
notifications.pushRegistration.protocol string?
|
Protocol for the push registration server. |
notifications.pushRegistration.version string?
|
Version for the push registration server. |
Available media devices have been changed.
A change has been made to default devices used for calls.
Media support has been checked.
(Object)
Name | Description |
---|---|
params.result Object
|
Results of initializing media. |
params.result.error boolean
|
Whether the initialization was successful or not. |
params.result.code number
|
A unique code describing the result scenario. |
params.result.message string
|
Human readable message of the result. |
The status of previewing local video has changed.
An error has occurred when changing local video preview status.
(Object)
Name | Description |
---|---|
params.error api.BasicError
|
Information about the error. |
The 'api' is the type returned by the create function. It contains various top-level functions that pertain to SDK global instance as well as several nested namespaces that pertain to various features (e.g. call, contacts, presence, etc).
Returns the current version of the API.
Destroys the SDK, and removes its state, rendering the SDK unusable. Useful when a user logs out and their call data needs to be destroyed. The SDK must be recreated to be usable again. The destroy command is async, and will happen on the next tick so as not to interfere with any ongoing events.
// Instantiate the SDK.
import { create } from 'kandy'
const config = {
authentication: { ... },
logs: { ... },
...
}
let client = create(config);
client.on( ... )
// Use the SDK
...
// Destroy the SDK, then recreate on the next step
client.destroy()
client = create(config)
client.on( ... )
Update the configuration values for the SDK to use.
This API will only modify the configurations provided, leaving other configurations as they were originally set, by performing a merge of the new values into the previous values.
Please note that updating the call.removeH264Codecs configuration will not immediately change the SDP handlers used for a call. If you want to add or remove the h264 codec remover sdp handler you should follow this procedure:
Update the config for removeH264Codecs using the updateConfig API.
Update the sdp handler list using the setSdpHandlers API and provide any client defined SDP handler functions.
NOTE: You can get the currently defined SDP handler functions with the getConfig API.
Please note that the object provided to the updateConfig
API may be different
than the object retrieved from the getConfig API. This may happen when a format
change has happened and the SDK modifies the provided format to alleviate
backwards-compatibility issues. We recommend ensuring the configurations you
provide are as described by the config section.
// Instantiate the SDK with certain configs.
const client = create({
authentication: { ... },
logs: { ... },
...
})
// Modify a subsection of the configs at a later time.
// This will only update the specified configurations.
client.updateConfig({
logs: {
loglevel: 'DEBUG'
}
})
Add an event listener for the specified event type. The event is emitted by the SDK instance.
(string)
The event type for which to add the listener.
(Function)
The listener for the event type. The parameters of the listener depend on the event type.
// Listen for events of a specific type emitted by the SDK.
client.on('dummy:event', function (params) {
// Handle the event.
})
Connect with user credentials to any backend services that the SDK instance deals with.
(Object)
The credentials object.
Name | Description |
---|---|
credentials.username string
|
The username including the application's domain. |
credentials.password string
|
The user's password. |
credentials.authname string?
|
The user's authorization name. |
(Object?)
The options object for non-credential options.
Name | Description |
---|---|
options.forceLogOut boolean?
|
Force the oldest connection to log out if too many simultaneous connections. Link only. |
options.clientCorrelator string?
|
Unique ID for the client. This is used by the platform to identify an instance of the application used by the specific device. |
client.connect({
username: 'alfred@example.com',
password: '********'
authname: '********'
}, {
forceLogOut: true
});
Connect by providing a username and HMAC token. This connects to any backend services that the SDK instance deals with.
An HMAC token is used to verify a user via the user's authorization within an organization.
HMAC tokens are generated by using the HmacSHA1 algorithm and a key on a data object
containing an authenticationTokenRequest
object with the following properties:
(Object)
The credentials object.
Name | Description |
---|---|
credentials.username string
|
The username. |
credentials.hmacToken string
|
An HMAC token for the user with the provided user ID. |
(Object?)
The options object for non-credential options.
Name | Description |
---|---|
options.forceLogOut boolean?
|
Force the oldest connection to log out if too many simultaneous connections. |
options.clientCorrelator string?
|
Unique ID for the client. This is used by the platform to identify an instance of the application used by the specific device. |
const hmacToken = HmacSHA1Algorithm({
authenticationTokenRequest: {
subscriberId: 'alfred',
organizationId: 'example.com'
}
}, key)
client.connect({
username: 'alfred@example.com',
hmacToken
}, {
forceLogOut: true
});
Disconnects from the backend. This will close the websocket and you will stop receiving events.
Retrieves information about the current user.
Object
:
user The user data.
string
:
user.username The username of the current user. Note that this username can take different encoded forms.
It's not meant to be displayed to a user.
string
:
user.token The current access token.
Get the connection state.
Object
:
connection The connection state.
boolean
:
connection.isConnected Whether the authenticated user is currently connected.
boolean
:
connection.isPending Whether the authenticated user's connection is currently pending.
Object
:
connection.error The error object if an error occurred.
string
:
connection.error.message The error message.
string
:
connection.error.stack The stack trace of the error.
Sets the user credentials necessary to make requests to the platform.
client.setCredentials({
username: 'alfred@example.com',
password: '********'
authname: '********'
});
Sets the username and HMAC token necessary to make requests to the platform.
An HMAC token is used to verify a user via the user's authorization within an of organization.
HMAC tokens are generated by using the HmacSHA1 algorithm and a key on a data object
containing an authenticationTokenRequest
object with the following properties:
const hmacToken = HmacSHA1Algorithm({
authenticationTokenRequest: {
subscriberId: 'alfred',
organizationId: 'example.com'
}
}, key)
client.setCredentials({
username: 'alfred@example.com',
hmacToken
});
Authentication state has changed. You can get the new state by calling getConnection()
.
There was an error with authentication.
(Object)
Name | Description |
---|---|
params.error api.BasicError
|
The Basic error object. |
An attempt to extend the current user's subscription was made.
In a failure scenario, the current user is still connected, and further resubscription attempts will be made, but may become disconnected if the session expires.
(Object)
Name | Description |
---|---|
params.attemptNum number
|
The attempt number of this resubscription. |
params.isFailure boolean
|
Whether the resubscription failed or not. |
params.error api.BasicError?
|
The Basic error object. |
The information (credentials) needed for connecting have been set.
The audio bridge feature allows multiple audio calls to be bridged together for a local three-way call.
Audio bridge functions are all part of the 'audioBridge' namespace.
An error occurred while performing an audio bridge operation.
(Object)
Name | Description |
---|---|
params.error api.BasicError
|
The Basic error object. |
The 'call.history' namespace is used to retrieve and inspect the authenticated users call logs.
Functions below are all part of this namespace.
Fetches the list of call logs and stores them locally. The API CallHistory.get can then be used to get the logs from local state after it has been updated.
Deletes all call logs.
Gets the list of call logs cached locally. The event
callHistory:changed
is used to indicate the local state of logs
has been updated.
Array
:
A list of call log records, ordered by latest first.
client.on('callHistory:change', function() {
// Get all call logs when they've been updated.
let callLogs = client.call.history.get();
});
Gets the cached call history data and returns stringified data.
The data is provided in a format that can be used directly with the call.history.setCache API. This allows an application to persist the information across SDK instances when the backend environment does not support the CallHistory feature.
string
:
A stringified list of call log records from the cache, ordered by latest first.
Sets the cached call history data, expects stringified data as it will be parsed.
The data can be retrieved from the call.history.getCache API. This allows an application to persist the information across SDK instances when the backend environment does not support the CallHistory feature.
(string)
The stringified call history data to store in the cache.
Call history state has been updated. See CallHistory.get to retrieve new state.
An error occurred while performing a call history operation.
(Object)
Name | Description |
---|---|
params.error api.BasicError
|
The Basic error object. |
Call history cached state has been updated
The Calls feature is used to make audio and video calls to and from SIP users and PSTN phones.
Call functions are all part of the 'call' namespace.
Whenever 'user' is mentioned as input parameter within this API, it needs to be provided in the user@domain format.
States of a call.
(string)
: The call is on-going.
(string)
: The call has been established and is waiting for a user response.
(string)
: The call has been terminated.
(string)
: The call has been put on hold locally.
(string)
: The call has been put on hold remotely.
client.on('call:stateChange', function(callInfo) {
if(callInfo.state === client.call.states.ENDED) {
// Call has ended.
}
});
State of the media connection within a call.
(string)
: A new media connection process has started.
(string)
: Media is searching for a connection.
(string)
: Media has found a connection, but may still be searching for a better connection to use.
(string)
: Media has finished searching and been established. Audio/video should now be flowing on the call.
(string)
: Media was not able to find a connection. Audio/video will not flow.
(string)
: The media connection has lost its connection and is trying to recover.
(string)
: The media connection has shut down.
Start an outgoing call.
(string)
Full user ID of the call recipient.
(Object?)
Call options.
Name | Description |
---|---|
options.from string?
|
Sets the display name of the caller to be sent alongside the username of the user. |
options.isVideoEnabled boolean
(default true )
|
Whether to enable video during the call. If false, you cannot start video mid-call. |
options.contact Object?
|
Object containing firstName and lastName of caller. |
options.sendInitialVideo boolean
(default false )
|
Whether to start the call sending the local video stream. |
options.isAudioEnabled boolean
(default true )
|
Whether to enable audio during the call. Setting this to false will disable audio for the call. |
options.webrtcdtls boolean
(default true )
|
Whether to enable DTLS for WebRTC calls. |
options.videoResolution Object?
|
The object to configure the local video resolution. |
options.videoResolution.height number?
|
The height in pixels of the local video. |
options.videoResolution.width number?
|
The width in pixels of the local video. |
options.customParameters Array<{name: string, value: string}>?
|
Custom SIP header parameters for the SIP backend. |
options.remoteVideoContainer HTMLElement?
|
The HTML element to use as a container for the remote video. |
options.localVideoContainer HTMLElement?
|
The HTML element to use as a container for the local video. |
options.normalizeAddress boolean
(default false )
|
Whether to enable normalization of callee address. |
string
:
Id of the outgoing call.
let remoteContainer = document.getElementById('remote-container');
// Start a video call that only shows the remote media (not local).
let callId = client.call.make('sampleUser@example.com', {
isVideoEnabled: true,
sendInitialVideo: true,
remoteVideoContainer: remoteContainer,
customParameters: [
{
"name": "X-GPS",
"value": "42.686032,23.344565"
}
]
});
Answer an incoming call.
(string)
The ID of the call to answer.
(Object?)
Call options.
Name | Description |
---|---|
options.isVideoEnabled boolean?
|
Whether to enable video during the call. If false, you cannot start video mid-call. |
options.sendInitialVideo boolean?
|
Whether to start the call sending the local video stream. |
options.isAudioEnabled boolean
(default true )
|
Whether to enable audio during the call. Setting this to false will disable audio for the call. |
options.videoResolution Object?
|
The object to configure the local video resolution. |
options.videoResolution.height number?
|
The height in pixels of the local video. |
options.videoResolution.width number?
|
The width in pixels of the local video. |
options.localVideoContainer HTMLElement?
|
The HTML element to use as a container for the local video. |
options.remoteVideoContainer HTMLElement?
|
The HTML element to use as a container for the remote video. |
Set custom parameters on an ongoing call.
(string)
The ID of the call being acted on.
// Set custom parameters for call.
client.call.setCustomParameters(
callId,
[
{ "name": "X-GPS",
"value": "42.686032,23.344565"
}
]
});
Start local video stream for an ongoing call.
(string)
Id of the call being acted on.
(Object?)
Options for the video stream.
Name | Description |
---|---|
options.videoResolution Object?
|
The video resolution configuration object. |
options.videoResolution.height number?
|
The height of the outgoing video in pixels. |
options.videoResolution.width number?
|
The width of the outgoing video in pixels. |
Starts sharing a screen over a call.
(string)
Id of the call being acted on.
(Object)
Name | Description |
---|---|
options.mediaSourceId string
|
Id of the media screen to share. |
options.height Number
(default 768 )
|
The height of the video stream to send. |
options.width Number
(default 1024 )
|
The width of the video stream to send. |
options.frameRate Number
(default 15 )
|
The number of frames per second to request. |
The clickToCall namespace is used to bridge a call between two specified devices
ClickToCall had an error.
(Object)
Name | Description |
---|---|
params.callId string
|
A unique id representing the call made |
params.error api.BasicError
|
The Basic error object. |
The 'connection' namespace is used to connect and maintain connections between the SDK and one or more backend servers.
Information about a websocket connection.
Can be retrieved using the connection.getSocketState API.
Type: Object
(boolean)
: The state of the websocket connection.
(boolean)
: True if the client has sent a ping to the server and is still waiting for a pong response.
(Object)
: Information about how the websocket is being used.
(string)
: The SDK platform being used.
(number)
: How often the client will ping the server to test for websocket connectivity.
(number)
: How many times the SDK will try to reconnect a disconnected websocket.
(number)
: How long the SDK will wait before retrying websocket reconnection.
(number)
: Reconnect delay multiplier for subsequent attempts. The reconnect delay time will be multiplied by this after each failed reconnect attempt to increase the delay between attempts. eg. 5000ms then 10000ms then 20000ms delay if value is 2.
(number)
: Maximum time delay between reconnect attempts (milliseconds). Used in conjunction with
reconnectTimeMultiplier
to prevent overly long delays between reconnection attempts.
(boolean)
: Indicates if the SDK should automatically try reconnecting a disconnected websocket.
(number)
: How many missed pings before the SDK stops trying to reconnect a disconnected websocket.
(string)
: The mode used for authenticating with the server.
(Object)
: Information required to connect a websocket to the server.
wsInfo.protocol
string?
The protocol to use to connect a websocket.
wsInfo.server
string?
The domain name or IP address of the server to connect to.
wsInfo.port
number?
The port of the server to connect to.
wsInfo.url
string?
The URL path to use to request a websocket connection.
wsInfo.params
string?
Any additional params that might be required by the server to establish the websocket connection.
(number)
: The date and time that the last known contact with the server was.
Get the state of the websocket.
(string
= 'link'
)
Backend platform for which to request the websocket's state.
connection.WSConnectionObject
:
Details about the current websocket connection, including state and configuration.
Triggers a reset in the connection to the WebSocket being used for notifications. This can be used in scenarios where a network issue (undetectable by the SDK) is detected by an application.
If there is no WebSocket currently connected, this function has no effect. Calling this function will trigger all the normal WebSocket and connectivity lifecycle events as well as trigger re-connection processing that follows the configuration of the SDK. Calling this function always has the potential of causing some events being lost by the SDK and preventing proper operation.
The 'contacts' namespace allows users to store personal contacts to their account.
Add a contact to a user's personal address book.
Will trigger the contacts:new
event.
(Object)
The contact object.
Name | Description |
---|---|
contact.primaryContact string
|
The primary userId for the contact |
contact.contactId string
|
The contact's unique contact ID |
contact.firstName string?
|
The contact's first name |
contact.lastName string?
|
The contact's last name |
contact.photoUrl string?
|
The URL address identifying location of user's picture |
contact.emailAddress string?
|
The contact's email address |
contact.homePhone string?
|
The contact's home phone number |
contact.workPhone string?
|
The contact's business phone number |
contact.mobilePhone string?
|
The contact's mobile phone number |
contact.conferenceURL string?
|
Conference URL and access code for this user's address book entry |
contact.fax string?
|
The user's fax number |
contact.pager string?
|
The user's pager number |
contact.groupList string?
|
The name of the contact list for which to add this contact to ("friends" by default) |
contact.friendStatus boolean?
|
Indicates whether or not the contact is a friend of the user |
Refreshes the local information about contacts. This will get new contacts from the platform.
Will trigger the contacts:change
event.
Update a contact from the user's personal address book.
Will trigger the contacts:change
event.
(Object)
The contact object.
Name | Description |
---|---|
contact.primaryContact string
|
The primary userId for the contact |
contact.contactId string
|
The contact's unique contact ID |
contact.firstName string?
|
The contact's first name |
contact.lastName string?
|
The contact's last name |
contact.photoUrl string?
|
The URL address identifying location of user's picture |
contact.emailAddress string?
|
The contact's email address |
contact.homePhone string?
|
The contact's home phone number |
contact.workPhone string?
|
The contact's business phone number |
contact.mobilePhone string?
|
The contact's mobile phone number |
contact.conferenceURL string?
|
Conference URL and access code for this user's address book entry |
contact.fax string?
|
The user's fax number |
contact.pager string?
|
The user's pager number |
contact.groupList string?
|
The name of the contact list for which to add this contact to ("friends" by default) |
contact.friendStatus boolean?
|
Indicates whether or not the contact is a friend of the user |
A new contact has been added to the address book.
(Object)
The new contact.
The contacts list has changed.
client.on('contacts:change', function () {
// Get the updated list of contacts.
const contacts = client.contacts.getAll()
...
})
The messaging feature revolves around a 'conversation' namespace. It is responsible to store the conversations and its messages, and return conversation objects when requested.
See the "Conversation" and "Message" sections of the documentation for more details.
Messaging functions are all part of the 'conversation' namespace. Ex: client.conversation.get('id').
A Conversation object represents a conversation between either two users, or a user and a group. A Conversation can create messages via the conversation's createMessage() function.
Type: Object
(string)
: The id of the remote user with which the current user is having a conversation.
Create and return a message object. You must provide a text
part as demonstrated in the example.
conversation.Message
:
The newly created Message object.
conversation.createMessage({type: 'text', text: 'This is the message'});
Clears all messages in this conversation from local state.
Get the messages associated with this conversation.
Function
:
messages.markRead Marks the message as read.
Function
:
messages.forward Forward the message to another user.
string
:
messages.messageId The Id of the message.
string
:
messages.sender The user Id of the user who sent the message.
number
:
messages.timestamp The time at which the message was sent.
boolean
:
messages.read Whether the message has been marked as read.
boolean
:
messages.isPending Whether the message has finished being sent to the server.
Array
:
messages.parts The parts of the message.
Subscribe to this conversations messages array.
Function
:
The unsubscribe function.
Allows the user to fetch messages associated with a specific conversation from the server. When the operation is complete, a NEW_MESSAGE event will be emitted. Messages can then be retrieved using getMessages.
(number
= 50
)
An amount of messages to fetch.
A Message object is a means by which a sender can deliver information to a recipient.
Creating and sending a message:
A message object can be obtained through the Conversation.createMessage API on an existing conversation.
Messages have Parts which represent pieces of a message, such as a text part, a json object part or a file part. Once all the desired parts have been added to the message using the Message.addPart function, the message can then be sent using the Message.send function.
Once the sender sends a message, this message is saved in sender's state as an object. Similarly, once the recipient gets a message, this message is saved in recipient's state.
Retrieving a delivered message:
Once a message is delivered successfully, it can be obtained through the Conversation.getMessages or Conversation.getMessage API on an existing conversation.
Below are the properties pertaining to the message object, returned by Conversation.getMessage(s) APIs, for either sender or recipient.
Type: Object
(number)
: A Unix timestamp in seconds marking the time when the message was created by sender.
(Array<conversation.Part>)
: An array of Part Objects.
(string)
: The primary contact address of the sender.
(Array<string>)
: An array of primary contact addresses associated with various destinations to which the message is meant to be delivered.
(string)
: The unique id of the message. The message object (stored in sender's state) has a different id
than the one associated with the message object stored in recipient's state.
(string)
: The type of message that was sent. See
conversation.chatTypes
for valid types.
This property applies only to message objects stored in sender's state.
Sends the message.
Get a conversation object matching the user ID provided in the 'destination' parameter. If successful, the event 'conversations:change' will be emitted.
This API will retrieve a conversation already existing in the store.
(string)
The destination for messages created in this conversation. This will
be a user's sip address.
conversation.Conversation
:
A Conversation object matching the passed destination, otherwise undefined is returned.
Returns all conversations currently tracked by the SDK
Array<conversation.Conversation>
:
An array of conversation objects.
A new conversation has been created and added to the state.
A change has occurred in the conversation list.
(Array)
An array of objects containing information about the conversations that have changed
Name | Description |
---|---|
params.destination Array
|
The destination for messages created in this conversation. |
params.type string
|
The type of conversation to create. Can be one of "chat", "im", "sms" or "group" |
A change has occurred in a specific conversations message list.
If a single message was affected/created, messageId
will be present
as part of the event argument.
(Object)
Name | Description |
---|---|
params.destination string
|
The destination for messages created in this conversation. |
params.type string
|
The type of conversation to create. Can be one of "chat", "im", "sms" or "group" |
params.messageId string?
|
The ID of the message affected. |
params.sender string?
|
The username of the sender of the message which caused the
messages:change
event to be triggered.
|
An error occurred with messaging.
(Object)
Name | Description |
---|---|
params.error api.BasicError
|
The Basic error object. |
An error occurred while performing a device operation.
Type: string
(Object)
Name | Description |
---|---|
params.error api.BasicError
|
The Basic error object. |
Retrieves the available media devices for use.
The SDK has an internal logging system for providing information about its behaviour. The SDK will generate logs, at different levels for different types of information, which are routed to a "Log Handler" for consumption. An application can provide their own Log Handler (see config.logs) to customize how the logs are handled, or allow the default Log Handler to print the logs to the console.
The SDK's default Log Handler is merely a thin wrapper around the browser's
console API (ie. window.console
). It receives the log generated by the
SDK, called a "Log Entry", formats a
human-readable message with it, then uses the console to log it at the
appropriate level. This is important to be aware of, since your browser's
console may affect how you see the SDK's default log messages. Since the
default Log Handler uses the console's levels, the browser may filter
which messages are shown depending on which levels it has configured. For
a user that understands console log levels, this can be helpful for
filtering the logs to only the relevant information. But it can equally
be a hindrance by hiding the more detailed log messages (at the 'debug'
level), since browser can have this level hidden by default. For this
reason, we recommend providing a custom Log Handler to the SDK that is
better suited for your application and its users.
A LogEntry object is the data that the SDK compiles when information is logged. It contains both the logged information and meta-info about when and who logged it.
A LogHandler provided to the SDK (see config.logs) will need to handle LogEntry objects.
Type: Object
(number)
: When the log was created, based on UNIX epoch.
(string)
: The log function that was used to create the log.
(string)
: The level of severity the log.
(Object)
: The subject that the log is about.
(Array)
: The logged information, given to the Logger
method as parameters.
(Object?)
: Timing data, if the log method was a timer method.
function defaultLogHandler (logEntry) {
// Compile the meta info of the log for a prefix.
const { timestamp, level, target } = logEntry
let { method } = logEntry
const logInfo = `${timestamp} - ${target.type} - ${level}`
// Assume that the first message parameter is a string.
const [log, ...extra] = logEntry.messages
// For the timer methods, don't actually use the console methods.
// The Logger already did the timing, so simply log out the info.
if (['time', 'timeLog', 'timeEnd'].includes(method)) {
method = 'debug'
}
console[method](`${logInfo} - ${log}`, ...extra)
}
A LogHandler can be used to customize how the SDK should log information. By default, the SDK will log information to the console, but a LogHandler can be configured to change this behaviour.
A LogHandler can be provided to the SDK as part of its configuration (see config.logs). The SDK will then provide this function with the logged information.
Type: Function
(Object)
The LogEntry to be logged.
// Define a custom function to handle logs.
function logHandler (logEntry) {
// Compile the meta info of the log for a prefix.
const { timestamp, level, target } = logEntry
let { method } = logEntry
const logInfo = `${timestamp} - ${target.type} - ${level}`
// Assume that the first message parameter is a string.
const [log, ...extra] = logEntry.messages
// For the timer methods, don't actually use the console methods.
// The Logger already did the timing, so simply log out the info.
if (['time', 'timeLog', 'timeEnd'].includes(method)) {
method = 'debug'
}
console[method](`${logInfo} - ${log}`, ...extra)
}
// Provide the LogHandler as part of the SDK configurations.
const configs = { ... }
configs.logs.handler = logHandler
const client = create(configs)
Possible levels for the SDK logger.
The SDK will provide Log Entries to the Log Handler for all logs at or above the set log level. 'debug' is considered the lowest level and 'silent' the highest level. For example, if the current level is 'info', then the Log Handler will receive Log Entries for logs at 'info', 'warn', and 'error', but not for the 'debug' level.
(string)
: Nothing will be logged.
(string)
: Unhandled error information will be logged. If
the SDK encounters an issue it cannot resolve, the error will be included
in the logs. This likely points to an issue with the SDK itself or an
issue with how the SDK is being used.
(string)
: Warning messages for the application developer will
be logged. If the SDK encounters an issue that it can recover and continue,
a warning about the issue will be included in the logs. These logs point
to issues that need to be handled by the application. For example, providing
an invalid configuration to the SDK will cause a warning log that explains
the issue.
(string)
: General information about the SDK's operations will
be logged, outlining how the SDK is handling the operations. Reading through
these logs should provide a high-level view of what the SDK is doing,
and why it is doing it.
(string)
: Detailed information about the SDK's operations,
meant for debugging issues, will be logged. Specific information and relevant
operation data are provided for understanding the scenario that the SDK
was in during the operation.
The SDK's media features are used to control WebRTC Media Devices.
Media functions are all part of the 'media' namespace.
The 'notification' namespace allows user to register/deregister for/from push notifications as well as enabling/disabling the processing of websocket notifications.
Registers with Apple push notification service. Once registration is successful, the application will be able to receive standard and/or voip push notifications. It can then send these notifications to the SDK with api.notifications.process in order for the SDK to process them.
(Object)
Name | Description |
---|---|
params.services Array<string>
|
Array of services for which we wish to receive notifications. |
params.voipDeviceToken string
|
The voip device token used for voip push on iOS. This token is required if registering for call service notifications on iOS. |
params.standardDeviceToken string
|
The standardDevice token used for standard push on iOS . This token is required when registering for non-call service notifications. |
params.bundleId string
|
The bundleId to identify the application receiving the push notification. |
params.clientCorrelator string
|
Unique identifier for a client device. |
params.realm string
|
The realm used by the push registration service to identify and establish a connection with the service gateway. |
params.isProduction boolean
|
If true, push notification will be sent to production. If false, push notification will be sent to sandbox. |
Promise
:
When successful, the information of the registration.
Promise will reject with error object otherwise.
Registers with Google push notification service. Once registration is successful, the application will be able to receive standard and/or voip push notifications. It can then send these notifications to the SDK with api.notifications.process in order for the SDK to process them.
(Object)
Name | Description |
---|---|
params.services Array<string>
|
Array of services to register for. |
params.deviceToken string
|
The device token used for standard push on Android. This token is required when registering for all related services notifications. |
params.bundleId string
|
The bundleId to identify the application receiving the push notification. |
params.clientCorrelator string
|
Unique identifier for a client device. |
params.realm string
|
The realm used by the push registration service to identify and establish a connection with the service gateway. |
Promise
:
When successful, the information of the registration.
Promise will reject with error object otherwise.
An error occurred with push notifications.
(Object)
Name | Description |
---|---|
params.error api.BasicError
|
The Basic error object. |
params.channel string
|
The channel for the notification. |
The 'presence' namespace provides an interface for an application to set the User's presence information and to track other Users' presence information.
Presence information is persisted by the server. When the SDK is initialized, there will be no information available. Presence information will become available either by using presence.fetch or by subscribing for updates about other Users, using presence.subscribe.
Available presence information can be retrieved using presence.get or presence.getAll.
The PresenceStatus type defines the user's current status in terms of the user's availability to communicate/respond to other users in the network. An instance of this type can be obtained by invoking the presence.get function.
Reporting when a user is on the phone is enabled (by default), which means that presence update notifications will be sent whenever a user is in a call, as well as when the call has ended. This is a user preference enabled or disabled on server side, and it can only be changed on the server side.
The status is set to open as soon as a user subscribes for the presence service.
Type: Object
(string)
: The unique identifier for the user associated with this presence status.
(string)
: The current status the user has set for themselves. For supported values see
presence.statuses
.
(string)
: The current activity of the user.
For supported values see
presence.activities
.
(string)
: Additional message accompanying the status & activity.
(boolean)
: Whether the presence information has been loaded or is in the process of loading.
Updates the presence information for the current user.
See presence.statuses and presence.activities for valid values.
The SDK will emit a presence:selfChange event when the operation completes. The updated presence information is available and can be retrieved with presence.getSelf.
Other users subscribed for this user's presence will receive a presence:change event.
Retrieves the presence information for the current user.
This information is set using the presence.update API.
Object
:
Presence information for the current user.
Fetches presence information for the given users. This will refresh the available information with any new information from the server.
Available presence information can be retrieved using the presence.get or presence.getAll APIs.
A presence update about a subscribed user has been received.
This event is generated as a result of presence.fetch or presence.update operations.
For the latter operation, the current user receives a presence update of another user that the current user is subscribed to.
The changed information can be retrieved using the presence.get API.
The current user's presence information has changed.
The changed information can be retrieved using the presence.getSelf API.
An error occurred with presence.
(Object)
Name | Description |
---|---|
params.error api.BasicError
|
The Basic error object. |
Prompt the user for permission to use their audio and/or video devices.
The 'request' namespace (within the 'api' type) is used to make network requests to the server.
Send a request to the underlying REST service with the appropriate configuration and authentication. This is a wrapper on top of the browser's fetch API and behaves very similarly but using SDK configuration for the base URL and authentication as well as SDK logging.
(string)
The full path of the resource to fetch from the underlying service. This should include any REST version
or user information. This path will be appended to the base URL according to SDK configuration.
(RequestInit)
An object containing any custom settings that you want to apply to the request. See
fetch API
for a full description and defaults.
// Send a REST request to the server
// Create a request options object following [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/fetch)
const requestOptions = {
method: 'POST',
body: JSON.stringify({
test: 123
})
}
// Note that you will need to subscribe for the `custom` service in order to
// receive notifications from the `externalnotification` service.
const response = await client.request.fetch('/rest/version/1/user/xyz@test.com/externalnotification', requestOptions)
A set of SdpHandlerFunctions for manipulating SDP information. These handlers are used to customize low-level call behaviour for very specific environments and/or scenarios.
Note that SDP handlers are exposed on the entry point of the SDK. They can be added during initialization of the SDK using the config.call.sdpHandlers configuration parameter. They can also be set after the SDK's creation by using the call.setSdpHandlers function.
import { create, sdpHandlers } from 'kandy';
const codecRemover = sdpHandlers.createCodecRemover(['VP8', 'VP9'])
const client = create({
call: {
sdpHandlers: [ codecRemover, <Your-SDP-Handler-Function>, ...]
}
})
// Through the Call API post-instantiation
client.call.setSdpHandlers([ codecRemover, <Your-SDP-Handler-Function>, ...])
This function creates an SDP handler that will remove codecs matching the selectors specified for SDP offers and answers.
In some scenarios it's necessary to remove certain codecs being offered by the SDK to remote parties. For example, some legacy call services limit the SDP length (usually to 4KB) and will reject calls that have SDP size above this amount.
While creating an SDP handler would allow a user to perform this type of manipulation, it is a non-trivial task that requires in-depth knowledge of WebRTC SDP.
To facilitate this common task, the createCodecRemover function creates a codec removal handler that can be used for this purpose. Applications can use this codec removal handler in combination with the call.getAvailableCodecs function in order to build logic to determine the best codecs to use for their application.
call.SdpHandlerFunction
:
The resulting SDP handler that will remove the codec.
import { create, sdpHandlers } from 'kandy';
const codecRemover = sdpHandlers.createCodecRemover([
// Remove all VP8 and VP9 codecs.
'VP8',
'VP9',
// Remove all H264 codecs with the specified FMTP parameters.
{
name: 'H264',
fmtpParams: ['profile-level-id=4d0032', 'packetization-mode=1']
}
])
const client = create({
call: {
sdpHandlers: [codecRemover]
}
})
Sets the selected devices as the default devices. They will be used for audio output for future calls. Changing speaker is supported on browser's that support HTMLMediaElement.setSinkId().
// Set only the default microphone and camera.
client.media.setDefaultDevices({
camera: 'abc123...',
microphone: 'def456...'
});
The SIP Events feature allows an application to communicate with a SIP network integrated
with their Kandy Link instance. The SIP network may generate custom events intended
for an application, which can be handled with the SDK's sip
namespace.
Usage of SIP Events is dependent on your Kandy Link instance. The types of SIP Events can be different based on configurations and components, often being part of a custom solution. As such, the SIP Events feature is presented in a generic manner to be flexible for any possible events.
An example of a common SIP event is "SIP presence". When a user is connected to a SIP phone, the network may generate "phone presence" events when the user starts and ends a call (eg. 'On Call', 'Available'). Applications can subscribe to receive these events for specific users.
A SIP event may either be solicited or unsolicited. Solicited events, such as the "presence" example above, requires the application to subscribe for the event. See the sip.subscribe API for more information about solicited events. Unsolicited events have no prerequisites for being received.
Creates a subscription for a SIP event.
A subscription is required to receive SIP notifications for solicited events. Before creating a SIP subscription, the service for the event type must have been provisioned as part of the user subscription using the services.subscribe API.
Only one SIP subscription per event type can exist at a time. A subscription can watch for events from multiple users at once. Users can be added to or removed from a subscription using the sip.update API at any time.
The SDK will emit a sip:subscriptionChange event when the operations completes. The sip.getDetails API can be used to retrieve the current information about a subscription.
The SDK will emit a sip:eventsChange event when a SIP event is received.
(string)
The name of the SIP event.
(string)
Unique identifier for a client device.
(Array<call.CustomParameter>?)
Custom SIP header parameters for the SIP backend.
// Provision the service for the specific SIP event during user subscription.
// This is required before a SIP subscription for the event can be created.
const services = ['call', 'event:presence', ...]
client.services.subscribe(services)
// Subscribe to receive SIP presence events from two users.
client.sip.subscribe('event:presence', ['userOne@example.com', 'userTwo@example.com'], 'clientId123')
// Subscribe for SIP events with a custom parameter.
const customParameters = [{
name: 'X-nt-GUID',
value: 'GUID123abc'
}]
client.sip.subscribe('event:presence', subscribeUserList, 'clientId123', customParameters)
Updates an existing SIP event subscription.
Allows for adding or removing users from the subscription, and for changing the custom parameters of the subscription.
The SDK will emit a sip:subscriptionChange event when the operations completes. The sip.getDetails API can be used to retrieve the current information about a subscription.
(string)
The name of the SIP event.
(Object)
Name | Description |
---|---|
userLists.subscribeUserList Array<string>
|
List of users to add to the subscription. |
userLists.unsubscribeUserList Array<string>
|
List of users to remove from the subscription. If all users are removed, the event subscription will be deleted. |
(Array<call.CustomParameter>?)
Custom SIP header parameters for the SIP backend.
// Add a user to an existing subscription.
const userLists = {
subscribedUserList: ['userThree@example.com']
}
client.sip.update('event:presence', userLists)
// Simultaneously add and remove users from the subscription.
const userLists = {
subscribedUserList: ['userThree@example.com'],
unsubscribeUserList: ['userOne@example.com']
}
client.sip.update('event:presence', userLists)
Deletes an existing SIP event subscription.
The SDK will emit a sip:subscriptionChange event when the operations completes.
Subscription details will no longer be available using the sip.getDetails API after it has been unsubscribed from.
(string)
The name of the SIP event.
// Delete a SIP subscription.
client.sip.unsubscribe('event:presence')
Retrieve information about a SIP event subscription.
The SDK will track which users are included as part of the subscription and previous notifications received. Each subscription will include a unique ID.
(string?)
The name of a SIP event. If not provided, will retrieve
information for all SIP subscriptions.
Object
:
SIP subscription information. If
eventType
was not provided, will
return an object namespaced by event types.
// Retrieve information about a single SIP subscription.
const { subscribedUsers, notifications } = client.sip.getDetails('event:presence')
// Retrieve information about all current SIP subscriptions.
const subscriptions = client.sip.getDetails()
const { subscribedUsers, notifications } = subscriptions['event:presence']
A change has occurred to a SIP subscription.
This event can be emitted when a new SIP subscription is created (sip.subscribe
API), an existing subscription is updated (sip.update API), or has been
deleted (sip.unsubscribe API). The change
parameter on the event indicates
which scenario caused the event.
When users are added or removed from a subscription through a new subscription or an update,
the subscribedUsers
and unsubscribedUsers
parameters will indicate the users added
and removed, respectively.
The sip.getDetails API can be used to retrieve the current information about a subscription.
(Object)
Name | Description |
---|---|
params.eventType string
|
The name of the SIP event. |
params.change string
|
The change operation that triggered the event. |
params.subscribedUsers Array<string>?
|
List of users added to the subscription as part of the change. |
params.unsubscribedUsers Array<string>?
|
List of users removed from the subscription as part of the change. |
An error has occurred during a SIP event operation.
(Object)
Name | Description |
---|---|
params.error api.BasicError
|
The Basic error object. |
// Listen for the event being emitted.
client.on('sip:error', (params) => {
// Handle the error based on the information.
const { code, message } = params.error
...
})
A SIP event notification has been received.
The event
parameter is the full notification received from the network. The format
of the notification is dependant on its event type. The SDK does not do any
pre-processing of this data.
(Object)
Information about the notification.
Name | Description |
---|---|
params.eventType string
|
The name of the SIP event. |
params.eventId string
|
A unique ID for the event notification. |
params.event Object
|
The full event object. |
params.links Object
|
|
params.links.callId string?
|
The ID of the call this SIP event links to. |
// Listen for the event being emitted.
client.on('sip:eventsChange', (params) => {
// Gather the SIP info specific to the event.
const sipInfo = params.event.genericNotificationParams
// Handle the data based on the event type.
if (params.eventType === 'event:presence') {
const { data, from } = sipInfo
...
}
})
Starts the local video stream and displays it to the user.
(HTMLElement?)
The container to use for local video.
``` javascript
var container = document.getElementById('local-video');
client.media.startPreviewVideo(container);
```
Stops the local video stream created in startPreviewVideo
.
The 'user' namespace allows access to user information for users within the same domain.
The User data object.
Type: Object
(user.UserID)
: The User ID of the user.
(string)
: The email address of the user.
(string)
: The first name of the user.
(string)
: The last name of the user.
(string)
: The URL to get the photo of the user.
(string)
: Whether the user is a "buddy". Values can be "true" or "false".
Fetches information about a User.
The SDK will emit a users:change event after the operation completes. The User's information will then be available.
Information about an available User can be retrieved using the user.get API.
(string)
The User ID of the user.
Fetches information about the current User from directory. Compared to user.fetch API, this API retrieves additional user related information.
The SDK will emit a users:change event after the operation completes. The User's information will then be available.
Information about an available User can be retrieved using the user.get API.
Retrieves information about a User, if available.
See the user.fetch and user.search APIs for details about making Users' information available.
(user.UserID)
The User ID of the user.
user.User
:
The User object for the specified user.
Retrieves information about all available Users.
See the user.fetch and user.search APIs for details about making Users' information available.
Searches the domain's directory for Users.
Directory searching only supports one filter. If multiple filters are provided, only one of the filters will be used for the search. A search with no filters provided will return all users.
The SDK will emit a directory:change event after the operation completes. The search results will be provided as part of the event, and will also be available using the user.get and user.getAll APIs.
(Object)
The filter options for the search.
Name | Description |
---|---|
filters.userId user.UserID?
|
Matches the User ID of the user. |
filters.name string?
|
Matches the firstName or lastName. |
filters.firstName string?
|
Matches the firstName. |
filters.lastName string?
|
Matches the lastName. |
filters.userName string?
|
Matches the userName. |
filters.phoneNumber string?
|
Matches the phoneNumber. |
The 'voicemail' namespace is used to retrieve and view voicemail indicators.
Voicemail functions are all part of this namespace.
Attempts to retrieve voicemail information from the server.
A voicemail:change event is emitted upon completion.
Returns voicemail data from the store.
A voicemail event has been received.
(Object)
An object containing voicemail info.
Name | Description |
---|---|
params.lastUpdated number
|
Timestamp of the last time voicemail data was checked. |
params.newMessagesWaiting boolean
|
Whether there are new messages. |
params.totalVoice number
|
The total number of voicemail messages. |
params.unheardVoice number
|
Number of unheard voicemail messages. |
params.voice Object
|
Object containing individual counts of new, old, urgent voicemails. |
params.fax Object
|
Object containing individual counts of new, old, urgent faxes. |
params.multimedia Object
|
Object containing individual counts of new, old, urgent multimedia messages. |
An error has occurred while attempting to retrieve voicemail data.
(Object)
Name | Description |
---|---|
params.error api.BasicError
|
The Basic error object. |