Install the widget

Add the Voicello voice widget to any website with one script tag, check that it shows, and fix the common problems.

The widget goes on your site with one script tag. You add your site's domain in the dashboard, copy the tag, and paste it into your pages. This guide covers any website. If you use WordPress, Shopify, Webflow, React or Next.js, the guide for that platform shows where the tag goes.

Before you start

You need four things:

A published agent. The widget only goes live for an agent that is published. See Create your first agent.
A widget for that agent. Open the agent, choose the Widget tab, then Set up widget. Start from your voice agents.
A site served over HTTPS. Browsers only allow the microphone on secure pages, so the widget does not load on a plain http address. localhost is the one exception.
A way to edit your site's HTML, or someone who can. This page is public, so you can send them the link.

Add your website's domain
Open your agent's Widget tab, choose Edit widget, then open the Deploy tab. Under Verified domains, type your domain (for example example.com), add it, and choose Save changes.
The widget shows only on the domains in this list.
- www.example.com and example.com count as the same domain. Add either one.
- Any other subdomain, such as shop.example.com, needs its own entry.
- Wildcards and IP addresses are not accepted.
- Add localhost if you want to try the widget on your own machine first.
Copy the install code
On the same Deploy tab, find Install on your website and choose Copy code. The code is one script tag that looks like this:
HTML
```
<script src="http://localhost:3000/widget.js" data-key="YOUR_WIDGET_KEY" async></script>
```
YOUR_WIDGET_KEY is a stand in. The code you copy from the Deploy tab already has your widget's own key in it. The key is not a secret: it only names which widget to load.
Paste it into your site
Paste the tag into the HTML of every page where the widget should show, just before the closing </body> tag. Most sites have one shared layout or footer file, so pasting it there covers the whole site.
The tag also works inside <head>. It loads in the background either way, so it does not slow the page down.
Add the tag once per page. A second copy is ignored.
Check that it shows
Open your site in a new browser tab. The widget's launcher button appears in the corner you chose on the Placement tab. Choose it, allow the microphone when the browser asks, and talk to your agent.

Start with the Deploy tab. Under Widget status it lists what the widget still needs before it can go live, and each line links to where you fix it.

Nothing appears on the page

Cause	Fix
Your domain is not in the list	Add it under Verified domains and save. Check the spelling, and remember that subdomains other than `www` need their own entry.
The agent is not published	Publish the agent. See Create your first agent.
The widget is paused	On the Deploy tab, choose Resume widget.
The key was rotated	Rotating the key stops the old script from working. Copy the code again and replace the tag on your site.
Your site has a Content Security Policy	Allow the address in the tag's `src` as both a script source and a frame source.

The browser console shows a message

When the script loads but cannot start, it writes one line to the browser console that begins with [Voicello] The voice widget was not loaded:. The rest of the line says why.

Message ends with	What it means
`the script tag has no data-key`	The tag was changed after copying. Copy the code again and paste it whole.
`it is already on this page`	The tag is on the page twice. This is harmless, but you can remove the second copy.
`the page is not served over HTTPS`	Serve the page over HTTPS.
`this browser cannot use the microphone`	The visitor's browser has no microphone support, so the widget stays hidden for them.
`this browser does not support voice calls`	The visitor's browser is too old for live calls, so the widget stays hidden for them.

To hide the widget for a while, choose Pause widget on the Deploy tab. Calls that are running go on, and new ones are refused. To remove it for good, delete the script tag from your site.

Install the widget

Before you start