Installing the Widget

The widget is a small piece of Callers that lives on your website. Visitors see a floating button in the corner of the page; when they click it, they can start a conversation with your AI agent right there in the browser - by voice or by text, with no phone number and no app to install. Because the conversation runs on your own website, you already know who the visitor is. You can pass their name, email, or plan into the campaign so the agent greets them by name and skips the questions you already have answers to.

No Phone Number Needed

Conversations run over the browser, so there are no per-minute telephony costs and no number to provision.

Voice or Text

Visitors choose how they want to talk. The same campaign script handles both.

Context From Your Site

Pass what you already know about the visitor into the campaign as variables.

Two Installation Paths

A one-line script tag for most sites, or the Web SDK when you need full control.

Widget campaigns are enabled per account. If you don’t see the Widget option described below, contact support@callers.ai to have it turned on.

Start a new campaign

From your dashboard, click New Campaign.

Open General Settings

In the campaign editor, open the General Settings modal.

Select Widget as the channel

In the channel row - Voice, Text, Email, Widget - choose Widget.

Name your campaign

Give the campaign a descriptive name so you can find it later, then close the modal.

General Settings modal with the Widget channel selected — Selecting Widget as the campaign channel in General Settings

Selecting Widget reconfigures the campaign automatically:

The campaign becomes Incoming. Your visitors start the conversation - the widget never dials out.
Outgoing phone numbers are cleared, and incoming phone calls are switched off. A widget campaign is reached through your website only.
A web call secret is generated for the campaign. You’ll need it only if you build a custom integration (see below).

Switching an existing campaign to Widget removes its phone numbers. If you want to keep a phone campaign running, create a separate campaign for the widget instead of converting the one you already have.

Build Your Script

A widget campaign uses the same script builder as a voice campaign. Write your steps, add actions, and set up variables exactly as you normally would - see Campaign Script and Campaign Variables. Any variables you define here become available to the widget, so you can pass real values from your website into the conversation.

Save your campaign before continuing. The installation code is generated from the saved campaign, so the installer stays empty until the campaign exists.

Step 2: Open the Installer

In the campaign toolbar, click the plug icon to open the Install the widget window.

Campaign toolbar with the widget connection button highlighted — The plug icon in the campaign toolbar opens the installer

This icon appears only on widget campaigns - it takes the place of the Channels button used by phone and messaging campaigns.

The window has two tabs:

Tab	Use it when
Embed on Web	You want the standard widget on your site. One script tag, no development work.
Custom	You need your own UI, your own launch button, or authenticated visitors. Uses the Web SDK.

Most sites should use Embed on Web.

Embed on Web

1. Add Your Domains

List every domain the widget is allowed to run on. Type a domain and press Enter to add it; each one appears as a removable chip. This list is a security boundary, not a suggestion. When a visitor opens the widget, Callers checks the page’s origin against this list and refuses the conversation if it isn’t there.

Domains are matched exactly. A few consequences worth knowing before you start:

Wildcards are rejected. *.example.com will not be accepted.
Subdomains are separate entries. Adding example.com does not cover app.example.com or www.example.com - add each one you actually use.
Ports are not stored. A local address like localhost:3000 is saved as localhost, which will not match a request coming from port 3000. To test locally, use the Custom integration with a token instead, since token authentication skips the domain check.

If the list is empty, the widget cannot start a conversation at all - you’ll see the error No allowed origins configured.

2. Bot Protection

Bot protection stops automated traffic from burning through your conversation minutes. Callers uses Cloudflare Turnstile, which is free.

Create a Turnstile widget

Open the Cloudflare Turnstile dashboard and create a new widget.

Add your website domains

Enter the same domains you added in the previous step. Cloudflare will only issue challenges for domains listed here.

Copy both keys into Callers

Cloudflare gives you a Site key and a Secret key. Paste both into the matching fields in the installer.

Both keys are required. Bot protection switches on only when the site key and the secret key are filled in - fill in just one and it stays off. The secret key lives in Callers because verification happens on our servers, not in the visitor’s browser.

Once enabled, bot protection applies to both installation methods - the embed script and the Web SDK. Unlike the domain list, a token does not bypass it.

After a visitor passes a challenge and the conversation ends, they must close and reopen the widget to start another one. This is intentional: each conversation gets its own challenge.

3. Copy the Code

Copy the snippet and paste it into your HTML, just before the closing </body> tag, on every page where you want the widget to appear.

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

That’s the whole installation. The floating button appears in the corner of the page as soon as the script loads.

Passing Visitor Information

If your campaign defines variables, the snippet includes a data-vars attribute pre-filled with placeholders:

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

The {{ name }} placeholders are not filled in automatically. Replace them with real values from your page or template before going live - otherwise your agent will greet visitors with the literal text {{ name }}.

Rendered by your server or templating engine, the final tag should look like this:

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

Script Tag Reference

Attribute	Description
`data-campaign`	Required (unless you use `data-token`). The campaign the widget connects to.
`data-token`	A pre-generated authentication token. Use instead of `data-campaign` for token-based authentication - see Custom Integration.
`data-vars`	JSON object of campaign variables, e.g. `'{"name":"Jane"}'`. Must be valid JSON.
`data-theme`	`"light"`, `"dark"`, or a full theme configuration as JSON.
`data-fab-text`	Label shown next to the phone icon on the floating button. Leave it out for an icon-only round button.
`data-show-fab`	Set to `"false"` to hide the floating button and launch the widget from your own code.

Custom Integration (Web SDK)

Use the Custom tab when the standard widget isn’t enough - you want your own launch button, you need the conversation embedded inside your page layout, or your visitors are logged in and you want to authenticate them properly.

Install the widget modal showing the Custom SDK tab — The Custom tab: install the SDK, authenticate, and initialize

1. Install the SDK

npm install @callers/web-sdk

2. Authenticate

Instead of checking the visitor’s domain, the SDK authenticates with a short-lived token that you generate on your own backend. The Authenticate step in the installer shows your campaign’s web call secret. Copy it and store it as a server-side environment variable.

Never put the secret in browser code. Anyone who reads your page source could mint their own tokens and run conversations on your account. The secret belongs on your backend only - your frontend should only ever receive the finished token.

Generating a Token

The SDK ships the helper, so on a JavaScript backend it’s one call:

import { generateToken } from '@callers/web-sdk';

const token = await generateToken(campaignId, process.env.CALLERS_WEB_CALL_SECRET);

That returns a token valid for one hour. Send it to your frontend and pass it to WebCall.

Generating a Token Without the SDK

If you’d rather not add the SDK as a server dependency, the format is simple enough to build yourself. A token is three dot-separated parts: the campaign ID, an expiry timestamp in seconds, and an HMAC-SHA256 signature of the first two parts, hex-encoded.

{campaignId}.{expiry}.{signature}

Here it is in Node. It ports directly to any language with an HMAC library - the only thing that has to match is the payload string and hex encoding:

import crypto from 'node:crypto';

const TOKEN_TTL_SECONDS = 3600; // 1 hour

function generateWebCallToken(campaignId, secret, ttlSeconds = TOKEN_TTL_SECONDS) {
  const expiry = Math.floor(Date.now() / 1000) + ttlSeconds;
  const payload = `${campaignId}.${expiry}`;
  const signature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `${payload}.${signature}`;
}

Expose it through an endpoint your frontend can call - ideally one that requires the visitor to be logged in, so only real users can obtain a token.

Tokens expire after one hour. Generate a fresh token each time a visitor loads the page rather than caching one. Requests with an expired token are rejected with Invalid web call token.

Token authentication replaces the domain allowlist - a valid token is accepted from any origin. Bot protection, if enabled, still applies.

3. Initialize the SDK

Pass the token your backend generated, along with any campaign variables:

import { WebCall } from '@callers/web-sdk';

const webCall = new WebCall({
  token,
  vars: {
    name: 'Jane Doe',
    email: 'jane@example.com',
  },
});

webCall.call();

webCall.call() starts a voice conversation immediately. To show the floating button and let the visitor start it themselves, create the instance without calling call() - the widget renders and waits.

Try It in the Playground

Before wiring the SDK into your own application, you can exercise it against a real campaign in the SDK Playground. Enter your campaign ID and secret, click Load SDK, and a working widget appears on the page - with every SDK method available as a button, a live event feed, and a running transcript.

SDK Playground with a campaign connected, the SDK loaded, and the widget button running on the page — A campaign loaded in the playground - the widget is live in the bottom-right corner

It doubles as a visual theme builder. See Styling the Widget for that side of it.

Verify the Installation

Load the page

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

Start a conversation

Click the button and allow microphone access when the browser asks. Try both the voice option and the text composer.

Check the transcript

Open the campaign in Callers and confirm the conversation appears with its full transcript.

Common Errors

Message	What it means	How to fix it
`No allowed origins configured`	The domain list is empty.	Add at least one domain in Your Domains, or switch to token authentication.
`Origin '...' is not allowed for this campaign`	The page’s domain isn’t on the list.	Add that exact domain - including the subdomain - and save the campaign.
`Origin header is required`	The page was opened without an origin, typically from a local `file://` path.	Serve the page over `http://` or `https://` instead of opening the file directly.
`Web calls not enabled for campaign`	The campaign isn’t set up as a widget campaign.	Open General Settings and select Widget as the channel.
`Bot verification is required` / `Bot verification failed`	Turnstile is enabled but the challenge wasn’t completed or didn’t validate.	Confirm the site key and secret key are both correct and that the page’s domain is listed 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 backend using the campaign’s web call secret.

The widget doesn't appear at all

The agent greets visitors with {{ name }}

Your data-vars placeholders were never replaced. The installer generates them as templates; your page or server needs to substitute real values before the HTML reaches the browser.

It works in production but not on localhost

The domain field stores hostnames without ports, so localhost:3000 is saved as localhost and won’t match. Use the Custom integration with a token for local development - token authentication skips the domain check entirely.

Next Steps

Add campaign actions so your agent can book meetings or push data to your CRM during a conversation.
Review Analytics & Insights to see how widget conversations are performing.
Set up webhooks to receive conversation results in your own systems.

Get Started

Build Your Campaign

Using Callers

Integrations

Agencies

Webhook

Resources

Legal

Installing the Widget

What Is the Widget?

No Phone Number Needed

Voice or Text

Context From Your Site

Two Installation Paths

Step 1: Create a Widget Campaign

What Changes When You Pick Widget

Build Your Script

Step 2: Open the Installer

Embed on Web

1. Add Your Domains

2. Bot Protection

3. Copy the Code

Passing Visitor Information

Script Tag Reference

Custom Integration (Web SDK)

1. Install the SDK

2. Authenticate

Generating a Token

Generating a Token Without the SDK

3. Initialize the SDK

Try It in the Playground

Verify the Installation

Common Errors

Next Steps

​What Is the Widget?

No Phone Number Needed

Voice or Text

Context From Your Site

Two Installation Paths

​Step 1: Create a Widget Campaign

​What Changes When You Pick Widget

​Build Your Script

​Step 2: Open the Installer

​Embed on Web

​1. Add Your Domains

​2. Bot Protection

​3. Copy the Code

​Passing Visitor Information

​Script Tag Reference

​Custom Integration (Web SDK)

​1. Install the SDK

​2. Authenticate

​Generating a Token

​Generating a Token Without the SDK

​3. Initialize the SDK

​Try It in the Playground

​Verify the Installation

​Common Errors

​Next Steps

What Is the Widget?

Step 1: Create a Widget Campaign

What Changes When You Pick Widget

Build Your Script

Step 2: Open the Installer

Embed on Web

1. Add Your Domains

2. Bot Protection

3. Copy the Code

Passing Visitor Information

Script Tag Reference

Custom Integration (Web SDK)

1. Install the SDK

2. Authenticate

Generating a Token

Generating a Token Without the SDK

3. Initialize the SDK

Try It in the Playground

Verify the Installation

Common Errors

Next Steps