Add an Available/Unavailable control to an IllyVoIP SDK phone

An Available/Unavailable switch in your SDK application can register or unregister that browser phone. Define the label narrowly: it affects this owner’s SIP registration, not the whole IllyVoIP account, another device, queue membership or a campaign’s Ready state.

This guide targets the official Webphone SDK 1.4.2 browser distribution. Start with the installation guide, one managed phone owner and an authenticated backend that authorizes the user’s SIP identity. Keep permanent API keys and SIP passwords out of browser code.

1. Use explicit registration ownership

Create the owner with autoConnect and autoRegister set to false, then connect and register through your deliberate enable workflow. The SDK’s managed refresh can restore automatic registration when both automatic flags are enabled; that configuration conflicts with treating an explicit unregister as a lasting local availability choice.

Keep one controller responsible for register, unregister, connection recovery and logout. Disable availability changes while a call exists, initialization is running or another control action is pending. An incoming call can arrive between a UI check and a registration change, so continue observing call events throughout.

2. Request the change and then read the state

This helper is for an already initialized, connected owner. It serializes clicks and conservatively blocks any known call. The caller must show thrown errors and refresh its displayed state; it must not retry automatically.

export function availabilityController(phone) {
  let busy = false;
  return async function setAvailable(wanted) {
    if (busy) throw new Error('Availability change in progress');
    if (phone.getCalls().length) throw new Error('Finish the current call first');
    if (phone.getState().connected !== true) throw new Error('Phone not connected');
    busy = true;
    try {
      if (wanted) await phone.register();
      else await phone.unregister();
      const state = phone.getState();
      if (state.registered !== wanted) throw new Error('Registration is not confirmed');
      return state;
    } finally {
      busy = false;
    }
  };
}

Disable the button before invoking the helper. Display Changing while its promise is pending. Do not optimistically display Unavailable merely because the user clicked the switch. If an incoming call appears during the operation, handle that actual call through the normal call UI; unregister is not a hangup command.

3. Keep the displayed state current

1. Subscribe to registration:registered and registration:unregistered and reread getState when they occur.
2. Observe connection and call events as well; a disconnected phone should not remain labeled ready to receive calls.
3. Retain the desired local preference separately from observed registration. If they disagree after a late event or recovery, show a review-needed state rather than silently pretending the request succeeded.
4. Dispose subscriptions when the owner is destroyed. Do not bind another set on every component render.

The SDK on method returns a disposer. A late event belongs to the owner that emitted it; ignore it after that owner has been replaced. Treat failed unregister or transport loss as an uncertain availability result until reconciled, not as evidence that no call can arrive.

4. Test both directions of the switch

1. With fixtures, delay register and unregister promises and try a second click. Confirm only one operation runs.
2. Inject an incoming event during the pending change and keep its call visible.
3. Test failure, disconnect and a late registered event after the user requested unavailable.
4. In an authorized live test, call the routed number while this endpoint is available, then repeat after confirmed unregister.

Another device or route may still receive the second call. That does not prove this browser’s control failed. Check the exact receiving endpoint and do not describe local unregister as account-wide Do Not Disturb.

5. Preserve normal logout and recovery rules

When signing out, stop new operations, apply your active-call policy and await orderly SDK destruction before another account can own the phone. Availability alone does not revoke tokens or authenticate a different user. Keep the connection, registration and call timestamps for troubleshooting; do not log secret bootstrap payloads.

Related guides

• Add browser calling with the Webphone SDK
• Manage the IllyVoIP WebRTC Phone SDK lifecycle in React
• Build incoming-call Answer and Decline controls with the Webphone SDK
• Troubleshoot the webphone

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