Add an authorized SIP-line selector to an IllyVoIP SDK phone

A custom SDK application can offer a choice among SIP identities the signed-in person is permitted to use for browser calling. The server owns that authorization. This guide does not add or restore a manual line selector in the native IllyVoIP app, whose controls follow their own product policy.

Start with the official IllyVoIP Webphone SDK 1.4.2 bundle and one managed phone owner. Your backend must authorize the signed-in user’s SIP identity and issue the short-lived browser token. The examples extend your application; they do not change the hosted Portal phone.

1. Build an authorized choice list on the backend

1. Authenticate the application user through your verified session middleware.
2. Resolve the SIP identities that user may operate in this application.
3. Intersect that list with current browser-calling capability and account state.
4. Return only the display information and opaque choice references the UI needs.

An identity listed under an account is not automatically suitable for browser calling. Do not bypass an IP-only or restricted identity’s capability by exposing its credentials. A client-side dropdown is presentation, not the authorization boundary.

2. Validate the selected identity again

When the user chooses a line, submit the choice reference to your backend. Recheck permission and capability there, then establish the selected SIP principal server-side before requesting /api/v1/sip/browser-token. Keep the permanent API key on the server.

The official proxy example rejects raw browser identity claims and obtains the identity from authenticated server state. A multi-identity application must extend that authorization deliberately; do not simply remove the rejection and trust any sip_user_id posted by the browser.

3. Require an idle owner before switching

1. Disable another switch while one is in progress.
2. Inspect all calls on the current SDK owner, including incoming and held calls.
3. If any call is active or pending, keep the current identity and ask the user to finish that workflow.
4. Stop new call actions before beginning cleanup.

Do not interpret a hidden call panel as an idle phone. This workflow does not migrate an active call from one SIP identity to another. Handle an incoming event that races the switch through your established stop policy rather than silently discarding it.

4. Replace the owner in a strict sequence

Dispose the old UI subscriptions and await the old owner’s destroy() result. If cleanup fails, stop with an uncertain-state message; do not register a replacement over an owner that may still be connected. Only then obtain the newly authorized token and initialize the replacement with the intended settings.

Use an application generation or operation ID to reject stale asynchronous results. A token response for a previous selection must not replace the latest choice. Ensure the token provider and refresh path remain bound to the same authorized identity throughout the new owner’s lifetime.

5. Confirm the new state before enabling Call

1. Inspect the new owner’s getState(), including its active SIP identity and connection/registration state.
2. Compare that identity with the backend-approved selection.
3. Show the selected line clearly beside call controls.
4. Enable calling only after the required state is confirmed.

Changing the SDK identity does not change an incoming number’s destination or guarantee a particular outgoing caller ID. Those are separate account configurations. Keep the selection label distinct from a customer record’s destination number.

6. Test denial, races and logout

Use mocked owners to test an unauthorized choice, an IP-only identity, an incoming call during switching, failed destruction, a late token response and logout mid-transition. Confirm no denied or stale selection creates a registered owner. Then arrange authorized calling tests for each supported choice, checking identity, caller ID and incoming behavior independently. Keep credentials and complete token/bootstrap data out of diagnostics.

Related guides

• Provision a SIP client with the IllyVoIP SIP API
• Add browser calling with the Webphone SDK
• Handle browser-token refresh in a long-running IllyVoIP SDK session

Reference

Current instructions and technical reference: IllyVoIP API documentation.

Reviewed 13 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.