Troubleshooting

If the widget is not behaving as expected, work through the checks below in order. Most issues are a stale browser cache, a mismatched public key, or a missing meta tag.

Known limitations

Some behaviors are by design. Confirm none of these match your situation before you dig deeper:

• Light DOM only. Triggers and the bubble both work in the light DOM. Closed Shadow Roots and (effectively) open Shadow Roots block trigger detection. Do not put data-voicegram-trigger inside encapsulated component shadow roots.
• Domain must match. The widget's public key is tied to a registered domain in the Voicegram dashboard. The widget hides itself on pages whose hostname does not match.
• Browser cache up to 24 hours. The widget bundle on cdn.voicegram.io is cached for up to 24 hours. After a widget update ships, returning visitors may continue to use the previous bundle for up to a day until their cache expires. New visitors get the new bundle immediately.
• Single instance per page. Loading the widget script twice in the same page is unsupported. Each init call overwrites the previous instance.
• iframes. The widget is scoped per document. A trigger in the parent page only fires if the widget is loaded in the parent. A trigger inside an iframe needs the widget loaded in that iframe.
• Mobile native. WebView-based apps work, pure native does not. See Mobile and native apps.

The bubble does not appear on my page

Symptoms. You added the script tag, but no floating bubble shows up in the bottom-right corner.

Work through these in order:

1. Hard-refresh. Browser cache may be serving an older script. Cmd+Shift+R (macOS) or Ctrl+Shift+F5 (Windows), or load the page in an Incognito window.
2. Check the public key matches the domain. Open DevTools, switch to the Network tab, reload the page, and look for a request to /api/config?publicKey=...&domain=.... If the response is { success: false, ... }, the key and domain do not match. Re-check the public key in the dashboard against the hostname of the page you are loading.
3. Check <meta name="voicegram-bubble">. If content="off" is set on the page, the bubble is hidden by design. See Customization.
4. Check the dashboard. If the domain is marked inactive in your Voicegram dashboard, the widget hides automatically.
5. Check window.__voicegram__ exists. In the DevTools console, type window.__voicegram__. If it is undefined, the script did not load. Look for network errors on the script URL, or for a Content Security Policy violation in the console.

Content Security Policy

If your site has a CSP and the script does not load, allow these origins:

• script-src. https://cdn.voicegram.io.
• connect-src. https://voicegram.io (for /api/config, session creation, verification), plus the wss:// realtime host shown in your dashboard (for live recording).
• media-src. blob: (for the local recording preview).
• frame-src. Not required. The widget does not use iframes.

A data-voicegram-trigger button does nothing

Symptoms. You added the attribute to a button, but clicking does not open the modal.

1. Confirm window.__voicegram__ exists. If the widget script did not load, the document-level click listener does not exist. See the bubble-does-not-appear section above.
2. Confirm the button's hostname matches. Cross-iframe triggers do not work. The widget must be loaded in the same document as the trigger.
3. Confirm the button is in the light DOM. Triggers inside Shadow Roots do not bubble correctly. See Customization › Light DOM only.
4. Confirm the button is not disabled. The browser blocks click events on disabled controls before the widget sees them.
5. Cmd-click and middle-click are intentionally ignored. Plain left-click only. This is so <a href data-voicegram-trigger> can still open in a new tab on Cmd-click.

The modal opens with default theme, then re-styles a moment later

Symptoms. A brief flash of the default Voicegram colors before your branded theme paints.

This should not happen on current widget versions. If you see this:

1. Hard-refresh to drop the stale browser-cached bundle.
2. If it persists, contact us. This is a bug.

The modal opens but my domain is disabled

Symptoms. A visitor opens the widget on a domain you have marked inactive in the dashboard.

This should not happen on current widget versions. If you see this:

1. Hard-refresh to drop the cached older bundle.
2. If it persists, contact us.

The verification email does not arrive

Symptoms. The visitor submits their email, but no 6-digit code arrives.

This is usually a backend or email-deliverability issue, not a widget issue.

1. Check the address spelling. Typos are the most common cause.
2. Check the spam folder. Verification emails go to spam occasionally on first contact with a sender.
3. Check the Voicegram dashboard error logs. Common causes surfaced there: the email address has DNS or disposable-domain validation issues, or your custom-domain email sending is misconfigured.
4. Try a different email. Some corporate mail filters silently drop transactional emails from new senders.

Recording fails on iOS Safari

Symptoms. The widget opens, the visitor enters the verification code, but the recording UI never appears or recording fails immediately.

1. iOS 14.3 or later is required. Earlier versions can't record in Safari, so ask the visitor to update iOS.
2. Microphone permission must be granted. When prompted, the visitor must tap Allow. If they previously denied permission, they have to clear the per-site permission in Settings › Safari › Camera & Microphone before the prompt re-appears.
3. Some captive-portal Wi-Fi networks block live recording. Public Wi-Fi at airports, hotels, and coffee shops occasionally blocks the live audio connection. Try cellular or a different network to rule this out.

CORS errors in the console

Symptoms. Console shows Access-Control-Allow-Origin errors against voicegram.io or cdn.voicegram.io.

These should not appear on properly registered domains. If they do:

1. Confirm your page's hostname is registered in the dashboard. Add the domain under Dashboard › Widgets.
2. Confirm you are using the public key (pk_*) and not a secret key (sk_*). Secret keys are server-side only and do not authenticate widget traffic.
3. If both check out and you still see CORS errors, contact us with the full console error.

Still stuck

If none of the above resolves your issue:

1. Capture a screenshot of the console errors (DevTools › Console).
2. Capture the network response for /api/config?publicKey=...&domain=... (DevTools › Network).
3. Note the widget bundle URL including any query parameters.
4. Contact us with those three artifacts.

Next steps

• Quickstart. The one-line install plus the four-step smoke test.
• Customization. Custom triggers and per-page bubble suppression.
• Mobile and native apps. Mobile-specific install gotchas.