Installing the widget

The widget puts your Voice agent on your website. Visitors click a floating button and talk to the agent by voice or text, in the browser, with no phone number to dial. Because the conversation runs on your site, you can pass what you already know about the visitor (name, email, plan) into the agent as variables. This guide covers the no-code setup in the dashboard. Developers who want their own UI, authentication, or React Native support should continue to the Web SDK.

A sample web page with the Callers call window open in the bottom-right corner showing a conversation transcript — The widget on a page during a voice call: the floating launcher expands into a call window with the live transcript.

The widget is enabled per account. If you don’t see a Widget tab in Channels, email to turn it on.

Before you start

A Voice agent set to Incoming in General Settings. The widget never dials out; visitors start the conversation. The Widget tab only appears on incoming Voice agents.
The agent is saved. The installation code is generated from the saved agent.
Access to your website’s HTML, or to a tag manager that can inject a script tag.

If you already run a phone agent you’d like on your website, duplicate it and set the copy to Incoming. One agent can accept both incoming phone calls and web calls, but keeping them separate makes results easier to read.

Open the Widget tab

In the agent header, click Channels, then the Widget tab.

Turn it on

Switch on Enable widget (“Let visitors call this campaign from your website”). This also creates the agent’s web call secret, used only for the Custom integration.

Save

Save the agent. Until it is saved, the tab shows “Save your campaign to get your widget installation code.”

Two options appear on the left: Embed on Web (one script tag, no code) and Custom (the Web SDK). Most sites use Embed on Web.

Step 2: Your Domains

List every hostname the widget is allowed to run on. Type a domain (for example example.com), then press Enter or click Add. Each domain becomes a removable chip. When a visitor opens the widget, Callers checks the page’s origin against this list and refuses the call if it isn’t there.

Matching is exact:

example.com does not cover www.example.com or app.example.com. Add each hostname you use.
Wildcards are rejected (“Wildcards are not allowed”).
A full URL you paste is reduced to its hostname, and ports are dropped. A page on localhost:3000 won’t match localhost. For local development use a token (see Custom integration).
An empty list blocks every call with No allowed origins configured.

Step 3: Bot protection

Bot protection stops scripts and bots from starting conversations and using up your minutes. Callers uses Cloudflare Turnstile, which is free and invisible to most visitors.

Create a Turnstile widget

Open the Cloudflare Turnstile dashboard and create a widget.

Add your website domains

In Cloudflare, add the same hostnames you listed under Your Domains.

Paste both keys

Copy Cloudflare’s Site key and Secret key into the matching fields in Callers, then save the agent.

Protection turns on only when both keys are filled in. Clear either field to turn it off. The secret key stays in Callers because the check runs on Callers’ servers, not in the visitor’s browser.

Once on, bot protection applies to both Embed on Web and Custom integrations. A token does not bypass it. Details for developers are in Bot protection.

Step 4: Copy the code

Copy the snippet from Copy the code and paste it before the closing </body> tag on every page where the widget should appear.

<script
  src="https://cdn.callers.ai/sdk.js"
  data-agent="YOUR_AGENT_ID"
></script>

That is the whole installation. The floating button appears in the bottom-right corner as soon as the script loads.

Older snippets use data-campaign instead of data-agent. Both keep working. If both are present, data-agent wins.

Pass visitor information

If the agent has variables, the snippet includes a data-vars attribute with a placeholder for each one:

<script
  src="https://cdn.callers.ai/sdk.js"
  data-agent="YOUR_AGENT_ID"
  data-vars='{"name":"{{ name }}","email":"{{ email }}"}'
></script>

Replace the {{ name }} placeholders with real values from your page or template engine before the HTML reaches the browser:

<script
  src="https://cdn.callers.ai/sdk.js"
  data-agent="YOUR_AGENT_ID"
  data-vars='{"name":"Jane Doe","email":"jane@example.com"}'
></script>

Placeholders are not filled in automatically. If you leave them, the agent greets visitors with the literal text {{ name }}. Mark variables you can’t supply from the page as optional in the agent’s Variables.

Common script-tag attributes

Attribute	What it does
`data-agent`	The agent to connect to. Required unless you use `data-token`. `data-campaign` is the legacy name.
`data-token`	A server-generated token instead of `data-agent`. See Custom integration.
`data-vars`	JSON object of agent variables. Must be valid JSON; invalid JSON is logged in the browser console and ignored.
`data-theme`	`"light"`, `"dark"`, or a full theme JSON. See Styling the widget.
`data-fab-text`	Label next to the button icon. Leave it out for an icon-only button.
`data-show-fab`	Set to `"false"` to hide the floating button and open the widget from your own code.
`data-launcher-position`	`bottom-right` (default), `bottom-left`, `top-right`, or `top-left`.
`data-avatar`	Shows a stock avatar (`maya` or `john`) during the call. See Avatars.
`data-page-guide`	`"true"` lets the agent see a summary of the page the visitor is on. See Page Guide.

The full list, including audio and avatar options, is in Script tag attributes.

Avatars and Page Guide

Two features are set on the script tag rather than in the dashboard: a talking avatar that gives the agent a lip-synced face during voice calls (data-avatar="maya", with layouts, framing and backgrounds), and Page Guide, which lets the agent see a summary of the page and highlight or scroll to elements while it talks (data-page-guide="true"). Add the attributes to the snippet you copied, and use the playground to preview the result against your agent before you deploy. Avatars can also be previewed in the dashboard’s Test > Web Call tab, where you pick an Avatar and an Avatar background for that test call only.

Custom integration

Use the Custom option when you need your own launch button, a conversation embedded in your page layout, logged-in visitors, or a mobile app. It uses the Web SDK and authenticates with a short-lived token that your server signs. The Custom tab shows three steps: install the SDK, Authenticate (your agent’s web call secret, masked), and Initialize the SDK with a code sample that includes your agent’s variables.

Never put the web call secret, or an API key, in browser code. Anyone who reads your page source could start calls on your account. Only your server should sign tokens.

Tokens can be signed with either the agent’s web call secret or any of your organization’s API keys. A valid token is accepted from any origin, so the domain list doesn’t apply, which also makes tokens the right choice for local development. Bot protection, if on, still applies. The SDK is loaded from https://cdn.callers.ai/sdk.js. Start with the SDK quickstart and Authentication, which show the token format and server code in several languages.

Test the web call

You don’t need a website to try the agent. Click Test in the agent header, choose the Web Call tab, fill in any variables, and start the call. The conversation runs in the dashboard with the same widget your visitors see, including in-call forms. See Testing your agent. To try the widget with different settings, themes, and avatars against your real agent, use the SDK playground.

Verify the installation

Load the page

Open a page where you pasted the snippet. The floating button should appear within a second or two.

Start a conversation

Click the button and allow microphone access. Try both speaking and typing in the text box.

Check the results

Open the agent in Callers and confirm the conversation appears with its transcript. Web calls are listed with your other calls.

Common errors

Message	Meaning	Fix
`No allowed origins configured`	Your Domains is empty.	Add at least one hostname, or use a token.
`Origin '...' is not allowed for this campaign`	The page’s hostname isn’t on the list.	Add that exact hostname, including the subdomain, and save.
`Origin header is required`	The page was opened from a `file://` path.	Serve the page over `http://` or `https://`.
`Web calls not enabled for campaign`	Enable widget is off.	Turn it on in Channels → Widget and save.
`Bot verification is required` / `Bot verification failed`	Turnstile is on but the challenge didn’t pass.	Check both keys, and that the page’s hostname is in your Cloudflare Turnstile widget.
`Invalid web call token`	The token is expired, malformed, or signed with the wrong secret.	Generate a fresh token on your server.

The widget doesn't appear at all

The agent greets visitors with {{ name }}

The data-vars placeholders were never replaced. Your page or server must substitute real values before the HTML is served.

It works in production but not on localhost

Ports aren’t stored, so localhost:3000 doesn’t match localhost. Use a token for local development.

Visitors can start one conversation but not a second

With bot protection on, each conversation gets its own challenge. After a call ends, the visitor closes and reopens the widget to start another one.

More cases are in the SDK troubleshooting page.

Styling the widget

Themes, the Widgets library, and matching your brand.

In-call forms

Collect structured answers with forms during the call.

Web SDK

Full control: methods, events, headless mode, React Native.

Call transfers

Hand a web call to a human operator queue.

Talking avatars

Give the agent a lip-synced face on voice calls.

Page Guide

Let the agent see the page and point at elements.

Get started

Build your agent

Guardrails and security

Test and deploy

Voice

Channels

Contacts and outreach

Results and analytics

Human operators

Best practices

Account and administration

Enterprise

Resources

Installing the widget

Before you start

Step 1: Enable the widget

Step 2: Your Domains

Step 3: Bot protection

Step 4: Copy the code

Pass visitor information

Common script-tag attributes

Avatars and Page Guide

Custom integration

Test the web call

Verify the installation

Common errors

Styling the widget

In-call forms

Web SDK

Call transfers

Talking avatars

Page Guide

Before you start

Step 1: Enable the widget

Step 2: Your Domains

Step 3: Bot protection

Step 4: Copy the code

Pass visitor information

Common script-tag attributes

Avatars and Page Guide

Custom integration

Test the web call

Verify the installation

Common errors

Related

Styling the widget

In-call forms

Web SDK

Call transfers

Talking avatars

Page Guide