@vivantcorp/softphone-sdk
v1.0.2
Published
Vivant Softphone SDK is a versatile and user-friendly softphone solution designed for seamless integration across various web platforms and CRMs. This package provides a robust, feature-rich VoIP calling experience, complete with event handling capabiliti
Readme
VivantPhone SDK/Library
VivantPhone SDK is a JavaScript library that enables easy integration of the Vivant softphone into any web application. Originally developed as part of our PBX application portal, the softphone was later deployed as a standalone web app. With this SDK, developers can seamlessly embed the Vivant softphone within their applications, allowing users to make and receive calls directly through the integrated interface.
Features
- Inbound and Outbound Calling: Embeds the Vivant webphone and relays events so users can make and receive calls within the web app.
- Event Listeners: Provides event hooks for various call actions, such as incoming calls, call acceptance, and call decline.
Installation
Install the VivantPhone SDK via npm:
npm install @vivantcorp/softphone-sdkBasic Usage
Here's how to set up the VivantPhone SDK in your application:
- Import the SDK.
- Initialize the softphone with required configurations.
- Set up event listeners for handling call events and send events to VivantPhone.
Example
const { VivantPhone } = require('@vivantcorp/softphone-sdk');
const phone = new VivantPhone({ subdomain: 'vivant-corp' });
// after initialization render softphone
phone.renderSoftphone();
// Listen for the login event
phone.on('onUserLoggedIn', (data) => {
console.log('User logged in:', data);
})
// Listen for the incoming call event
phone.on('onIncomingCall', (data) => {
console.log('Incoming call:', data);
});
// Listen for the onCallAccepted call event
phone.on('onCallAccepted', (data) => {
console.log('Call accepted:', data);
});
// Listen for the onCallDeclined call event
phone.on('onCallDeclined', (data) => {
console.log('Call declined:', data);
});
// Emit the doMaximize event to maximize Softphone window.
phone.sendMessage(
{
action: 'doMaximize',
data: {},
}
);
// Emit the doMinimize event to minimize Softphone window.
phone.sendMessage(
{
action: 'doMinimize',
data: {},
}
);
// Emit the doLogin event to bypass the login screen.
phone.sendMessage(
{
action: 'doLogin',
data: { username: '[email protected]', password: 'secret' },
}
);
// Emit the `doDial` event to pass the phone number to the softphone.
phone.sendMessage(
{
action: 'doDial',
data: { phoneNumber: '1234567890' },
}
);
// Emit the `doLogout` event to destroy softphone session.
phone.sendMessage(
{
action: 'doLogout',
data: {},
}
);
Configuration Options
Pass these in the constructor:
- subdomain: string (preferred)
- url: string (optional, default: https://webphone.vivantcorp.com)
- platform: string (required if subdomain is not provided)
- platformuserid: string (required if subdomain is not provided)
- connectedColor: string (optional, default: #8bc34a)
- disconnectedColor: string (optional, default: red)
- buttonShape: string (optional, one of: circle, rounded, square)
Events
You can listen to these events via phone.on(eventName, handler):
- onDomainLoaded: Fires when the softphone is ready; only start sending actions or other requests after this event. Payload: {}
- onUserLoggedIn: Fires after the user successfully logs in. Payload: {}
- onUserLoggedOut: Fires after the user successfully logs out. Payload: {}
- onIncomingCall: Fires when an incoming call is received by the softphone. Payload: { phoneNumber: string }
- onCallAccepted: Fires when call accepted. Payload: {}
- onCallDeclined: Fires when call declined. Payload: {}
- onPBXInternalUser: Fires Specially for Vivant platform Use. Payload: {}
- onSoftphoneMinimize: Fires when the softphone window is minimized. Payload: {}
- onSoftphoneMaximize: Fires when the softphone window is maximized. Payload: {}
- onSoftphoneModeChanged: Fires when the softphone connection mode changes (connected or notconnected). Payload: { mode: 'notconnected' | 'connected' }
- onSoftphoneSizeChanged: Fires when the softphone window size changes. Payload: { width: string, height: string }
- onSoftphoneModeUpdate: Fires when the softphone UI mode updates (NO_DEVICE, NOT_CONNECTED, NOT_REGISTERED, ANOTHER_REGISTRATION_FOUND, DISCONNECTED, STAND_BY, CALLING, CALL_IN_PROGRESS, ADD_CALL, TRANSFER_CALL, VOICEMAIL_TRANSFER_CALL, ATTENDED_TRANSFER, CALL_TAGGING, FORCED_CALL_TAGGING, SEND_DTMF, INCOMING_CALL, SETTINGS, TRANSFERS_MENU, ATTENDED_TRANSFER_IN_PROGRESS). Payload: {}
- onSessionExpired: Fires when the session expires and the system logs the user out automatically (unlike
doLogout, which is a manual logout). Payload: {} - onCallEnded: Fires when call Ended. Payload: { sessionName: string, sessionNumber: string, callStarted: number, callEnded: number, isIncoming: boolean, callDuration: string }
- onCallInit: Fires when call initialized. Payload: { sessionName: string, sessionNumber: string, isIncoming: boolean }
- onCallRinging: Fires when call ringing. Payload: { sessionName: string, sessionNumber: string, isIncoming: boolean }
- onContactSearchLoaded: Fires when contact details are returned from third-party integrations (e.g., HubSpot, Salesforce) after a lookup, typically on incoming calls. Payload: {}
- onRecentActivitiesLoaded: Fires when recent activities for the caller are returned from third-party integrations (e.g., HubSpot, Salesforce). Payload: {}
Actions (sendMessage)
Supported actions you can send to the iframe:
- doMaximize: Maximizes the softphone window. Payload: { }
- doMinimize: Minimizes the softphone window. Payload: { }
- doLogin: Logs in the user with provided credentials. Payload: { username: string, password: string }
- doDial: Starts an outbound call to the given number. Payload: { phoneNumber: string }
- doLogout: Logs out the current user and ends the session. Payload: { }
- doCheckSoftphoneMode: Requests the current softphone mode/state. Payload: { }
License
This package is proprietary software owned by Vivant Corporation. Installing and using it via npm does not grant permission to modify, redistribute, resell, or reverse engineer the SDK. See the LICENSE file for full terms.
