Client side SDK for web applications hosted in Vonage Business Cloud
Use npm to install.
npm install @vonage/vbc-web-sdkimport VBCWebSDK from 'vbc-web-sdk';
vbc = new VBCWebSDK();
const token = vbc.initialize();
// do some verification at your end...
verifyUser(token);
vbc.ready();All the services can accept an options object with the following fields:
- requestTimeout - to set a request timeout. default is set to 10 seconds.
Creates a connection with VBC. Parameters: options returns: -- extensionToken - a string that is used for user verification in the hosted app. -- vbcContext - an object describing the context in which the app was accessed inside VBC. (relevant only for popup for now)
vbc = new VBCWebSDK();
token = vbc.initialize(options);Let VBC know the app is ready to be displayed. Parameters: options
vbc.ready(options);In case something went wrong and the app is not ready for user interaction, the method reports an error to VBC. Parameters: options -- error - TBD
vbc.error(error, options);Let VBC know the app is being terminated. Parameters: options
vbc.terminate(options);Let VBC know that the context sent from it is invalid for the app. Parameters: options
vbc.contextInvalid(options);Request VBC for a valid vbc JWT token. Parameters: options returns: Object with new token and refresh token
{
"accessToken": "TOKEN",
"refreshToken": "TOKEN"
}tokenObj = vbc.getAccessToken();Request the contacts of the user. Parameters: options returns: -- contacts - an array of contact objects.
contacs = vbc.getContacts(options);contact:
{
"addresses": [],
"cuid": "123456789e123456789",
"display": { "tel": "", "ext": "x0000", "status": "available", "isContactable": true, "description": "always on time" },
"displayName": "John Smith",
"firstName": "John",
"isFavorite": false,
"isOffNet": false,
"labels": ["CAB"],
"lastName": "Smith",
"mailingAddresses": "some address",
"organization": "JM corps",
"props": null,
"revision": 1234567890,
"title": "JM corps CEO"
}Request VBC to make a call to some number. Parameters: toNumber, options returns: TBD
vbc.makeCall(toNumber, options);Request VBC to get user information. Parameters: options returns: --userInfo - an array of user information.
vbc.getUserInfo(options);Request VBC to send a message. Parameters:
- messageBody - the message to be sent.
- contactNumber - the number to send the message to.
- contactId - in case the number is invalid, allows VBC to the contactId default number.
- options
vbc.sendMessage(messageBody, contactNumber, contactId, options);Request VBC to open a popup window inside vbc. Parameters:
- url - the url to embed in the popup
- title - title of the modal
- options
vbc.openPopup(url, title, options);Requests VBC hang up an ongoing call. Parameters: callId, options
vbc.hangupCall(callId, options);Requests VBC mute/unmute an ongoing call. Parameters: callId, options
vbc.muteCall(callId, options);Requests VBC to dial a digit in an ongoing call. Parameters: callId, digit, options
vbc.sendDTMF(callId, digit, options);Requests VBC to record/unrecord an ongoing call. parameters: callId, options
vbc.recordCall(callId, options);Requests VBC to manage calls. Parameters: parameters, options Using the manageCalls without any parameters will toggle the app state from false to true and vice-versa. Using the parameters, the app can customize the VBC behaviour of managing calls. Each of the following parameters has a default value, that is set if the parameter was not explicitly stated. Default values will only be set when toggling 'manage-calls' from false to true and will not take effect if 'manage-calls' was already active. Therefore you can partially update the 'manage-calls' settings without worrying the default values take effect.
- manageCalls - boolean - Turn on or off the 'manage-calls' state on VBC. When true, VBC will set all action parameters into it's state. When set to false, non of the parameters take effect, and all previous values are removed from VBC's state.
- playIncomingCallSounds - boolean (default = false) - this parameter determines whether VBC plays the ringing sound for incoming calls or not. Using this parameter you may choose if you want your own app to manage ringing states and play sounds or keep the VBC default behavior.
- showIncomingCallScreen - boolean (default = false) - this parameter determines whether VBC shows the incoming call screen when a call rings your softphone. Using this parameter you may choose if you want your own app to show the incoming call indication or not.
- showIncomingCallNotification - boolean (default = false) - Whether VBC shows the native notification for incoming calls or not.
- showOngoingCallScreen - boolean (default = false) - Whether VBC shows the ongoing call screen. You may use this option to display the status of the ongoing calls on your app instead.
- suppressOutboundCalls - boolean (default = false) - When set to true, VBC will not initiate outgoing calls, instead it will send the 'initiate-click-to-call' event. You may use this event to initiate an outbound call from you app instead of VBC.
- includeVBCExtensionCalls - boolean (default = true) - When set true, when making an outbound call to an onNet number, VBC will ignore the manage calls settings and the call flow would be as if the manageCalls key was set to false.
vbc.manageCalls(parameters, options);Parameters example:
{
"type": "manage-calls",
"parameters": {
"manageCalls": true,
"playIncomingCallSounds": true,
"showIncomingCallScreen": false,
"showIncomingCallNotification": false,
"showOngoingCallScreen": false,
"suppressOutboundCalls": false,
"includeVBCExtensionCalls": false
}
}Important: When calling emergency numbers - VBC will ignore the manage-calls parameters and act as if the manageCalls key is false.
Request VBC to change to a different route of the same application. Parameters: route_id, route_context?, options
Route context example:
{
"initial_context": "SOME_CONTEXT",
"some_relevant_data": "OTHER_CONTEXT"
}vbc.setActiveRouteId('ROUTE_ID');Request VBC to update the badge count near the application in the sidebar. Can be some number larger than 0 for notification indication or 0 to show no notifications. Parameters: app_id, count, options
vbc.setAppBadge('ROUTE_ID', 7);Request VBC to update the title bar configuration. Setting what buttons & dropdowns will be shown Parameters: titleBarConfig, options
Title bar config example:
{
"buttons": [
{
"icon": "Vlt-icon-plus",
"text": "New Message",
"tooltip": "New Message",
"event": "newMessage"
}
],
"dropdowns": [
{
"id": "Mode",
"options": [
{ "index": 0, "label": "Dark" },
{ "index": 1, "label": "Bright" }
],
"selectedValue": { "index": 0, "label": "Dark" }
}
]
}vbc.setAppTitleBarPlugin(titleBarConfig);Request VBC to register to an event. Parameters:
- eventName - the event to be registered to.
- callBack - function of the application which will be executed when the event happens.
vbc.registerEvent(eventName, callBack);Ask VBC to execute an action (which the application has permissions to).. Parameters:
- action - an action object to send to VBC
vbc.sendCustomAction(action);Parameters example (asking VBC to execute an action type 'dispatch-action', which changes the value of openSideView to true)
{
"isPrivileged": true,
"type": "dispatch-action",
"parameters": {
"actionId": "openSideView",
"isRoot": true,
"context": {
"value": true
}
}
}Send a file to be downloaded, VBC can control how to manage the file downloads. Could have different implementation for Electron and Browser.
Parameters:
- url - file's url to download.
- name - the name of the file to be displayed.
- type - enum of DOWNLOAD_FILE_TYPES, default is general, values: { general:0, audio:1, video:2, image:3 }
- thumbnail - optional thumbnail to be displayed for VBC
vbc.downloadFile(url, name, type, thumbnail, options);Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate.
Unit tests can be run simply by executing:
npm run test