Have ideas to improve npm?Join in the discussion! »

    TypeScript icon, indicating that this package has built-in type declarations

    1.17.0 • Public • Published

    VBC Web SDK

    Client side SDK for web applications hosted in Vonage Business Cloud


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


    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



    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



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



    Request the contacts of the user. Parameters: options returns: -- contacts - an array of contact objects.

    contacs = vbc.getContacts(options);


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



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


    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

    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.


    • 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






    npm i @vonage/vbc-web-sdk

    DownloadsWeekly Downloads






    Unpacked Size

    804 kB

    Total Files


    Last publish


    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar