Voicegram

Widget quickstart

Drop a one-line script tag onto any HTML page and a floating bubble appears in the bottom-right that lets visitors leave you voice messages.

On this page

The Voicegram widget is a single script tag. Add it once to your site and a floating microphone bubble appears in the bottom-right corner of every page that loads the script. Visitors click the bubble to leave you a voice message.

One-line install

Paste this tag into your site, with your own public key in the filename:

html
<script
  type="module"
  src="https://cdn.voicegram.io/w/pk_your_public_key.js">
</script>

That is the entire install. The floating bubble appears in the bottom-right corner. Visitors click it to leave a voice message.

Why type=module?

ES modules are required for the widget to load correctly. A plain <script> (without type="module") will not work.

Where to get your public key

Public keys start with the pk_ prefix and are tied to a specific domain in the Voicegram dashboard. To create or look one up:

  1. Go to Dashboard › Widgets. If you are not signed in, you will be prompted to log in and then sent straight to the Widgets page.
  2. Either pick an existing domain or click Add domain, enter your hostname, and click Save.
  3. Copy the pk_ public key shown on the domain detail page. This is the filename in the script src.

Public keys are safe to embed in client-side HTML. They authenticate the page domain against your account, not a secret. Secret keys (prefixed sk_) are for server-side API calls only and should never appear in browser code.

Verify the install

Once the script tag is on your page, run this four-step smoke test to confirm the widget is wired up correctly:

  1. Load the page. Hard-refresh (Cmd+Shift+R on macOS, Ctrl+Shift+F5 on Windows) to bypass any cached older bundle.
  2. Look for the bubble. A floating microphone button should appear in the bottom-right corner within a second of page load. If it does not, see Troubleshooting.
  3. Click the bubble. A modal should slide in with an email input field and a Send code button.
  4. Type a test email and submit. You should receive a 6-digit verification code at that address. Enter the code, grant microphone permission when prompted, record a short test message, and click Send. The recording should arrive in your Voicegram dashboard within a few seconds.

If all four steps pass, you are done.

Common install gotchas

  • Use type="module". Plain <script src=...> will not work. The widget's lazy-loaded chunks require ES modules.
  • Place the script near the end of <body>, or in <head> with defer. Loading it in <head> without defer blocks page rendering until the script downloads.
  • One install per page. Loading the widget script twice in the same page is unsupported. Each load overwrites the previous instance.
  • Match the registered domain. The public key is tied to a specific hostname. If your page hostname does not match the domain registered in the dashboard, the widget hides itself silently. Use a separate public key per domain.
  • Browser cache up to 24 hours. The widget bundle on cdn.voicegram.io is cached for one day. After an update, returning visitors may load a cached version briefly until their cache refreshes. New visitors get the new bundle immediately.

If your site has a Content Security Policy

Most sites do not, and if yours does not, the script tag above is genuinely all you need. Skip this section.

If your site does send a Content-Security-Policy header, add these entries or recording will fail after the visitor enters their verification code:

text
script-src  https://cdn.voicegram.io
connect-src https://www.voicegram.io https://*.livekit.cloud wss://*.livekit.cloud
media-src   blob:
style-src   'unsafe-inline'

Two things worth calling out, because both are easy to get subtly wrong:

  • https://www.voicegram.io needs the www. CSP host matching is exact, so https://voicegram.io on its own does not match it.
  • Use *.livekit.cloud, not a specific hostname. The realtime service fails over to regional hostnames, so a pinned host works right up until the first failover.

This is the single most common reason a correctly-installed widget still fails to record. See Troubleshooting for what each entry does and how to confirm a CSP is the cause.

Check your Permissions-Policy header too. It is a separate header, and if it disallows the microphone (microphone=()) recording fails before the CSP ever matters, so fixing only the CSP will not appear to help. It needs to allow microphone=(self).

Next steps

  • Customization. Wire the recorder to your own button, suppress the bubble on specific pages.
  • Framework recipes. Drop-in snippets for React, Next.js, WordPress, Webflow, Squarespace, Wix, and Shopify.
  • Programmatic API. Open and close the widget from JavaScript.
  • Troubleshooting. Solutions for the most common install problems.
Need help? Email support@voicegram.io.