urvo - Documentation

Overview

The widget lets visitors talk to one of your agents directly from your website, over the browser's microphone, with no phone call and no phone number involved. It is a single script tag, so it works on any page you can add HTML to.

Widget conversations are ordinary conversations. They appear in call analytics with transcripts alongside phone calls, they consume plan minutes, and they run the same prompt, tools and knowledgebases as the agent's phone calls.

Get the snippet

Open the agent you want to embed and go to Configuration.
Scroll to the Advanced section and find Widget.
Click the copy button next to the snippet.

The snippet looks like this, with your agent's ID already filled in:

<script src="https://app.urvo.io/widget.js" data-agent-id="YOUR_AGENT_ID" async></script>

Paste it into the HTML of any page where you want the widget to appear, ideally just before the closing </body> tag. The async attribute means it will not block your page from rendering.

The data-agent-id attribute is what selects the agent. To embed a different agent, copy the snippet from that agent instead of editing the ID by hand.

Allowed domains

A widget with no domain restrictions could be lifted off your site and embedded anywhere, burning your minutes on someone else's page. To prevent that, the widget only runs on domains you explicitly allow.

In the same Advanced section, find Allowed Domains.
Add each domain the widget should work on.
Save the agent.

The list is not optional in practice. If a page's domain is not on the list, the widget will not start a conversation there. This is the single most common reason a correctly pasted snippet appears to do nothing, so add your domain before you test.

Remember to add every hostname you actually serve from. A staging site, a www variant, and a preview deployment are all different domains as far as the check is concerned.

How it works

When a visitor starts a conversation, the widget asks urvo for a short-lived signed token. urvo validates the requesting domain against your allowed list before issuing it. Audio then flows through a urvo server that relays it to the voice provider.

The practical consequence: no provider API key or account credential is ever present in the browser. There is nothing sensitive in the snippet, so it is safe to put on a public page, commit to your site's repository, or serve through a CDN. The only thing the page carries is your agent ID.

Microphone permission

Browsers only grant microphone access on secure origins, so the page must be served over HTTPS (localhost is treated as secure for local development). The visitor is prompted for microphone permission by their browser the first time they start a conversation. If they decline, the widget cannot capture audio — that prompt belongs to the browser and urvo cannot bypass or re-trigger it.

Troubleshooting

Symptom	Likely cause	Fix
Widget never appears	Script not reached, or the page's domain is not allowed	Confirm the tag is in the served HTML, then add the exact domain to Allowed Domains.
Appears, but a conversation never starts	Domain rejected when requesting a token	Add the hostname exactly as it appears in the browser address bar, including any `www`.
Agent hears nothing	Microphone permission denied, or the page is not HTTPS	Serve over HTTPS and reset the site's microphone permission in browser settings.
Works locally, not in production	Only the development host was allowed	Add the production domain too. Both can be on the list at once.
Conversation ends immediately	Workspace is out of plan minutes	Check remaining minutes in billing.

Next steps

To share an agent without touching your website at all, use a shareable agent link.
To let the embedding page change the agent's language, greeting or voice per visitor, see overrides.
To review what callers said, see analyze calls.

Website Widget