Add IllyVoIP browser calling using the official Webphone SDK and a backend that issues short-lived calling tokens to authorized users. Keep one phone owner in your application, make connection and call state visible, and verify audio separately from registration.
This guide covers the web/browser SDK, including the reviewed 1.4.2 bundle. It is not a replacement for a native mobile calling integration. Start with an authenticated HTTPS application, an eligible SIP identity, a secure backend secret store and a defined policy for logout, navigation and account changes.
1. Choose hosted assets or the versioned bundle
Open the public SDK installation reference. Use its documented hosted browser asset, or follow Download web SDK bundle through the authorized download flow. The downloaded archive includes browser assets, the module facade, TypeScript definitions, examples and a manifest.
The downloadable package is not currently published to the public npm registry. Do not assume an npm install command for a similarly named package will provide IllyVoIP’s SDK. Follow the package included in the official archive.
For self-hosting, retain the package and browser directories together unless you explicitly configure their new asset URLs. The SDK’s JavaScript entry point and its WebRTC runtime are different files; copying only the SDK script can leave the runtime unavailable when initialization starts.
illyvoip-webrtc-phone-sdk-web-v1.4.2/
browser/assets/js/illyvoip-webrtc-phone-sdk.js
browser/assets/vendor/illyvoip-webrtc-runtime/index.js
browser/assets/vendor/illyvoip-webrtc-runtime/...
package/index.js
package/index.d.ts
package/README.md
MANIFEST.jsonRetain the runtime’s supporting files, not just index.js. Check the archive’s manifest and documented release before deployment. If you serve a versioned directory, keep the tested SDK/runtime set together and retain the previous deployment for your application’s normal rollback procedure.
2. Load the chosen distribution once
For the hosted browser script, use the current URL shown in the reference and wait for it to load before accessing window.IllyVoipWebRtcPhone. For the downloadable module facade, import from the extracted package path served by your application. That facade normally loads the adjacent browser assets.
If you move the directories, configure both asset URLs before creating the phone. The following paths are examples of your application’s own static deployment; they are not existing IllyVoIP-hosted URLs.
import { configureAssets, IllyVoipWebRtcPhone }
from '/vendor/illyvoip-sdk/package/index.js';
configureAssets({
sdkUrl: '/vendor/illyvoip-sdk/browser/assets/js/illyvoip-webrtc-phone-sdk.js',
runtimeUrl:
'/vendor/illyvoip-sdk/browser/assets/vendor/illyvoip-webrtc-runtime/index.js'
});Check the browser Network panel for successful JavaScript responses at the intended paths. An HTML login page or SPA fallback returned with HTTP 200 is not a valid runtime module. Review MIME types, deployment base paths and your application’s content security policy when loading fails.
Do not load two distributions or recreate the SDK on every route render. Use the framework-specific lifecycle guide for React, Vue, Next.js or Angular where appropriate.
3. Keep permanent credentials on your backend
Implement an authenticated token endpoint in your application. The backend chooses the SIP identity the signed-in user is allowed to use and requests a short-lived browser token from IllyVoIP using the account API key. Return only the documented browser-token payload.
Do not accept an arbitrary SIP identity from browser JSON and forward it without authorization. Recheck access on later token issuance, not only at initial login. Keep API keys and SIP passwords out of browser bundles, local storage, repositories, screenshots and ordinary logs.
Use the managed-token example from the current reference to create the phone. Raw SIP mode is an advanced alternative for applications deliberately managing SIP, WSS and ICE settings; it is not a reason to expose an account’s permanent API key.
4. Make readiness and call controls visible
Subscribe to the documented connection, registration and call events. Show incoming, active, held, ending and ended states as appropriate. A visible keypad does not establish registration; registration does not establish incoming routing or two-way audio.
Request microphone permission through a clear user action. Provide supported audio-device selection, explain permission denial and handle playback restrictions visibly. Bind each call action to the selected call object or ID and prevent competing button submissions.
Default SDK hold is local audio control. Regional fallback is connection recovery, not migration of an active call. Follow the focused guides for incoming Answer and Decline, mute, hold and keypad controls, transfer, regional fallback and token refresh.
5. Define cleanup and identity changes
Keep one owner across routes that should share calling. During logout or account switching, block new actions, follow your intended active-call policy, dispose listeners and destroy the old owner before a replacement can register. Clear account-specific state so a new user cannot inherit the previous user’s call panel.
Handle initialization, cleanup and session-conflict failures explicitly. A failed destroy operation is not permission to silently create another registration. Do not assume the SDK supplies your complete multi-device or background-calling policy.
6. Verify the installation and upgrade deliberately
First confirm the intended SDK and runtime assets load, the backend authorizes the right identity and one owner registers. Test denied tokens, missing runtime files, microphone denial, route changes, logout and lost connectivity with local fixtures where possible.
During an authorized live acceptance session, check incoming and outgoing calls, answer/end, microphone and speaker audio, and every additional control you expose. Use controlled destinations and check charges. The SDK Playground is a separate real calling tool; opening a guide does not authorize repeated paid test calls.
For an upgrade, deploy a matched bundle in a test environment and repeat the acceptance cases before changing your production asset reference. Preserve the version and sanitized errors when investigating a regression. Do not infer native mobile, suspended-tab or headset compatibility from a successful desktop registration.
Diagnose by stage
Authorization failures belong to the backend and user-to-identity mapping. Asset failures belong to deployment paths, responses and runtime loading. Signaling failures need region/network/registration evidence. Connected audio failures need permission, device and media-path evidence. Use preflight and call statistics to collect bounded, sanitized evidence rather than logging complete bootstrap data.
Related guides and reference
- Start with the API, Playground and webhooks
- Manage the IllyVoIP WebRTC Phone SDK lifecycle in React
- Add IllyVoIP browser calling to a Vue 3 application
- Add IllyVoIP browser calling to a Next.js App Router application
- Integrate the IllyVoIP WebRTC Phone SDK into Angular
- Add microphone and speaker selection to the IllyVoIP WebRTC SDK
- SDK installation
- Backend token endpoint
- SDK methods
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.