Troubleshooting

Common issues and solutions for the Convirza Dialer SDK.

Authentication issues

Problem: auth-failed event fires

Symptoms: widget shows an error message; console logs [Dialer] Login failed or [Dialer] Auto-config failed; event detail contains an error message.

1. Wrong credentials

Verify username/password are correct. Check: email matches the Convirza account, password is correct (no typos, caps lock), the account has the Dialer feature enabled, and the user has an assigned extension in the Dialer Portal.

2. No dialer access — Error: "No dialer domains configured for this user"

Contact your Convirza admin to enable the Dialer feature, assign an extension to your user, and configure dialer permissions in the Dialer Portal.

3. Network/CORS errors — Error: "Login failed: Failed to fetch"

Check internet connection; verify the OAuth endpoint is accessible (https://oauth.convirza.com); check the browser console for CORS errors; if behind a corporate firewall, ensure the OAuth endpoint is whitelisted.

SIP registration issues

Problem: sip-registration-failed event fires

Symptoms: widget loads but no "SIP registered" message; cannot make calls; console logs [Dialer] SIP registration failed.

1. WebSocket connection blocked

Check the firewall allows WebSocket connections; verify wss:// is not blocked; try a different network (mobile hotspot to test); contact IT to whitelist the SIP proxy servers.

2. Domain mismatch — Error: "403 Forbidden". Internal issue — contact Convirza support (domain/realm configuration mismatch on the server).

3. Invalid SIP credentials — Error: "Authentication failed". Re-login (destroys the widget and re-initializes); clear browser cache/cookies; contact Convirza support if it persists.

Audio issues

Problem: no audio during a call

Symptoms: call connects but you cannot hear the other party (or they cannot hear you); microphone icon shows muted but unmuting doesn't work.

1. Microphone permission denied

Click the lock icon in the browser address bar, change microphone permission to "Allow", refresh the page, and try the call again.

2. Wrong audio device selected

Open widget → Account tab, select the correct microphone and audio device (Chrome/Edge only), and test audio after switching.

3. Browser audio muted — check the browser tab is not muted, system volume is up, and the headphone/audio device is connected properly.

Call issues

Problem: calls fail immediately

Symptoms: call goes to "error" state immediately; console shows a call-failed event; no ringing.

1. Invalid phone number — use E.164 format: +[country code][number] (e.g., +12485551234). Remove spaces, dashes, and parentheses.

2. Calling while already on a call

End the current call first (dialer.endCall()), confirm the widget shows "idle" state, then place the new call.

3. SIP session not registered — wait for the sip-registered event before calling:

Problem: widget not showing

1. Z-index conflict — dialer.setAttribute('z-index', '9999');

2. Position off-screen — dialer.setAttribute('position', 'bottom-right'); dialer.setAttribute('state', 'collapsed');

3. CSS conflicts — the widget uses shadow DOM, so global styles shouldn't affect it. Check for !important rules targeting all elements.

Method call errors

Validation rules:

Method	Requires Active Call?	Error if No Call?
`open()`, `close()`, `toggle()`	No	Never throws
`setTheme()`	No	Never throws
`placeCall()`	No (requires idle)	Yes — throws if call active
`endCall()`	No	No — silent no-op
`mute()`, `hold()`	Yes	No — returns current state
`sendDTMF()`	Yes	No — silent no-op

Check call state before calling methods:

Browser compatibility

Browser	Version	Notes
Chrome	90+	✅ Full support (recommended)
Edge	90+	✅ Full support
Firefox	88+	⚠️ No audio device selection
Safari	14+	⚠️ No audio device selection, may require user gesture

Known issues — Safari: first call may require user interaction (click a button); audio device selection not available. Firefox: audio device selection not available. Mobile: iOS Safari works but audio device is on by default; Android Chrome has full support.

Common error messages

Error Message	Cause	Solution
`Login failed: 401 Unauthorized`	Wrong credentials	Check email/password
`No dialer domains configured`	Account missing dialer setup	Contact admin to enable Dialer
`No extension configured`	User has no extension	Contact admin to assign extension
`SIP registration failed`	Network/firewall blocks WebSocket	Check firewall, try different network
`Cannot place a call while another call is connected`	Call already active	End current call first
`Phone number is required`	Empty phone number	Pass a valid E.164 number
`No active call`	Method requires a call	Wait for the call to connect

Still having issues?

Before contacting support: check this guide, test in a different browser, test on a different network, and collect error details (console logs, network tab, screenshot, steps to reproduce).

Contact Convirza Support — Email: support@convirza.com. Include: SDK version (e.g., 1.1.6), browser + version, operating system, exact error message, steps to reproduce, and when the issue started. Response time: 1-2 business days. For urgent issues, mark the subject [URGENT] Dialer SDK - <brief description> and include impact.

Additional resources

Quickstart Guide — get started in 10 minutes

API Reference — complete method documentation

Configuration & Theming — customize widget appearance

SDK GitHub — report bugs, request features

Last updated: July 2026 | SDK v1.1.6

Troubleshooting

Authentication issues#

SIP registration issues#

Audio issues#

Call issues#

Widget UI issues#

Method call errors#

Browser compatibility#

Common error messages#

Still having issues?#

Additional resources#