Pass a tones object when creating your IllyVoIP Webphone SDK owner to control its local incoming and outgoing sounds. These are browser-generated notifications. Outgoing local sound is not proof that the far-end telephone rang or that a call was answered.
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. Add tone options to the existing owner
Merge the following into the options used by your existing phone creation code. Keep its token provider, bootstrap URL and identity authorization unchanged. Do not create another phone just to play a ringtone.
const toneOptions = {
enabled: true,
incoming: { enabled: true, volume: 0.08 },
outgoing: { enabled: true, volume: 0.05 }
};
// Include this property in your existing SDK creation options:
const optionsWithTones = { ...managedOptions, tones: toneOptions };The example uses the reviewed default volumes. Volume ranges from zero to one; choose a comfortable level on the actual output device. Set the whole object’s enabled value to false to disable both local channels, or disable just incoming or outgoing when another part of your application deliberately owns that sound.
2. Choose synthesized sound or an owned audio asset
A channel can specify frequencies and cadence for synthesized sound, or src or an audio element for a sound you are entitled to use. Frequencies are in hertz; cadence entries alternate sound and silence in milliseconds. Avoid extremely loud or continuous tones.
const incomingTone = {
enabled: true,
volume: 0.08,
frequencies: [440, 480],
cadence: [350, 180, 350, 1800]
};For a custom file, serve a browser-playable asset from your controlled HTTPS deployment and verify its actual response and MIME type. A login page returned at the audio URL is not a ringtone. Use one custom source deliberately rather than relying on undocumented precedence between competing element and source settings.
3. Make browser playback available
Provide a clear user action to enable the phone. Browser autoplay policies can block audible playback until interaction, and suspended/background contexts have additional limitations. The SDK primes its tone system through calling controls, but this is not a universal bypass. Show a visible incoming-call state even when sound is unavailable.
- Open the application in the target browser and use its explicit phone-enable action.
- Check the tab is not muted and the intended speaker or headset is selected.
- If a custom audio element’s playback fails, handle its rejected playback promise in your own UI where you own that element.
- Repeat after a fresh session; a browser that already allowed audio can hide a first-use problem.
4. Check when sounds start and stop
The SDK uses signaling progress and media state for outgoing tone behavior. Do not add a second unconditional loop as soon as call creation begins. Incoming ringing should also be tied to the real incoming call rather than an old event left in a notification panel.
- Test one authorized incoming call, answer it and confirm local ringing stops.
- Test decline and remote cancellation separately.
- For outgoing calls, distinguish early media from local sound and check the transition to answered audio.
- End the call and confirm no tone remains. Repeat cleanup during your application’s normal logout or navigation policy while idle.
First exercise those events with your application’s local fixtures. Real calls are still needed to hear playback on your actual browser and audio hardware, and can incur charges. A fixture that receives an event does not prove audible ringing.
Diagnose duplicate or missing sound
Duplicate ringing often warrants checking whether two SDK owners or an extra application audio loop exist; do not assume a network fault. For silence, check enabled flags, volume, asset loading, browser permissions and output routing. Preserve the SDK version and event sequence for Support without logging complete tokens or bootstrap credentials.
Related guides
- Add browser calling with the Webphone SDK
- Diagnose missing ringback and early audio on an IllyVoIP SIP call
- Add microphone and speaker selection to the IllyVoIP WebRTC SDK
- Diagnose an IllyVoIP SDK call with preflight checks and WebRTC statistics
Reference
Current instructions and technical reference: MDN: browser autoplay policies.
Reviewed 12 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.