Variables
| Variable | Description |
|---|---|
version | Returns current version of the Plivo SDK. |
isLoggedIn | Returns true if the user is logged in and false otherwise. |
Methods
| Method | Description |
|---|---|
login(username, password) | Register a Plivo endpoint using username and password credentials. |
loginWithAccessToken(accessToken) | Register a Plivo endpoint using a JSON Web Token (JWT). Added in v2.2.16. |
loginWithAccessTokenGenerator(accessTokenObject) | Register a Plivo endpoint using a JWT generator object that provides tokens dynamically. Added in v2.2.16. |
logout() | Log out from the registered endpoint. |
| call(number, extraHeaders) | Call a number or SIP address. ‘number’ takes a String value and ‘extraHeaders’ takes a JSON object. Extra headers should start with X-PH. Example of ‘extraHeaders’: {‘X-PH-Test1’: ‘test1’, ‘X-PH-Test2’: ‘test2’} Note: Browser SDK supports specific characters in extra headers. Those include [A-Z], [a,z], [0-9]. Additionally, special characters +-_() are also allowed. Any other characters apart from these are ignored by Browser SDK. |
answer(callUUID, actionOnOtherIncomingCalls) | Answer an incoming call. When callUUID is given, the SDK will attempt to answer the incoming call identified by it. When callUUID is not given, the SDK will attempt to answer the most recent ringing call. When callUUID is invalid, the SDK will return false with an error log. actionOnOtherIncomingCalls is Optional - Possible string values: reject — This is the default value. Other incoming calls (if any) are rejected.ignored — Other incoming calls (if any) stop ringing locally but ring for the caller. These incoming calls cannot be answered after ignored.letring — Other incoming calls ring silently in local and continue to ring for the caller. These incoming calls can be answered until they stop ringing. |
hangup() | Hang up the ongoing call. |
reject(callUUID) | Reject an incoming call. When callUUID is given, the SDK attempts to reject the ringing call it identifies. When callUUID is not given or an invalid callUUID is given, the SDK attempts to answer the most recent ringing call. |
ignore(callUUID) | Stops the incoming sound (ring) and sets the call state to ignored, but does not send a hangup message to the dialing party. The incoming call keeps ringing for the called party until the call times out.When callUUID is given, the SDK attempts to ignore the incoming call it identifies. When callUUID is not given or an invalid callUUID is given, the SDK attempts to ignore the most recent ringing call. |
sendDtmf(digit) | Send the digits as DTMF.digit can be any numeric one-character strings or ”*” or ”#“. |
| mute() | Mutes the mic. |
| unmute() | Unmutes the mic. |
| setRingTone(url or boolean) | Configures the ringtone played locally by the browser for incoming calls. true (default) — default tone is played during incoming call false — no ringtone is played during incoming call url — media at the URL is played during incoming call |
setRingToneBack(url or boolean) | Use this function to configure the ringtone played locally by the browser when an outgoing call starts ringing.true (default) — the default tone is played when an outbound call rings. Note that ringtone and pre-answer announcements passed by Plivo’s media servers will not be played.false — ringtone and pre-answer announcements received from Plivo’s media servers are playedurl — remote ringtone is paused and media URL passed is played during outbound call ringing status. |
setConnectTone(boolean) | true (default) — Dial tone plays while the call is being connected.false — No dial tone plays. |
setDebug(debug) | Set the log level of the SDK. Allowed values: OFF, ERROR, WARN, INFO, DEBUG, ALL |
| getPeerConnection() | Returns a RTCPeerConnection object. Example: { status: ‘success’, pc: RTCPeerConnection } |
| submitCallQualityFeedback(callUUID, starRating, issues, note, sendConsoleLogs) | callUUID is a mandatory string parameter used to identify the call the feedback belongs to. You can get the callUUID from getCallUUID() or getLastCallUUID().starRating is a mandatory integer parameter with a value from 1 to 5. For a score from 1 to 4, issues parameter is mandatory; it is optional for a score of 5.issues is an array and must have at least one of these reasons for a starRating value from 1 to 4: AUDIO_LAG, BROKEN_AUDIO, CALL_DROPPPED, CALLERID_ISSUES, DIGITS_NOT_CAPTURED, ECHO, HIGH_CONNECT_TIME, LOW_AUDIO_LEVEL, ONE_WAY_AUDIO, ROBOTIC_AUDIO, OTHERSnote is an optional string attribute for user remarks.sendConsoleLogs is an boolean optional paramter with default value false. Set to true to enable Plivo’s team to collect and analyze Browser SDK’s logs so we can better understand the issue. |
getCallUUID() | Returns a string call UUID if a call is active, else returns null. |
getLastCallUUID() | Returns the call UUID of the latest answered call. Useful if you want to send feedback for the last call. |
startNoiseReduction() | Starts noise reduction. |
stopNoiseReduction() | Stops noise reduction. |
isConnected() | This function returns a boolean value indicating whether the WebSocket is connected. It serves to check the status of the WebSocket connection before attempting to re-initiate it. |
isConnecting() | This function returns a boolean value indicating whether the WebSocket connection is currently in progress. It serves to check the status of the WebSocket connection before attempting to re-initiate it. |
isRegistered() | This function returns a boolean value indicating whether the registration is sucessful. |
register() | This method will register the SDK once it is connected to Plivo servers. The onWebSocketConnected event will be triggered when the SDK is successfully connected to the Plivo servers. |
unregister() | This method will unregister the SDK while keeping it connected to Plivo servers. |
disconnect() | This method will disconnect the SDK from Plivo servers and unregister it. |
getContactUri() | Returns a contact URI string that can be used to redirect a call to different tabs, typically used in multi-tab scenarios. |
redirect(uri) | This method allows redirecting a call to the specified URI, directing it to the required tab. |
getCurrentSession() | Returns the current active session. If there is no active session, it returns null; otherwise, it returns the active session object. |
setIdentifier() | Helps to uniquely identify a tab. |
webRTC() | Returns true if webRTC is supported and false if not. |
supportedBrowsers() | Returns a string listing the browsers supported by the SDK. |
getIncomingCalls() | Returns an array of all current incoming calls when allowMultipleIncomingCalls is enabled. |
getErrorStringByErrorCodes(errorCode) | Returns a human-readable error string for a given error code. |
Audio Device API
Methods
| Method | Description |
|---|---|
availableDevices(filter) | Returns promise that resolves with an array of device objects. The filter parameter is optional and takes a String value. Pass input to filter by input audio devices, output to filter by output audio devices, null to get all audio devices. Wrapper for MediaDevices.enumerateDevices() that filters out non-audio devices.Note : 1. When media permission is not given by users, labels do not appear. In this case, to get labels for a device, use revealAudioDevices(), then call availableDevices(). 2. Device ID remains the same, unless the domain changes or private browsing mode is used. Refer: MediaDeviceInfo.deviceId 3. Device Enumerator API from browser can also be used to list devices IDs and labels — enumerateDevices. |
revealAudioDevices(arg) | Returns a promise that resolves with success if user allows media permission. If returnStream is passed as an argument, the promise will resolve with the MediaStream object. |
Objects
| Object | Methods and Parameters | Description |
|---|---|---|
microphoneDevices | set(deviceID)get()reset() | set takes the deviceID parameter and sets it as the default input device for taking input audio. The deviceID parameter is mandatory and takes a String value.get returns the input audio device ID that is set.reset removes any input audio device ID that is already set. |
speakerDevices | set(deviceID)get()reset()media(source) | set sets the audioDevice ID as default speaker device for DTMF and remote audio. The deviceID parameter is mandatory and takes a String value.get returns the speaker device ID that is set.reset removes any speaker device ID that is already set.media takes dtmf or ringback as a source parameter and returns the corresponding HTML audio element. This parameter is mandatory. |
ringtoneDevices | set(deviceID)get()reset()media | set takes the deviceID parameter and sets it as the ringtone device for playing an incoming call ringtone. The deviceID parameter is mandatory and takes a String value.get returns the ringtone device ID that is set.reset removes any ringtone device ID that is already set.media returns the HTML audio element for playing the ringtone. |
Events
| Event | Description |
|---|---|
onLogin | Occurs when a login is successful. |
onLoginFailed(cause) | Occurs when a login has failed. cause returns the login failure reason. |
onLogout | Occurs when a logout is successful. |
onCalling | Occurs when a call is initiated. |
onCallRemoteRinging(callInfo) | Occurs when the call is initiated towards the remote end from the plivo servers during an outbound call. |
onCallConnected(callInfo) | Occurs when the PSTN remote end starts ringing during an outbound call. This event is not applicable for Multi-Party Call (MPC) or Conference based calls. |
onCallAnswered(callInfo) | Occurs when an outbound or an inbound call is answered. |
onMediaConnected(callInfo) | Occurs when the media connection is established. |
onCallTerminated(hangupInfo, callInfo) | Occurs when an outbound or an inbound call has ended. |
remoteAudioStatus(bool) | Provides a boolean value indicating audio activity from the remote party. True denotes the reception of an audio packet, while False indicates the absence of audio packet reception from the other end. This feature is exclusively accessible in conference or Multi-Party Call (MPC) calls. |
onIncomingCall(callerID, extraHeaders, callInfo, callerName) | Occurs when there is an incoming call. callerID provides the caller ID, callerName provides the caller name set by the initiator of the call, and extraHeaders return the X-Headers from Plivo. |
onIncomingCallCanceled(callInfo) | Occurs when an incoming call is canceled by the caller. |
onIncomingCallIgnored(callInfo) | Occurs when an incoming call is successfully ignored using the ignore(callUUID) function. |
onCallFailed(cause, callInfo) | Occurs when an outbound or an inbound call fails. cause returns the reason for call failing.Possible error events: INVALID_ACCESS_TOKENINVALID_ACCESS_TOKEN_HEADERINVALID_ACCESS_TOKEN_ISSUERINVALID_ACCESS_TOKEN_SUBJECTACCESS_TOKEN_NOT_VALID_YETACCESS_TOKEN_EXPIREDINVALID_ACCESS_TOKEN_SIGNATUREINVALID_ACCESS_TOKEN_GRANTSEXPIRATION_EXCEEDS_MAX_ALLOWED_TIMEMAX_ALLOWED_LOGIN_REACHED |
onMediaPermission(event) | Occurs when media permission has been granted. event returns the stream access status. The success event returns {'status':'success','stream':true}. On failure the event returns {'status':'failure','error':errorName}. |
onWebrtcNotSupported | Occurs when browser does not support WebRTC. |
mediaMetrics | Works only for Chrome. Object sent in the event callback: high_jitter: when the jitter is higher than 30 ms for three out of last five samples. { group: ‘network’, level: ‘warning’, type: ‘high_jitter’, value: ‘<current jitter value>’, active: true || false, //Will be false when value goes to normal level. desc: ‘jitterLocalMeasures’ || ‘jitterRemoteMeasures’, stream: ‘local || remote’ } high_rtt: When the RTT is higher than 400 ms for three out of last five samples. { group: ‘network’, level: ‘warning’, type: ‘high_rtt’, value: ‘<average rtt value>’, active: true || false, //Will be false when value goes to normal level. desc: ‘high latency’, stream: ‘None’ } high_packetloss: When the packet loss is > 10% for Opus and loss > 20% PCMU. { group: ‘network’, level: ‘warning’, type: ‘high_packetloss’, value: ‘<average packet loss value>’;, active: true || false, //Will be false when value goes to normal level. desc: ‘packetLossLocalMeasure’ || ‘packetLossRemoteMeasure’, stream: ‘local || remote’ } low_mos: When sampled MOS is < 3 for three out of last five samples, no_microphone_access When we detect one way audio (<80 bytes sent in three seconds). { group: ‘network’, level: ‘warning’, type: ‘low_mos’, value: ‘<current mos value>’, active: true || false, //Will be false when value goes to normal level. desc: ‘mosRemoteMeasure’, stream: ‘None’ } no_audio_received : When remote or local audio is silent. { group: ‘audio’, level: ‘warning’, type: ‘no_audio_received’, value: ‘<current audio level in dB>’, active: true || false, //Will be false when value goes to normal level. desc: ‘local_audio’ || ‘remote_audio’, stream: ‘local || remote’ } ice_timeout : Alert if ICE gathering takes more than two seconds either for outgoing call invite or incoming call answer. { group: ‘network’, level: ‘warning’, type: ‘ice_timeout’, value: ‘2000’, active: true, desc: ‘Possible NAT/Firewall issue’, stream: ‘None’ } no_microphone_access : When Chrome losses access to microphone. This event is generated if preDetectOwa is set to true. { group: ‘audio’, level: ‘warning’, type: ‘no_microphone_access’, active: true, desc: ‘Chrome lost access to microphone — restart browser’, stream: ‘None’ } ice_connection : When call’s ICE connection state changes. { group: ‘network’, level: ‘warning’, type: ‘ice_connection’, active: true || false, // Will be false when value is ‘connected’ value: ‘connected’ || ‘disconnected’ || ‘failed’, desc: ‘network drop’, //when value is ‘connected’ stream: ‘None’ } mute_detection: Speech is detected when the call is muted during an ongoing conversation. { group: ‘audio’, level: ‘warning’, type: ‘speaking_on_mute’, active: true value: ‘0’, desc: ‘User is trying to speak on mute’ stream: ‘None’ } |
audioDeviceChange(deviceObj) | Occurs when a USB audio device is added or removed. This event emits an object with two properties: change and device. change may have the values added or removed. device provides device-specific properties. |
onConnectionChange | Generated when the state of Plivo’s WebSocket connection changes; for example, when the WebSocket is disconnected due to internet issues. On WebSocket disconnect { ‘state’:‘disconnected’, ‘eventCode’:<code>, ‘eventReason’:<reason> } On WebSocket reconnect { ‘state’:‘connected’ } Common WebSocket event codes ( RFC 6455)1006 indicates that the connection was closed abnormally, without sending or receiving a Close control frame. For example, internet disconnection. 1009 indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process. 1011 indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request. |
onNoiseReductionReady | Upon initialization of the SDK with the “enableNoiseReduction” flag, a necessary file for call processing is loaded. Once the file is successfully loaded and prepared for use, the “onNoiseReductionReady” event is triggered. Subsequently, you have the option to initiate noise suppression by calling the “startNoiseReduction()” function at any point. |
onWebSocketConnected | This event triggers when the SDK is connected to the Plivo servers. |
volume(audioStats) | Display user real-time volume of mic and speaker. The volume event handler is invoked 60 times per second. The handler receives inputVolume and outputVolume as percentages of maximum volume represented by a floating point number between 0.0 and 1.0, inclusive. This value represents a range of relative decibel values between -100dB and -30dB. audioStats JSON object: { ‘inputVolume’: ‘<relative_value_on_scale_0_to_1>’, ‘outputVolume’: ‘<relative_value_on_scale_0_to_1>’ } ‘inputVolume’: input device volume (mic) ‘outputVolume’: output device volume (speaker) |
onDtmfReceived(dtmfData) | DTMF received from the other end during an ongoing call. dtmf data JSON object: { tone: ‘<dtmf_tone>’, duration: ‘<dtmf_duration>’, }; ‘tone’: dtmf tone received from other end ’duration’: duration of the tone received |
CallInfo Object
A CallInfo object is passed as a parameter for the following event callbacks:- onCallRemoteRinging
- onCallConnected
- onCallAnswered
- onMediaConnected
- onCallTerminated
- onIncomingCall
- onIncomingCallCanceled
- onIncomingCallIgnored
- onCallFailed
| Property | Description |
|---|---|
callUUID | The UUID of the call. |
direction | The call direction. Can be INCOMING or OUTGOING. |
src | The source address for the call. Will be the SIP URI of the endpoint in the case of an outgoing call. Will be the FROM number/endpoint in the case of an incoming call. |
dest | The destination address for the call. Will be the TO number/endpoint in the case of an outgoing call. Will be the the SIP URI of the endpoint in the case of an incoming call. |
extraHeaders | The extraHeaders (json object) sent to or received from the Plivo SIP server. |
Reason | Indicates the cause of disconnection. |
Protocol | The values can be either Q.850 or SIP. |
Code | Hangup error code from SIP. |
Originator | Source of disconnection, with possible values being remote or local. |
state | The current state of the call. Can be one of: 1. ringing 2. answered 3. rejected 4. ignored 5. canceled 6. failed 7. ended Call state will be set to failed if an error leads to the call being hung up before it could be answered. |