Managed regional fallback lets the IllyVoIP Webphone SDK try another configured region when connecting or registering fails. Your token provider must request credentials for the region the SDK asks for, and your backend must authorize that region and SIP identity.
This guide targets SDK 1.4.2 managed-token mode. Fallback is not an active-call migration feature: the current SDK does not start this fallback while a current call exists. It also does not apply to raw SIP credential mode. Design the interface around reconnection, not a promise that ongoing audio will survive a region failure.
1. Choose an ordered list of supported regions
Use regions currently supported for your account and calling identity. Order them according to your application’s intended primary and alternatives. Do not generate region codes or substitute arbitrary SIP/WSS hostnames.
The example below uses de, us and sg as the documented region codes. Your backend still needs an allowlist appropriate to the account. A different region does not bypass identity restrictions, account verification, balance requirements or destination controls.
2. Make the token provider region-aware
The backend route in this example is a route you implement in your application. It must authenticate the user, enforce CSRF/origin policy as appropriate, derive the authorized SIP identity, validate the requested region, call IllyVoIP with the server-held API key and return only the short-lived token response.
async function tokenProvider({ region }) {
const response = await fetch('/my-backend/illyvoip/browser-token', {
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': readApplicationCsrfToken()
},
body: JSON.stringify({ region }),
signal: AbortSignal.timeout(10000)
});
if (!response.ok) throw new Error('Voice authorization unavailable');
return response.json();
}readApplicationCsrfToken is your application’s existing CSRF-token reader, not an SDK method. Use an equivalent bounded request mechanism in supported browsers if AbortSignal.timeout is unavailable. The timeout here bounds the token HTTP request; it is not a deadline for every subsequent SDK operation.
Do not cache one region’s token and return it for every request. Recheck authorization on refresh and fallback. Never move the permanent API key into browser code to simplify the provider.
3. Configure fallback before connecting
const phone = await IllyVoipWebRtcPhone.create({
autoConnect: false,
autoRegister: false,
tokenBootstrapUrl:
'https://api.illyvoip.com/api/v1/sip/browser-bootstrap',
tokenProvider,
regions: ['de', 'us', 'sg']
});
const off = [
phone.on('fallback:attempt', ({ fromRegion, toRegion, operation }) =>
showConnectionStatus(`Trying ${toRegion} for ${operation}`)),
phone.on('fallback:applied', ({ region }) =>
showConnectionStatus(`Connection fallback applied: ${region}`)),
phone.on('fallback:failed', () =>
showConnectionStatus('Fallback failed; check connection and authorization'))
];
await phone.connect();
await phone.register();showConnectionStatus is a plain-text UI function. Place this setup inside your existing serialized phone owner and catch startup errors there. The snippet is not permission to create a second phone instance alongside a framework integration. Unsubscribe and destroy the instance through that owner’s cleanup process.
Also display the normal connection and registration events. A fallback-applied event reports the fallback operation; it does not prove microphone permission, incoming routing or a successful call.
4. Handle exhausted or ineligible fallback
If startup ultimately fails, stop the spinner and show an actionable result. Check connectivity, the token backend, identity eligibility and region configuration. Repeatedly cycling through regions cannot repair an invalid key or disabled account.
The SDK chooses the next configured candidate within its fallback behavior. Do not assume one call to connect will keep trying forever until a region works. Bound any application-level retry policy, avoid overlapping startup attempts and investigate the failure before creating a replacement owner.
If a current call exists, preserve its state and present the connection problem accurately. Do not destroy and recreate the phone as if this would move the established call to another region.
5. Test the behavior you intend to support
With local fixtures, verify that each token request uses the requested region, a failed provider rejects cleanly, events update the UI, cleanup removes listeners and a replacement owner cannot overlap the old one. Include a current-call case in which fallback must not be treated as migration.
An authorized live acceptance test must separately establish connection, registration and actual calling in the selected regions. Do not deliberately disrupt shared production connectivity or place paid calls simply to demonstrate this guide.
Related guides and reference
- Add browser calling with the Webphone SDK
- Manage the IllyVoIP WebRTC Phone SDK lifecycle in React
- Add IllyVoIP browser calling to a Next.js App Router application
- SDK regional fallback
- Backend token endpoint
Reviewed 10 October 2026 against the current IllyVoIP reference and implementation. SDK examples target version 1.4.2 where applicable. Local example checks do not certify a completed live call, routing change or third-party integration.