# How to add an ElevenLabs voice FAQ widget to one website page
> Set up a dedicated public ElevenLabs FAQ agent, restrict its allowed hostname, embed the voice widget on one page, and check a live conversation, privacy settings and usage.
By BIG CHANGE Editorial
Published: 2026-10-20T06:57:39.691Z
Updated: 2026-10-20T06:57:39.691Z
Canonical: https://bigchange.ai/blog/elevenlabs-voice-faq-widget-website-guide
AI-generated conceptual illustration by BIG CHANGE.
An ElevenLabs widget can let visitors ask spoken questions on a website. This guide is for the person who manages both the page and the ElevenLabs agent. It takes one narrow public FAQ from agent setup through a live page check, then shows how to inspect access, conversation records and usage. The steps reflect ElevenLabs documentation checked on 20 October 2026. BIG CHANGE did not create an agent, embed a widget or make a test call.
## The big change
- **What:** ElevenLabs documents a website widget for a public ElevenAgents agent, with voice as its default mode.
- **How:** The page loads a custom element using the agent's visible ID. The agent's hostname allowlist controls which site origins may connect.
- **Why it matters:** A site owner can check a spoken visitor help path on one page, but must approve the public information, visitor notice and potential call charges before exposing it. A hostname allowlist does not identify individual visitors.
## Prepare a public FAQ and a small test
You need permission to manage one ElevenLabs agent and edit and publish one site page. Have an HTTPS page, a browser with a working microphone, and a person who can approve the FAQ and listen to its answers. Your site's publishing tool must permit the documented custom element and script; use that tool's current method for adding custom HTML. The example below is the provider's plain HTML embed, not platform-specific installation advice.
Write down a few **approved public facts** the agent may answer, plus a human contact route for requests outside that scope. Choose one question whose answer appears in those facts and one question the agent should decline or refer to a person. Keep customer records, private policies, account details and API secrets out of this public agent. Decide who can approve the site's voice and visitor-facing notice. Check that the selected ElevenLabs voice and your account terms permit the intended site use; this guide establishes no universal commercial voice entitlement.
Before any voice test, inspect your actual ElevenLabs plan, remaining credits, pay-as-you-go setting and the selected model's cost information. ElevenLabs says creating an agent is free, while connected voice calls consume usage and LLM charges can be separate. Connection time can exceed the time spent speaking. Get the site's spending approval for the dashboard and live calls before starting either. A per-call time limit constrains one conversation; it is not a monthly spending cap.
## Configure the dedicated agent
1. **Create a separate public FAQ agent** in the ElevenLabs dashboard. Use an approved blank or template setup, then check its inherited knowledge and tools. Remove any private knowledge, booking, CRM, webhook or other action the public FAQ does not need. Set its purpose and answer boundary from the approved facts, include the human contact route, and choose a voice and language you are authorized to use. Do not turn an existing private agent into this public widget by disabling its authentication.
2. Under **Channels → Widget → Interface**, select the intended voice interface and review the visitor-facing text and terms. The current manual also calls part of this the **Widget** tab, so verify the saved controls in your dashboard. The embed route below requires a **public agent with authentication disabled**, which the manual locates in **Advanced**. The agent ID will be visible in the page source; it is not a secret. Keep API keys and personal or visitor-specific information out of the markup and widget overrides.
3. In the agent's **Security** tab, add the exact site hostname to its **Allowlist**, save it, and read it back. ElevenLabs says it matches hostnames exactly, permits up to ten, and requires each subdomain separately. Add a local test hostname only if you actually need that test origin. The allowlist restricts where a connection may start; it does not authenticate the person speaking.
4. Review the agent's privacy controls for transcript retention and audio saving, and approve the visitor notice and consent process appropriate to your site. The widget can show owner-supplied terms before a call, but that screen and the browser's microphone permission do not settle your site's legal obligations. In **Advanced → Call limits**, set and save a suitable **Max conversation duration**. ElevenLabs documents a 600-second default and a 60–7,200-second range. Read back the saved privacy, duration and access settings before a billable test.
## Add the embed to one draft page
Place the following in the page body using your site's supported custom HTML or script facility. Replace `YOUR_PUBLIC_AGENT_ID` with the dedicated agent's ID. Keep the initial rollout to the one approved page.
```html
```
This is the current [official widget embed](https://elevenlabs.io/docs/eleven-agents/customization/widget). Its script URL is **unversioned**; record what you installed and recheck the manual when maintaining the page. On a draft preview, confirm the widget appears once and does not cover essential page controls. If your site enforces a Content Security Policy, have its maintainer inspect the actual blocked script or connection requests and make a narrow, reviewed change. Disabling the policy or adding broad wildcards is not a setup step.
## Check the agent, then the live visitor path
After the cost and privacy review, ask the answerable and out-of-scope questions in the dashboard voice test. Compare the replies with the approved facts and the human referral boundary. Revise the agent and test again if either answer is unsafe or unsupported. A dashboard call confirms only that dashboard path; it does not establish that the site embed works.
Have the page owner review the content, notice, placement and test result before publishing. On the **live page at the allowlisted hostname**, open the widget in a browser, deliberately grant microphone permission, ask the same two questions, listen to both replies, and end the call. Check that the microphone indicator turns off and the widget remains usable on a phone-sized view. Compare what it actually said with the approved answers; a fluent answer is not proof that its facts are right. Record the test time and agent so you can investigate its usage. This is a check for the reader to perform, not a result observed by BIG CHANGE.
Open **Call history** for the agent if the chosen retention setting preserves a record, and inspect the conversation against the two questions. In **Analytics**, filter to that agent and a narrow time window and review call count, duration and cost. These are aggregate figures; they cannot alone prove which call produced a charge. If your approved retention setting deletes conversation records, keep only the minimal owner-approved observation of the live answer and review the available aggregate usage. Do not lengthen retention just to complete this check. An absent retained record does not prove the call was free.
## If the check fails
If no widget appears, compare the actual published markup with the [documented embed](https://elevenlabs.io/docs/eleven-agents/customization/widget), check for duplicate elements or scripts, and inspect specific browser script or CSP errors. If it appears but cannot connect, read back the dedicated agent's public authentication setting, the exact live hostname on the allowlist, microphone permission, available credits and any dashboard error. If speech fails, check the selected microphone, browser permission and secure page context, then inspect the available call record. End an uncertain session and look at usage before paying for another attempt.
If the agent invents an answer or strays beyond the FAQ, remove the embed from the page while revising its approved facts and instructions. Repeat both dashboard and live questions before restoring it. If usage is higher than approved, remove the embed, inspect the filtered analytics and account billing, and reconsider the conversation duration and rollout. Removing this page's embed stops this page offering new calls; it does not prove an existing call has ended or remove access to the public agent from another permitted host.
For a local developer-built browser voice application, [our OpenAI Realtime guide](https://bigchange.ai/blog/openai-realtime-browser-voice-webrtc-guide) covers a different task. This guide uses the hosted ElevenLabs public widget. The widget manual lists a `signed-url` attribute elsewhere, but its basic embed instructions explicitly require a public agent; that attribute alone is not a tested private-widget recipe.
## Sources & further reading
- [ElevenLabs widget customization](https://elevenlabs.io/docs/eleven-agents/customization/widget): the public-agent requirement, interface controls and current embed. The script URL is unversioned.
- [Agent authentication](https://elevenlabs.io/docs/eleven-agents/customization/authentication): exact hostname allowlist behavior, ten-host limit and distinction from per-user authentication.
- [Conversation flow](https://elevenlabs.io/docs/eleven-agents/customization/conversation-flow) and [privacy controls](https://elevenlabs.io/docs/eleven-agents/customization/privacy): duration, retention and audio-saving settings.
- [ElevenAgents quickstart](https://elevenlabs.io/docs/eleven-agents/quickstart), [Analytics](https://elevenlabs.io/docs/eleven-agents/dashboard) and [cost help](https://elevenlabs.io/docs/help-center/product/eleven-agents/how-much-does-eleven-agents-cost): dashboard tests, history, aggregate usage and charging basis. Account terms determine the actual allowance and bill.
## Sources
- [Widget customization](https://elevenlabs.io/docs/eleven-agents/customization/widget) — Checked 20 October 2026. Official public-agent requirement, widget modes, basic custom element and current unversioned script. It does not verify a private signed-widget implementation.
- [Agent authentication](https://elevenlabs.io/docs/eleven-agents/customization/authentication) — Checked 20 October 2026. Exact hostname allowlist and ten-host limit; the allowlist is origin control, not visitor authentication.
- [Conversation flow](https://elevenlabs.io/docs/eleven-agents/customization/conversation-flow) — Checked 20 October 2026. Per-conversation duration default, range and dashboard save control; no aggregate spend cap established.
- [Privacy](https://elevenlabs.io/docs/eleven-agents/customization/privacy) — Checked 20 October 2026. Transcript retention and audio-saving controls; actual site notice and lawful basis require owner review.
- [ElevenAgents quickstart](https://elevenlabs.io/docs/eleven-agents/quickstart) — Checked 20 October 2026. Dashboard setup and test, Call history and the official website widget snippet; no BIG CHANGE test.
- [Analytics](https://elevenlabs.io/docs/eleven-agents/dashboard) — Checked 20 October 2026. Agent/time filtering and aggregate count, duration and cost; aggregates cannot alone identify one test call.
- [How much does ElevenAgents cost?](https://elevenlabs.io/docs/help-center/product/eleven-agents/how-much-does-eleven-agents-cost) — Checked 20 October 2026. Agent creation, connected call duration and separate LLM costs; account-specific plan, credit and voice rights must be verified.