VBC Web SDK

Client side SDK for web applications hosted in Vonage Business Cloud

Installation

Use npm to install.

npm install @vonage/vbc-web-sdk

Usage Example

import VBCWebSDK from 'vbc-web-sdk';
vbc = new VBCWebSDK();
const token = vbc.initialize();
// do some verification at your end...
verifyUser(token);
vbc.ready();

Services

All the services can accept an options object with the following fields:

• requestTimeout - to set a request timeout. default is set to 10 seconds.

initialize

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);

ready

Let VBC know the app is ready to be displayed. Parameters: options

vbc.ready(options);

error

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);

terminate

Let VBC know the app is being terminated. Parameters: options

vbc.terminate(options);

contextInvalid

Let VBC know that the context sent from it is invalid for the app. Parameters: options

vbc.contextInvalid(options);

getAccessToken

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();

getContacts

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"
}

makeCall

Request VBC to make a call to some number. Parameters: toNumber, options returns: TBD

vbc.makeCall(toNumber, options);

getUserInfo

Request VBC to get user information. Parameters: options returns: --userInfo - an array of user information.

vbc.getUserInfo(options);

sendMessage

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);

openPopup

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);

hangupCall

Requests VBC hang up an ongoing call. Parameters: callId, options

vbc.hangupCall(callId, options);

muteCall

Requests VBC mute/unmute an ongoing call. Parameters: callId, options

vbc.muteCall(callId, options);

sendDTMF

Requests VBC to dial a digit in an ongoing call. Parameters: callId, digit, options

vbc.sendDTMF(callId, digit, options);

recordCall

Requests VBC to record/unrecord an ongoing call. parameters: callId, options

vbc.recordCall(callId, options);

manageCalls

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.

1. 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.
2. 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.
3. 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.
4. showIncomingCallNotification - boolean (default = false) - Whether VBC shows the native notification for incoming calls or not.
5. 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.
6. 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.
7. 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.

setActiveRouteId

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');

setAppBadge

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);

setAppTitleBarPlugin

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);

registerEvent

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);

sendCustomAction

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
		}
	}
}

downloadFile

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);

Contributing

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.

Tests

Unit tests can be run simply by executing:

npm run test

License

MIT