API Reference

Two ways to control the widget:

Web Component — direct element methods (recommended)

Helper Functions — utility functions for common tasks

Web Component API

The widget is a web component (<convirza-dialer>). Access it via the DOM:

Method	Returns	Description
`open()`	—	Expand the widget panel
`close()`	—	Collapse to floating button
`toggle()`	—	Toggle expanded/collapsed state

Call methods

Method	Returns	Description
`placeCall(phoneNumber, options?)`	`CallSession`	Place an outbound call
`endCall()`	—	Hang up active call
`mute(enable?)`	boolean	Mute/unmute microphone
`hold(enable?)`	boolean	Hold/unhold call
`sendDTMF(digit)`	—	Send DTMF tone during call

placeCall() example:

Call controls example:

Call method validation:
mute(), hold(), sendDTMF() — silent fail if no active call (return current state)
endCall() — safe to call anytime (no-op if no call)
Only placeCall() requires callStatus === 'idle'

Theming methods

Method	Parameters	Description
`setTheme(options)`	`ThemeOptions`	Update theme/branding at runtime

Utility methods

Method	Returns	Description
`clearCallHistoryCache()`	`Promise<void>`	Clear local call history (IndexedDB)

`CallSession` object

Returned by placeCall():

interface CallSession {
  phoneNumber: string;
  status: 'idle' | 'dialing' | 'ringing' | 'connected' | 'ended' | 'error';
  duration: number;  // milliseconds
  onAnswered(callback: () => void): void;
  onEnded(callback: (duration: number) => void): void;
  end(): void;
}

Events

Listen for widget events on the element:

Event	Detail	Description
`sip-registered`	—	SIP connection established, ready to make calls
`sip-unregistered`	—	SIP disconnected
`auth-failed`	`{ error: string }`	Authentication failed (wrong credentials, network error)
`call-started`	`{ phoneNumber: string }`	Outbound call initiated
`call-ended`	`{ phoneNumber: string, duration: number }`	Call terminated
`state-change`	`{ oldState, newState, metadata }`	Call state changed
`widget-opened`	—	Widget expanded
`widget-closed`	—	Widget collapsed
`sip-call-mute`	`{ muted: boolean }`	Mute state changed
`sip-call-hold`	`{ onHold: boolean }`	Hold state changed
`call-quality-change`	`CallQualityMetrics`	Call quality metrics updated (every 2s during call)
`history-updated`	`{ history: CallHistoryItem[] }`	Call history changed

Example:

Complete example

TypeScript support

Full type definitions included:

import type {
  CallSession,
  CallStatus,
  CallOptions,
  ThemeOptions,
  CallQualityMetrics,
  CallHistoryItem,
} from '@convirza/dialer-sdk';

const dialer = document.querySelector('convirza-dialer');
const session: CallSession = dialer.placeCall('+15551234567');
const status: CallStatus = session.status;

Available types:

CallSession — call object returned by placeCall()

CallOptions — options for placeCall()

ThemeOptions — options for setTheme()

CallQualityMetrics — call quality data

CallHistoryItem — history record structure

Method validation reference

Quick reference for which methods require active calls:

Method	Requires Call?	Behavior Without Call
`open()`, `close()`, `toggle()`	No	Always works
`setTheme()`	No	Always works
`placeCall()`	No (requires idle)	Throws if call active
`endCall()`	No	Silent no-op
`mute()`	Yes	Returns current state (silent fail)
`hold()`	Yes	Returns current state (silent fail)
`sendDTMF()`	Yes	Silent no-op
`clearCallHistoryCache()`	No	Always works

Best practice: always check call state before calling mute(), hold(), or sendDTMF() in production code, or listen to state-change events.

API Reference

Web Component API#

Widget control methods#

Call methods#

Theming methods#

Utility methods#

CallSession object#

Events#

Complete example#

TypeScript support#

Method validation reference#