Web Phone SDK Configuration Options

The ProvisionPhone() method accepts a configuration object that controls how the phone UI behaves, what features are enabled, and how it integrates with your application. This article documents all available options and how to use them.

ProvisionPhone() Options

Pass a configuration object to ProvisionPhone() with any or all of the following options:

Option	Type	Required	Description
`Provisioning`	object	Yes	The provisioning object from `GetProvisioning()` or a manually constructed object with SIP credentials
`PhoneFrame`	HTMLIFrameElement	Yes	The `<iframe>` element where the phone UI will render
`ProfileUserId`	string	Yes	A unique identifier for this phone instance (e.g., a session ID or user identifier)
`SessionId`	string	Yes	The session identifier, typically the `SessionToken` from `Login()`
`UserId`	string	Yes	The user identifier from your session
`EnableAvatar`	boolean	No	Show user avatar in the phone UI (default: `true`)
`EnableSettings`	boolean	No	Show settings panel accessible from the phone UI (default: `false`)
`EnableDialPad`	boolean	No	Show dial pad for manual number entry (default: `true`)
`EnableCallTransfer`	boolean	No	Enable call transfer functionality (default: `true`)
`EnableCallHold`	boolean	No	Enable call hold functionality (default: `true`)
`EnableCallMute`	boolean	No	Enable microphone mute during calls (default: `true`)
`EnableCallRecording`	boolean	No	Enable call recording (if your account supports it) (default: `true`)
`EnableDeviceSelector`	boolean	No	Show audio device (microphone/speaker) selector in settings (default: `true`)
`UiThemeStyle`	string	No	UI theme: `'light'`, `'dark'`, or `'system'` (follows OS preference) (default: `'light'`)
`Language`	string	No	UI language code (e.g., `'en'`, `'es'`, `'fr'`) or `'auto'` to detect from browser (default: `'auto'`)
`OnLoad`	function	No	Callback function invoked when the phone is fully loaded and ready to use

ProvisionPhone() Example

const phone = await window.Siperb."ProvisionPhone"({
    Provisioning: provisioning,
    PhoneFrame: document.getElementById("phone-iframe"),
    ProfileUserId: "user-session-001",
    SessionId: session.SessionToken,
    UserId: session.UserId,
    EnableAvatar: true,
    EnableSettings: true,
    EnableDialPad: true,
    EnableCallTransfer: true,
    EnableCallMute: true,
    UiThemeStyle: 'dark',
    Language: 'en',
    OnLoad: () => {
        // Phone is ready
        console.log('Phone loaded');
    }
});

Manual Provisioning Object

For direct PBX connections (bypassing the Siperb proxy), you can construct a manual provisioning object instead of calling GetProvisioning(). This object contains SIP credentials and connection details.

Property	Type	Description
`RegistrationMode`	string	Connection type: `"Socket"` for direct PBX connection, `"Proxy"` for Siperb proxy
`profileName`	string	Display name for this phone profile (e.g., “Office Phone”)
`SipWssServer`	string	The PBX server address (hostname or IP)
`SipUsername`	string	The SIP username for authentication
`SipPassword`	string	The SIP password for authentication
`SipDomain`	string	The SIP domain (usually the same as the server address)
`ProfileUserName`	string	The caller ID display name (appears on inbound calls)
`SipContact`	string	Contact user parameter; leave empty string if not needed
`SipWebsocketPort`	number	The WebSocket port for SIP over WebSocket (e.g., `8089`)
`SipServerPath`	string	The WebSocket path on the server (e.g., `"/ws"`)

Manual Provisioning Example

Here’s how to use a manually constructed provisioning object for a direct connection:

const manualProvisioning = {
    RegistrationMode: "Socket",
    profileName: "Direct PBX",
    SipWssServer: "pbx.company.local",
    SipUsername: "user@company.local",
    SipPassword: "sip-password",
    SipDomain: "pbx.company.local",
    ProfileUserName: "John Doe",
    SipContact: "",
    SipWebsocketPort: 8089,
    SipServerPath: "/ws"
};

const phone = await window.Siperb."ProvisionPhone"({
    Provisioning: manualProvisioning,
    PhoneFrame: document.getElementById("phone-iframe"),
    ProfileUserId: "user-123",
    SessionId: "session-token",
    UserId: "user-id"
});

Comparison: Provisioned vs Manual

Use GetProvisioning() when:

You’re connecting through the Siperb proxy (most common case)
You want Siperb to manage SIP credentials and updates
Your account has transcoding, filtering, or other Siperb services enabled

Use manual provisioning when:

You’re connecting directly to your own PBX (Socket mode)
You want complete control over SIP parameters
Your PBX manages authentication directly

Common Configuration Patterns

Minimal Setup

const phone = await window.Siperb."ProvisionPhone"({
    Provisioning: provisioning,
    PhoneFrame: document.getElementById("phone"),
    ProfileUserId: "user",
    SessionId: session.SessionToken,
    UserId: session.UserId
});

Dark Mode with Callbacks

const phone = await window.Siperb."ProvisionPhone"({
    Provisioning: provisioning,
    PhoneFrame: document.getElementById("phone"),
    ProfileUserId: "user",
    SessionId: session.SessionToken,
    UserId: session.UserId,
    UiThemeStyle: 'dark',
    OnLoad: () => {
        console.log('Phone ready');
        phone.Toast('Welcome back');
    }
});

Feature Restrictions

const phone = await window.Siperb."ProvisionPhone"({
    Provisioning: provisioning,
    PhoneFrame: document.getElementById("phone"),
    ProfileUserId: "user",
    SessionId: session.SessionToken,
    UserId: session.UserId,
    EnableCallTransfer: false,
    // Disable call transfer for restricted users
    EnableCallRecording: false
    // Disable recording
});