@kandy-io/uc-sdk-3.x
Version:
The v3 stream of the Kandy UC JavaScript SDK has been deprecated and is not receiving regular updates. The latest version of the SDK can be found at https://github.com/Kandy-IO/kandy-uc-js-sdk.
1,404 lines (876 loc) • 104 kB
Markdown
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
## create
The SDK creation factory. Create an instance of the SDK by calling this factory with the desired configurations.
The SDK instance will be referred as 'api' throughout the rest of the documentation content.
### Parameters
* `config` **[config][1]** The configuration object.
### Examples
```javascript
// Instantiate the SDK.
import { create } from 'kandy'
const client = create({
authentication: { ... },
logs: { ... },
...
});
// Use the SDK's API.
client.on( ... );
```
Returns **[api][2]** The SDK instance.
## config
The configuration object. This object defines what different configuration
values you can use when instantiating the SDK using the [create][3] function.
### config.logs
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][4]. This function will receive a
[LogEntry][5] 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][6] description.
#### Parameters
* `logs` **[Object][7]** Logs configs.
* `logs.logLevel` **[string][8]** Log level to be set. See [logger.levels][9]. (optional, default `'debug'`)
* `logs.handler` **[logger.LogHandler][10]?** 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][11]** Enable the detailed call logger
for v3.X. Requires log level debug. (optional, default `true`)
* `logs.logActions` **([Object][7] | [boolean][11])** Options specifically for action logs when
logLevel is at DEBUG+ levels. Set this to false to not output action logs. (optional, default `false`)
* `logs.logActions.handler` **[logger.LogHandler][10]?** 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][11]** Only output information
about the action itself. Omits the SDK context for when it occurred. (optional, default `false`)
* `logs.logActions.collapsed` **[boolean][11]** Whether logs should be
minimized when initially output. The full log is still output and can be
inspected on the console. (optional, default `false`)
* `logs.logActions.diff` **[boolean][11]** Include a diff of what SDK
context was changed by the action. (optional, default `false`)
* `logs.logActions.level` **[string][8]** Log level to be set
on the action logs (optional, default `'debug'`)
* `logs.logActions.exposePayloads` **[boolean][11]** Allow action payloads
to be exposed in the logs, potentially displaying sensitive information. (optional, default `true`)
### config.authentication
Configuration options for the Authentication feature.
#### Parameters
* `authentication` **[Object][7]** Authentication configs.
* `authentication.subscription` **[Object][7]**
* `authentication.subscription.server` **[string][8]** Hostname of the server to be used for subscription requests.
* `authentication.subscription.protocol` **[string][8]** Protocol to be used for subscription requests. (optional, default `'https'`)
* `authentication.subscription.port` **[Number][12]** Port to be used for subscription requests. (optional, default `443`)
* `authentication.subscription.expires` **[Number][12]** Time duration, in seconds, until a subscription should expire. (optional, default `3600`)
* `authentication.subscription.service` **[Array][13]?** Services to subscribe to for notifications. Default value is \['call', 'IM', 'presence'].
* `authentication.subscription.localization` **[string][8]** (optional, default `English_US`)
* `authentication.subscription.useTurn` **[Boolean][11]** (optional, default `true`)
* `authentication.subscription.notificationType` **[string][8]** (optional, default `Websocket`)
* `authentication.websocket` **[Object][7]**
* `authentication.websocket.server` **[string][8]** Hostname of the server to be used for websocket notifications.
* `authentication.websocket.protocol` **[string][8]** Protocol to be used for websocket notifications. (optional, default `'wss'`)
* `authentication.websocket.port` **[Number][12]** Port to be used for websocket notifications. (optional, default `443`)
* `authentication.earlyRefreshMargin` **[Number][12]** (optional, default `300`)
### config.call
Configuration options for the call feature.
#### Parameters
* `call` **[Object][7]** The call configuration object.
* `call.callDefaults` **[Object][7]?** Default options to be used when making/answering a call.
* `call.callDefaults.isAudioEnabled` **[boolean][11]** Specifies whether audio is enabled or not. (optional, default `true`)
* `call.callDefaults.isVideoEnabled` **[boolean][11]** Specifies whether video is enabled or not. (optional, default `true`)
* `call.callDefaults.sendInitialVideo` **[boolean][11]** Specifies whether to send an initial video stream or not. (optional, default `false`)
* `call.callDefaults.remoteVideoContainer` **[Object][7]?** Specifies the container where video (coming from remote party) is rendered.
* `call.callDefaults.localVideoContainer` **[Object][7]?** Specifies the container where video (coming from local party) is rendered.
* `call.chromeExtensionId` **[string][8]?** ID of the screenshare extension being used for screenshare of Google Chrome.
* `call.recordCallStats` **[boolean][11]** Whether to enable the recording of call statistics as part of app's local storage. (optional, default `false`)
* `call.earlyMedia` **[boolean][11]** Whether to use early media (e.g. for playing incoming tones) as part of an outgoing call. (optional, default `false`)
* `call.callAuditTimer` **[number][12]** Audit time value for calls, as a positive number in milliseconds. (optional, default `30000`)
* `call.activeCallTimeoutMS` **[number][12]** Timeout for an existing ringing call before it gets terminated, as a positive number in milliseconds. (optional, default `120000`)
* `call.ringingFeedback` **[boolean][11]?** When enabled, inform Spidr that RingingFeedback is supported.
* `call.codecsToReplace` **[string][8]?** 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][11]** Sets the video as "inactive" instead of "sendonly" when holding a call. (optional, default `false`)
* `call.forceDisableMediaOnHold` **[boolean][11]** Disables any type of media (e.g. Comfort Noise) from transmitting when call is held locally. (optional, default `false`)
* `call.iceCandidateCollectionTimeoutInterval` **[number][12]** When provided (in milliseconds), ice candidate collection is assumed to be completed if at least one candidate is received within the interval. (optional, default `3000`)
* `call.relayCandidateCollectionTimeoutCycle` **[boolean][11]** When enabled, iceCandidateCollectionTimeoutInterval is restarted until receiving first relay candidate. If the provided cycle limit is reached, ice candidate collection assumed to be completed. (optional, default `false`)
* `call.recordCallStats` **[boolean][11]** When enabled, call statistics are recorded in app's localstorage after the call is terminated. (optional, default `false`)
* `call.callConstraints` **[Object][7]?** Custom RTCPeerConnection constraints to use for calls. Will cause errors if malformed.
* `call.callConstraints.chrome` **[Object][7]?** Custom constraints to be used on Google Chrome.
* `call.callConstraints.firefox` **[Object][7]?** Custom constraints to be used on Mozilla Firefox.
* `call.bundlePolicy` **[string][8]** 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. (optional, default `'DISABLED'`)
* `call.opusConfig` **[Object][7]?** Bandwidth controls to add for Opus audio codec.
* `call.opusConfig.maxPlaybackRate` **[number][12]?** Maximum playback rate, in bits per second. Must be a positive value between 8000 and 48000.
* `call.opusConfig.maxAverageBitrate` **[number][12]?** A bitrate encoding value between 6000 and 510000 bits per second.
* `call.opusConfig.fec` **[number][12]?** 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][12]?** 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][12]?** 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][12]** Interval at which to collect WebRTC logs for calls, in milliseconds. (optional, default `3000`)
* `call.useRelay` **[boolean][11]** Whether we should force connection through the relay candidates (i.e. TURN server). Mostly used for testing. (optional, default `false`)
* `call.trickleIceSupport` **[string][8]** Whether we should advertise and use Trickle ICE. Accepted value is one of: 'none', 'half' or 'full'. (optional, default `'none'`)
* `call.continuity` **[boolean][11]** 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). (optional, default `false`)
* `call.resyncOnConnect` **[boolean][11]** Whether all active calls should be resynched upon connecting or reconnecting to the websocket (requires Kandy Link 4.7.1+). (optional, default `false`)
### config.connectivity
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
#### Parameters
* `connectivity` **[Object][7]** Connectivity configs.
* `connectivity.pingInterval` **[Number][12]** Time in between websocket ping attempts (milliseconds). (optional, default `30000`)
* `connectivity.reconnectLimit` **[Number][12]** Number of failed reconnect attempts before reporting an error. Can be set to 0 to not limit reconnection attempts. (optional, default `5`)
* `connectivity.reconnectDelay` **[Number][12]** Base time between websocket reconnect attempts (milliseconds). (optional, default `5000`)
* `connectivity.reconnectTimeMultiplier` **[Number][12]** 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. (optional, default `1`)
* `connectivity.reconnectTimeLimit` **[Number][12]** Maximum time delay between reconnect attempts (milliseconds). Used in conjunction with the reconnect time multiplier to prevent overly long delays between reconnection attempts. (optional, default `640000`)
* `connectivity.autoReconnect` **[Boolean][11]** Flag to determine whether the SDK will attempt to automatically reconnect after connectivity disruptions. (optional, default `true`)
* `connectivity.maxMissedPings` **[Number][12]** Maximum pings sent (without receiving a response) before reporting an error. (optional, default `3`)
* `connectivity.checkConnectivity` **[Boolean][11]** Flag to determine whether the SDK should check connectivity. (optional, default `true`)
* `connectivity.webSocketOAuthMode` **[string][8]** query will send the bearer access token to authenticate the websocket and none will not send it. (optional, default `query`)
### config.notifications
Configuration options for the notification feature.
#### Parameters
* `notifications` **[Object][7]** The notifications configuration object.
* `notifications.idCacheLength` **[number][12]** Default amount of event ids to remember for de-duplication purposes. (optional, default `100`)
* `notifications.incomingCallNotificationMode` **[string][8]** Communication channel mode used for incoming call notifications. Supported values are 'any-channel' or 'push-channel-only'. (optional, default `'any-channel'`)
* `notifications.pushRegistration` **[Object][7]?** Object describing the server to use for push services.
* `notifications.pushRegistration.server` **[string][8]?** Hostname for the push registration server.
* `notifications.pushRegistration.port` **[string][8]?** Port for the push registration server.
* `notifications.pushRegistration.protocol` **[string][8]?** Protocol for the push registration server.
* `notifications.pushRegistration.version` **[string][8]?** Version for the push registration server.
## call:error
An error has occurred with a call.
### Parameters
* `params` **[Object][7]**
* `params.callId` **[string][8]** The id of the call.
* `params.error` **[api.BasicError][14]** The Basic error object.
## call:forward
A call has successfully been forwarded.
### Parameters
* `params` **[Object][7]**
* `params.callId` **[string][8]** The Id of the call.
## call:join
Calls have been successfully joined.
### Parameters
* `params` **[Object][7]**
* `params.callId` **[string][8]** The ID of the new, joined call.
* `params.joinedCalls` **[Array][13]** The two calls that were joined together.
## call:mediaStateChange
A call's media state has changed.
### Parameters
* `params` **[Object][7]**
* `params.callId` **[string][8]** The Id of the call.
* `params.mediaState` **[string][8]** New media state of the call.
## call:receive
A new incoming call has been received.
### Parameters
* `params` **[Object][7]**
* `params.callId` **[string][8]** The Id of the call.
### Examples
```javascript
client.on('call:receive', function(callId) {
// We have received a call, prompt the user to respond.
promptUser(client.call.getById(callId));
});
```
## call:screenshareChange
Screensharing has been started turned on or off.
### Parameters
* `params` **[Object][7]**
* `params.callId` **[string][8]** The Id of the call.
## call:start
An outgoing call has successfully started.
### Parameters
* `params` **[Object][7]**
* `params.callId` **[string][8]** The Id of the call.
## call:stateChange
A call's state has changed.
### Parameters
* `params` **[Object][7]**
* `params.callId` **[string][8]** The Id of the call.
* `params.state` **[string][8]** New state of the call.
* `params.transition` **[Object][7]** Information about the state change.
* `params.transition.code` **[number][12]** Code representing the reason for the state change.
* `params.transition.reasonText` **[string][8]** Explanation of the status code.
* `params.transition.oldState` **[string][8]** The previous state of the call.
### Examples
```javascript
client.on('call:stateChange', function(params) {
// We are now in call with another user, so update our app to show it.
if(params.state === client.call.states.IN_CALL) {
renderCall(client.call.getById(params.callId));
}
});
```
## devices:change
Available media devices have been changed.
### Parameters
* `params` **[Object][7]**
* `params.devices` **[Object][7]** The devices, separated by device type.
## devices:defaultsChange
A change has been made to default devices used for calls.
### Parameters
* `params` **[Object][7]**
* `params.devices` **[Object][7]** The devices now set as default.
## media:initialize
Media support has been checked.
### Parameters
* `params` **[Object][7]**
* `params.result` **[Object][7]** Results of initializing media.
* `params.result.error` **[boolean][11]** Whether the initialization was successful or not.
* `params.result.code` **[number][12]** A unique code describing the result scenario.
* `params.result.message` **[string][8]** Human readable message of the result.
## videoPreview:change
The status of previewing local video has changed.
### Parameters
* `params` **[Object][7]**
* `params.displaying` **[boolean][11]** Whether the local video preview is being displayed or not.
## videoPreview:error
An error has occurred when changing local video preview status.
### Parameters
* `params` **[Object][7]**
* `params.error` **[api.BasicError][14]** Information about the error.
## api
The 'api' is the type returned by the create function.
It contains various top-level functions that pertain to SDK global instance
as well as several nested namespaces that pertain to various features (e.g. call, contacts, presence, etc).
### getVersion
Returns the current version of the API.
### destroy
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.
#### Examples
```javascript
// 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( ... )
```
### getConfig
Gets the current configuration Object. This is the object that is initially set as part of SDK creation using 'create' function.
Returns **[Object][7]** A configuration Object.
### updateConfig
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][15] 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:
1. Update the config for removeH264Codecs using the [updateConfig][16] API.
2. Update the sdp handler list using the [setSdpHandlers][17] API and provide any client defined SDP handler functions.
NOTE: You can get the currently defined SDP handler functions with the [getConfig][18] API.
Please note that the object provided to the `updateConfig` API may be different
than the object retrieved from the [getConfig][18] 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][19] section.
#### Parameters
* `newConfigValues` **[Object][7]** Key-value pairs that will be placed into the store. See [config][19] for details on what key-value pairs are available for use.
#### Examples
```javascript
// 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'
}
})
```
### on
Add an event listener for the specified event type. The event is emitted by the SDK instance.
#### Parameters
* `type` **[string][8]** The event type for which to add the listener.
* `listener` **[Function][20]** The listener for the event type. The parameters of the listener depend on the event type.
#### Examples
```javascript
// Listen for events of a specific type emitted by the SDK.
client.on('dummy:event', function (params) {
// Handle the event.
})
```
* Throws **[Error][21]** Invalid event type
### off
Removes an event listener for the specified event type. The event is emitted by the SDK instance.
#### Parameters
* `type` **[string][8]** The event type for which to remote the listener.
* `listener` **[Function][20]** The listener to remove.
<!---->
* Throws **[Error][21]** Invalid event type
### subscribe
Adds a global event listener to SDK instance.
#### Parameters
* `listener` **[Function][20]** The event listener to add. The parameters are (type, ...args), where args depend on the event type.
<!---->
* Throws **[Error][21]** Listener not a function
### unsubscribe
Removes a global event listener from SDK instance.
#### Parameters
* `listener` **[Function][20]** The event listener to remove.
<!---->
* Throws **[Error][21]** Listener not a function
### connect
Connect with user credentials to any backend services that the SDK instance deals with.
#### Parameters
* `credentials` **[Object][7]** The credentials object.
* `credentials.username` **[string][8]** The username including the application's domain.
* `credentials.password` **[string][8]** The user's password.
* `credentials.authname` **[string][8]?** The user's authorization name.
* `options` **[Object][7]?** The options object for non-credential options.
* `options.forceLogOut` **[boolean][11]?** Force the oldest connection to log out if too many simultaneous connections. Link only.
* `options.clientCorrelator` **[string][8]?** Unique ID for the client. This is used by the platform to identify an instance of the application used by the specific device.
#### Examples
```javascript
client.connect({
username: 'alfred@example.com',
password: '********'
authname: '********'
}, {
forceLogOut: true
});
```
**Meta**
* **deprecated**: Since version 4.19.0. Please see [setCredentials][22] and [subscribe][23] for new method of connecting.
### connect
Connect by providing an access token to any backend services that the SDK instance deals with.
You can optionally provide a refresh token and the SDK will automatically get new access tokens.
#### Parameters
* `credentials` **[Object][7]** The credentials object.
* `credentials.username` **[string][8]** The username without the application's domain.
* `credentials.accessToken` **[string][8]** An access token for the user with the provided user Id.
* `credentials.refreshToken` **[string][8]?** A refresh token for the same user.
* `credentials.expires` **[number][12]?** The time in seconds until the access token will expire.
* `options` **[Object][7]?** The options object for non-credential options.
* `options.clientCorrelator` **[string][8]?** Unique ID for the client. This is used by the platform to identify an instance of the application used by the specific device.
#### Examples
```javascript
client.connect({
username: 'alfred@example.com',
accessToken: 'AT0V1fswAiJadokx1iJMQdG04pRf',
refreshToken: 'RTG9SV3QAoJaeUSEQCZAHqrhde1yT',
expires: 3600
});
```
**Meta**
* **deprecated**: Since version 4.19.0. Please see [setCredentials][22] and [subscribe][23] for new method of connecting.
### connect
Connect by providing a refresh token to any backend services that the SDK instance deals with.
#### Parameters
* `credentials` **[Object][7]** The credentials object.
* `credentials.username` **[string][8]** The username without the application's domain.
* `credentials.refreshToken` **[string][8]** A refresh token for the same user.
* `credentials.expires` **[number][12]?** The time in seconds until the access token will expire.
* `options` **[Object][7]?** The options object for non-credential options.
* `options.clientCorrelator` **[string][8]?** Unique ID for the client. This is used by the platform to identify an instance of the application used by the specific device.
#### Examples
```javascript
client.connect({
username: 'alfred@example.com',
refreshToken: 'RTG9SV3QAoJaeUSEQCZAHqrhde1yT'
expires: 3600
});
```
**Meta**
* **deprecated**: Since version 4.19.0. Please see [setCredentials][22] and [subscribe][23] for new method of connecting.
### connect
Connect by providing an oAuth token to any backend services that the SDK instance deals with.
#### Parameters
* `credentials` **[Object][7]** The credentials object.
* `credentials.username` **[string][8]** The username without the application's domain.
* `credentials.oauthToken` **[string][8]** An OAuth token provided by an outside service.
* `options` **[Object][7]?** The options object for non-credential options.
* `options.clientCorrelator` **[string][8]?** Unique ID for the client. This is used by the platform to identify an instance of the application used by the specific device.
#### Examples
```javascript
client.connect({
username: 'alfred@example.com',
oauthToken: 'RTG9SV3QAoJaeUSEQCZAHqrhde1yT'
});
```
**Meta**
* **deprecated**: Since version 4.19.0. Please see [setCredentials][22] and [subscribe][23] for new method of connecting.
### disconnect
Disconnects from the backend. This will close the websocket and you will stop receiving events.
**Meta**
* **deprecated**: Since version 4.19.0. Please see [unsubscribe][24] for new method of disconnecting.
### updateToken
If you're authenticating with tokens that expire and have not provided a refresh token to the `connect` function, you can update your access token with `updateToken` before it expires to stay connected.
#### Parameters
* `credentials` **[Object][7]** The credentials object.
* `credentials.username` **[string][8]** The username without the application's domain.
* `credentials.accessToken` **[string][8]** An access token for the user with the provided user Id.
### updateToken
If you're authenticating with tokens that expire and have not provided a refresh token to the `connect` function, you can update your access token with `updateToken` before it expires to stay connected.
#### Parameters
* `credentials` **[Object][7]** The credentials object.
* `credentials.username` **[string][8]** The username without the application's domain.
* `credentials.oauthToken` **[string][8]** An OAuth token provided by an outside service.
#### Examples
```javascript
client.updateToken({
username: 'alfred@example.com',
oauthToken: 'RTG9SV3QAoJaeUSEQCZAHqrhde1yT'
});
```
### getUserInfo
Retrieves information about the current user.
Returns **[Object][7]** user The user data.
Returns **[string][8]** 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.
Returns **[string][8]** user.token The current access token.
### getConnection
Get the connection state.
Returns **[Object][7]** connection The connection state.
Returns **[boolean][11]** connection.isConnected Whether the authenticated user is currently connected.
Returns **[boolean][11]** connection.isPending Whether the authenticated user's connection is currently pending.
Returns **[Object][7]** connection.error The error object if an error occurred.
Returns **[string][8]** connection.error.message The error message.
Returns **[string][8]** connection.error.stack The stack trace of the error.
### getServices
Retrieves the services that the user is subscribed for.
Returns **[Array][13]** A list of subscribed-to services.
### subscriptionStates
Possible subscription states of the user.
#### Properties
* `FULL` **[string][8]** All requested feature subscriptions exist.
* `PARTIAL` **[string][8]** Some feature subscriptions exist.
* `NONE` **[string][8]** No feature subscriptions exist.
### disconnectReasons
Possible reasons for disconnecting.
#### Properties
* `GONE` **[string][8]** Connection was terminated by the server
* `LOST_CONNECTION` **[string][8]** Internet connection was lost
* `WS_OVERRIDDEN` **[string][8]** WebSocket was overridden by the server
### setCredentials
Sets the user credentials necessary to make requests to the platform.
#### Parameters
* `credentials` **[Object][7]** The credentials object.
* `credentials.username` **[string][8]** The username including the application's domain.
* `credentials.password` **[string][8]** The user's password.
* `credentials.authname` **[string][8]?** The user's authorization name.
#### Examples
```javascript
client.setCredentials({
username: 'alfred@example.com',
password: '********'
authname: '********'
});
```
### BasicError
The Basic Error object. Provides information about an error that occurred in the SDK.
Type: [Object][7]
#### Properties
* `code` **[string][8]** The code of the error. If no code is known, this will be 'NO_CODE'.
* `message` **[string][8]** A human-readable message to describe the error. If no message is known, this will be 'An error occurred'.
### auth:change
Authentication state has changed. You can get the new state by calling `getConnection()`.
#### Parameters
* `params` **[Object][7]**
* `params.reason` **[string][8]** The cause of the authentication change, provided in the event of an unsolicited disconnection. See the `disconnectReasons` API for possible values.
### auth:error
There was an error with authentication.
#### Parameters
* `params` **[Object][7]**
* `params.error` **[api.BasicError][14]** The Basic error object.
### auth:resub
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.
#### Parameters
* `params` **[Object][7]**
* `params.attemptNum` **[number][12]** The attempt number of this resubscription.
* `params.isFailure` **[boolean][11]** Whether the resubscription failed or not.
* `params.error` **[api.BasicError][14]?** The Basic error object.
### auth:credentialsSet
The information (credentials) needed for connecting have been set.
## AudioBridge
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.
### create
Creates a local bridge that can be used to join audio calls.
Returns **[string][8]** ID used to identify the bridge.
### close
Closes an existing audio bridge.
#### Parameters
* `bridgeId` **[string][8]** Identifier for the bridge to act on.
### addCall
Adds a call to the specified local audio bridge.
#### Parameters
* `bridgeId` **[string][8]** Identifier for the bridge to act on.
* `callId` **[string][8]** Identifier for the call to add.
### removeCall
Remove a specified call from the local audio bridge.
#### Parameters
* `bridgeId` **[string][8]** Identifier for the bridge to act on.
* `callId` **[string][8]** Identifier for the call to remove.
### mute
Mute the local audio for all of the calls on the bridge.
#### Parameters
* `bridgeId` **[string][8]** Identifier for the bridge to act on.
### unmute
Unmute the local audio for all of the calls on the bridge.
#### Parameters
* `bridgeId` **[string][8]** Identifier for the bridge to act on.
### silence
Silence the remote audio for all of the calls on the bridge.
#### Parameters
* `bridgeId` **[string][8]** Identifier for the bridge to act on.
### unsilence
Un-silence the remote audio for all of the calls on the bridge.
#### Parameters
* `bridgeId` **[string][8]** Identifier for the bridge to act on.
### getAll
Retrieve information about audio bridges.
Returns **[Array][13]** List of active audio bridges.
### getBridgeCalls
Retrieve all calls currently part of an audio bridge.
#### Parameters
* `bridgeId` **[string][8]** The ID of the bridge whose calls we wish to retrieve
Returns **[Array][13]** List of calls currently part of the specified audio bridge.
### audioBridge:change
A change has occurred in an audio bridge.
#### Parameters
* `params` **[Object][7]**
* `bridgeId` **[string][8]** The bridge that the change occurred on.
### audioBridge:error
An error occurred while performing an audio bridge operation.
#### Parameters
* `params` **[Object][7]**
* `params.error` **[api.BasicError][14]** The Basic error object.
## callHistory
The 'call.history' namespace is used to retrieve and inspect the authenticated
users call logs.
Functions below are all part of this namespace.
### fetch
Fetches the list of call logs and stores them locally. The API
[CallHistory.get][25] can then be used to get
the logs from local state after it has been updated.
#### Parameters
* `amount` **[number][12]** The number of records to retrieve. (optional, default `50`)
* `offset` **[number][12]** Starting offset for records to retrieve. (optional, default `0`)
### remove
Deletes the specified call log.
#### Parameters
* `recordId` **[number][12]** The ID of the call log to be removed.
### clear
Deletes all call logs.
### get
Gets the list of call logs cached locally. The event
`callHistory:changed` is used to indicate the local state of logs
has been updated.
#### Examples
```javascript
client.on('callHistory:change', function() {
// Get all call logs when they've been updated.
let callLogs = client.call.history.get();
});
```
Returns **[Array][13]** A list of call log records, ordered by latest first.
### getCache
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][26] API. This allows an
application to persist the information across SDK instances when the
backend environment does not support the CallHistory feature.
Returns **[string][8]** A stringified list of call log records from the cache, ordered by latest first.
### setCache
Sets the cached call history data, expects stringified data as it will be parsed.
The data can be retrieved from the [call.history.getCache][27] API. This allows an
application to persist the information across SDK instances when the
backend environment does not support the CallHistory feature.
#### Parameters
* `data` **[string][8]** The stringified call history data to store in the cache.
### callHistory:change
Call history state has been updated. See [CallHistory.get][25] to retrieve new state.
### callHistory:error
An error occurred while performing a call history operation.
#### Parameters
* `params` **[Object][7]**
* `params.error` **[api.BasicError][14]** The Basic error object.
### callHistoryCache:change
Call history cached state has been updated
## Calls
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.
### getAll
Retrieves the state of calls made during the current session.
#### Examples
```javascript
let calls = client.call.getAll();
let currentCalls = calls.filter(call => {
return call.state === client.call.states.IN_CALL;
});
```
Returns **[Array][13]** Call objects.
### getById
Retrieves a call from state with a specific call ID.
#### Parameters
* `callId` **[string][8]** The ID of the call to retrieve.
Returns **[Object][7]** A call object.
### changeInputDevices
Changes camera and microphone for the specified call.
The call will use the current selected default devices.
#### Parameters
* `callId` **[string][8]** The ID of the call to act upon.
### changeSpeaker
Changes speaker used for call audio output.
Supported on browser's that support HTMLMediaElement.setSinkId().
#### Parameters
* `speakerId` **[string][8]** ID of the speaker to use for call audio.
### states
States of a call.
#### Properties
* `IN_CALL` **[string][8]** The call is on-going.
* `RINGING` **[string][8]** The call has been established and is waiting for a user response.
* `ENDED` **[string][8]** The call has been terminated.
* `ON_HOLD` **[string][8]** The call has been put on hold locally.
* `ON_REMOTE_HOLD` **[string][8]** The call has been put on hold remotely.
#### Examples
```javascript
client.on('call:stateChange', function(callInfo) {
if(callInfo.state === client.call.states.ENDED) {
// Call has ended.
}
});
```
### mediaStates
State of the media connection within a call.
#### Properties
* `NEW` **[string][8]** A new media connection process has started.
* `CHECKING` **[string][8]** Media is searching for a connection.
* `CONNECTED` **[string][8]** Media has found a connection, but may still be searching for a better connection to use.
* `COMPLETED` **[string][8]** Media has finished searching and been established. Audio/video should now be flowing on the call.
* `FAILED` **[string][8]** Media was not able to find a connection. Audio/video will not flow.
* `DISCONNECTED` **[string][8]** The media connection has lost its connection and is trying to recover.
* `CLOSED` **[string][8]** The media connection has shut down.
### make
Start an outgoing call.
#### Parameters
* `callee` **[string][8]** Full user ID of the call recipient.
* `options` **[Object][7]?** Call options.
* `options.from` **[string][8]?** Sets the display name of the caller to be sent alongside the username of the user.
* `options.isVideoEnabled` **[boolean][11]** Whether to enable video during the call. If false, you cannot start video mid-call. (optional, default `true`)
* `options.contact` **[Object][7]?** Object containing firstName and lastName of caller.
* `options.sendInitialVideo` **[boolean][11]** Whether to start the call sending the local video stream. (optional, default `false`)
* `options.isAudioEnabled` **[boolean][11]** Whether to enable audio during the call. Setting this to false will disable audio for the call. (optional, default `true`)
* `options.webrtcdtls` **[boolean][11]** Whether to enable DTLS for WebRTC calls. (optional, default `true`)
* `options.videoResolution` **[Object][7]?** The object to configure the local video resolution.
* `options.videoResolution.height` **[number][12]?** The height in pixels of the local video.
* `options.videoResolution.width` **[number][12]?** The width in pixels of the local video.
* `options.customParameters` **[Array][13]<{name: [string][8], value: [string][8]}>?** Custom SIP header parameters for the SIP backend.
* `options.remoteVideoContainer` **[HTMLElement][28]?** The HTML element to use as a container for the remote video.
* `options.localVideoContainer` **[HTMLElement][28]?** The HTML element to use as a container for the local video.
* `options.normalizeAddress` **[boolean][11]** Whether to enable normalization of callee address. (optional, default `false`)
#### Examples
```javascript
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"
}
]
});
```
Returns **[string][8]** Id of the outgoing call.
### answer
Answer an incoming call.
#### Parameters
* `callId` **[string][8]** The ID of the call to answer.
* `options` **[Object][7]?** Call options.
* `options.isVideoEnabled` **[boolean][11]?** Whether to enable video during the call. If false, you cannot start video mid-call.
* `options.sendInitialVideo` **[boolean][11]?** Whether to start the call sending the local video stream.
* `options.isAudioEnabled` **[boolean][11]** Whether to enable audio during the call. Setting this to false will disable audio for the call. (optional, default `true`)
* `options.videoResolution` **[Object][7]?** The object to configure the local video resolution.
* `options.videoResolution.height` **[number][12]?** The height in pixels of the local video.
* `options.videoResolution.width` **[number][12]?** The width in pixels of the local video.
* `options.localVideoContainer` **[HTMLElement][28]?** The HTML element to use as a container for the local video.
* `options.remoteVideoContainer` **[HTMLElement][28]?** The HTML element to use as a container for the remote video.
### ignore
Ignore an incoming call.
#### Parameters
* `callId` **[string][8]** The ID of the call to ignore.
### reject
Reject an incoming call.
#### Parameters
* `callId` **[string][8]** The ID of the call to reject.
### end
End an on-going call.
#### Parameters
* `callId` **[string][8]** Id of the call to end.
### mute
Mute the local audio stream on an ongoing call.
#### Parameters
* `callId` **[string][8]** The ID of the call being acted on.
### unmute
Unmute the local audio stream on an ongoing call.
#### Parameters
* `callId` **[string][8]** The ID of the call being acted on.
### silence
Silence the remote audio on an ongoing call.
#### Parameters
* `callId` **[string][8]** The ID of the call being acted on.
### unsilence
Un-silence the remote audio on an ongoing call.
#### Parameters
* `callId` **[string][8]** The ID of the call being acted on.
### getCustomParameters
Retrieves a call's customParameters.
#### Parameters
* `callId` **[string][8]** The ID of the call to retrieve custom parameters.
Returns **[Array][13]<{name: [string][8], value: [string][8]}>** Custom parameters of the call.
### setCustomParameters
Set custom parameters on an ongoing call.
#### Parameters
* `callId` **[string][8]** The ID of the call being acted on.
* `customParameters` **[Array][13]<{name: [string][8], value: [string][8]}>** Custom parameters for the call.
#### Examples
```javascript
// Set custom parameters for call.
client.call.setCustomParameters(
callId,
[
{ "name": "X-GPS",
"value": "42.686032,23.344565"
}
]
});
```
### startVideo
Start local video stream for an ongoing call.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
* `options` **[Object][7]?** Options for the video stream.
* `options.videoResolution` **[Object][7]?** The video resolution configuration object.
* `options.videoResolution.height` **[number][12]?** The height of the outgoing video in pixels.
* `options.videoResolution.width` **[number][12]?** The width of the outgoing video in pixels.
### stopVideo
Stop local video for an ongoing call.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
### hold
Put an ongoing call on hold.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
### unhold
Return a held call to ongoing.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
### startScreenshare
Starts sharing a screen over a call.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
* `options` **[Object][7]**
* `options.mediaSourceId` **[string][8]** Id of the media screen to share.
* `options.height` **[Number][12]** The height of the video stream to send. (optional, default `768`)
* `options.width` **[Number][12]** The width of the video stream to send. (optional, default `1024`)
* `options.frameRate` **[Number][12]** The number of frames per second to request. (optional, default `15`)
### stopScreenshare
Stops sharing a screen over a call.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
### sendDTMF
Send a DTMF tone over a call.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
* `tone` **[number][12]** DTMF tone to send. Valid values are \[0,1,2,3,4,5,6,7,8,9,#].
### sendCustomParameters
Explicitly send the current custom parameters for a call.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
### forwardCall
Forward an incoming call to another user.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
* `destination` **[string][8]** The user to forward the call to.
### directTransfer
Transfer a call to another user.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
* `destination` **[string][8]** The user to transfer the call to.
### consultativeTransfer
Transfer a call to another user.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
* `destinationCallId` **[string][8]** The callId to transfer the call to.
### join
Join two calls (both must be on hold and audio only). The joined call can be referenced via callId.
#### Parameters
* `callId` **[string][8]** Id of the call being acted on.
* `destinationCallId` **[string][8]** The callId to join the call with.
## clickToCall
The clickToCall namespace is used to bridge a call between two specified devices
### make
Attempts to establish a call between two specified devices
#### Parameters
* `caller` **[string][8]** A string representing the person making the call
* `callee` **[string][8]** A string representing the person receiving the call
Returns **[string][8]** callId A unique id representing the call
### get
Gets all local clickToCall calls
Returns **[Array][13]** A list of clickToCall records, ordered by earliest requestTime
### clickToCall:start
ClickToCall has successfully started.
#### Parameters
* `params` **[Object][7]**
* `params.callId` **[string][8]** A unique id representing the call made
### clickToCall:error
ClickToCall had an error.
#### Parameters
* `params` **[Object][7]**
* `params.callId` **[string][8]** A unique id representing the call made
* `params.error` **[api.BasicError][14]** The Basic error object.
## connection
The 'connection' namespace is used to connect and maintain connections between
the SDK and one or more backend servers.
### WSConnectionObject
Information about a websocket connection.
Can be retrieved using the [connection.getSocketState][29] API.
Type: [Object][7]
#### Properties
* `connected` **[boolean][11]** The state of the websocket connection.
* `pinging` **[boolean][11]** True if the client has sent a ping to the server and is still waiting for a pong response.
* `method` **[Object][7]** Information about how the websocket is being used.
* `method.type` **[string][8]?** How the websocket is staying connected.
* `method.responsibleParty` **[string][8]?** Who is responsible for keeping the connection alive.
* `platform` **[string][8]** The SDK platform being used.
* `pingInterval` **[number][12]** How often the client will ping the server to test for websocket connectivity.
* `reconnectLimit` **[number][12]** How many times the SDK will try to reconnect a disconnected websocket.
* `reconnectDelay` **[number][12]** How long the SDK will wait before retrying websocket reconnection.
* `reconnectTimeMultiplier` **[number][12]** 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.
* `reconnectTimeLimit` **[number][12]** Maximum time delay between reconnect attempts (milliseconds). Used in conjunction with `reconnectTimeMultiplier` to prevent overly long delays between reconnection attempts.
* `autoReconnect` **[boolean][11]** Indicates if the SDK should automatically try reconnecting a disconnected websocket.
* `maxMissedPings` **[number][12]** How many missed pings before the SDK stops trying to reconnect a disconnected websocket.
* `webSocketOAuthMode` **[string][8]** The mode used for authenticating with the server.
* `wsInfo` **[Object][7]** Information required to connect a websocket to the server.
* `wsInfo.protocol` **[string][8]?** The protocol to use to connect a websocket.
* `wsInfo.server` **[string][8]?** The domain name or IP address of the server to connect to.
* `wsInfo.port` **[number][12]?** The port of the server to connect to.
* `wsInfo.url` **[string][8]?** The URL path to use to request a websocket connection.
* `wsInfo.params` **[string][8]?** Any additional params that might be required by the server to establish the websocket connection.
* `lastContact` **[number][12]** The date and time that the last know