@convirza/dialer-sdk

Browser-based SIP calling widget with call history, parking, device controls.

Installation

npm install @convirza/dialer-sdk

Quick Start

Needs access_token + refresh_token in sessionStorage.

import { convirzaDialer } from '@convirza/dialer-sdk';

convirzaDialer.init({
	access_token: sessionStorage.getItem('access_token'),
	refresh_token: sessionStorage.getItem('refresh_token'),
	dark_theme: true,
	primaryColor: '#6366f1',
});

// Token refresh handler
window.addEventListener('dialer-token-refreshed', (e) => {
	sessionStorage.setItem('access_token', e.detail.access_token);
	sessionStorage.setItem('refresh_token', e.detail.refresh_token);
});

// Auth failure (redirect to login)
window.addEventListener('dialer-auth-failed', () => {
	window.location.href = '/login';
});

convirzaDialer.call('+15551234567');
convirzaDialer.mute(true);
convirzaDialer.endCall();
convirzaDialer.destroy(); // cleanup on logout

Web Component

<convirza-dialer access-token="..." refresh-token="..." auto-configure="true" theme="dark"></convirza-dialer>

API

convirzaDialer

convirzaDialer.init(config)                    // Initialize widget (access_token, refresh_token required)
convirzaDialer.call(phoneNumber?)              // Place call, opens widget
convirzaDialer.endCall()                       // Hang up
convirzaDialer.mute(enable?)                   // Mute mic (toggle if omitted) → boolean
convirzaDialer.hold(enable?)                   // Hold call (toggle if omitted) → boolean
convirzaDialer.record(enable?)                 // Start/stop recording → boolean
convirzaDialer.transfer(target)                // Blind transfer to extension/number
convirzaDialer.showPopup() / hidePopup()       // Expand/collapse widget
convirzaDialer.getActiveCallID()               // Active call ID or null
convirzaDialer.callList(limit?)                // Call history array
convirzaDialer.destroy()                       // Cleanup (call on logout)

Config: access_token, refresh_token (required), brandName, brandLogo, dark_theme, primaryColor, accentColor

Helpers

import { initDialer, destroyDialer, isDialerInitialized } from '@convirza/dialer-sdk';

SipAdapter (Headless SIP client)

For custom UI / non-widget integrations. Requires sip.js global.

Config: sipUsername, sipPassword, sipDomain, wsServers, apiUrl (for parking), authToken
Callbacks: onRegistered, onCallAnswered, onCallEnded, onIncomingCall, onQualityChange, etc.

Methods: connect(), disconnect(), call(), endCall(), answerCall(), rejectCall(), mute(), hold(), sendDTMF(), startRecording(), stopRecording(), park(), blindTransfer(), setMicrophone(), setSpeaker(), getAudioDevices(), getCallQuality(), getCallUuid(), reconnect()

See packages/web-sdk/src/core/sip-adapter.ts for implementation.

Web Component (<convirza-dialer>)

element.placeCall(phoneNumber, options?)       // Place call → CallSession { onAnswered(), onEnded(), end() }
element.endCall()                              // Hang up
element.mute(enable?)                          // Mute mic → boolean
element.hold(enable?)                          // Hold call → boolean
element.sendDTMF(digit)                        // Send DTMF '0'-'9', '*', '#'
element.startRecording() / stopRecording()     // Server-side recording
element.open() / close() / toggle()            // Widget visibility
element.setTheme(options)                      // Dynamic theme update
element.clearCallHistoryCache()                // Clear IndexedDB history

Attributes: access-token, refresh-token, auto-configure, brand-name, brand-logo, theme, primary-color, accent-color, position, state, z-index, park-poll-interval

Events:
Auth: token-refreshed, auth-failed, sip-registered, sip-unregistered
Call: call-started, call-ended, call-answered, state-change, sip-call-mute, sip-call-hold, dtmf-sent, call-transferred
Widget: widget-opened, widget-closed, dialer-error, history-updated

Features

Call Parking

Widget sends park request to POST /v3/park-call, polls GET /v3/park-slots for occupancy.
Events: call-parked, park-slots-updated, call-park-failed

Call History

Stored in IndexedDB (browser-local, no backend sync). Survives page reload.
Clear: await dialer.clearCallHistoryCache()

Audio Devices

Hot-swap mic/speaker during call. Preferences → sessionStorage:convirza_audio_preferences
Speaker switching Chrome/Edge only (setSinkId).

Theming

HTML attributes or element.setTheme(). CSS vars injected at runtime.

Types

WidgetPosition, CallStatus, WidgetState, ThemeMode, CallDirection, CallDisposition, DialerEvents, CallSession, CallQualityMetrics

See packages/web-sdk/src/types/ for definitions.

Browser Support

Chrome 74+, Firefox 69+, Safari 14.1+, Edge 79+
Speaker selection (setSinkId) Chrome/Edge only.

License

PROPRIETARY — Copyright Convirza. All rights reserved.