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.

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.