Quickstart

This guide gets a working call widget on a page, then shows the programmatic setup you’d use in a logged-in app. You need an agent with the widget turned on.

Want to see it first? Open the playground, paste your agent ID and secret, and start a test call without writing any code.

Before you start

Turn on the widget for your agent

Open your agent, go to Channels, select the Widget tab and switch on Enable widget. The full walkthrough is in Installing the widget.

Copy the agent ID

The agent ID is in the agent’s URL and in the snippet on the Embed on Web tab.

Option 1: script tag (2 minutes)

Allow your domain

On the Embed on Web tab, under Your Domains, add every hostname the widget runs on, for example www.example.com. Each subdomain is a separate entry, and wildcards are not accepted.

Paste the snippet

Add this just before </body> on every page that should show the widget:

<script
  src="https://cdn.callers.ai/sdk.js"
  data-agent="YOUR_AGENT_ID"
  data-fab-text="Talk to us"
></script>

Pass what you know about the visitor (optional)

If your script uses variables, fill them from your page or template:

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

Test it

Load the page. A launcher appears in the bottom-right corner. Click it, then choose Voice Call (allow the microphone) or type into Or send a message… to start a text conversation.

The conversation shows up in your agent’s results with its transcript.

All script tag options are listed in the script tag reference.

Option 2: programmatic (5 minutes)

Use this when you want token authentication, your own launch button or your own UI.

Mint a token on your server

Tokens are signed with the agent’s web call secret (shown on the Custom tab) or one of your organization’s API keys. Keep the secret on your server.

server.js

import crypto from 'node:crypto';

// GET /callers-token  →  { token }
export function createCallersToken(agentId) {
  const expiry = Math.floor(Date.now() / 1000) + 3600; // valid for 1 hour
  const payload = `${agentId}.${expiry}`;
  const signature = crypto
    .createHmac('sha256', process.env.CALLERS_WEB_CALL_SECRET)
    .update(payload)
    .digest('hex');

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

More languages and details: Authentication.

Load the SDK

Without data-agent or data-token, the script only defines the CallersWebSdk global and creates nothing.

<script src="https://cdn.callers.ai/sdk.js"></script>

Create the call

<button id="talk">Talk to our assistant</button>
<script>
  const { WebCall } = window.CallersWebSdk;

  async function start() {
    const { token } = await fetch('/callers-token').then((r) => r.json());

    const webCall = new WebCall({
      token,
      vars: { name: 'Jane Doe' },
      showFab: false, // use your own button instead of the launcher
      onStatusChange: (status) => console.log('status', status),
      onTranscriptMessage: (message) => console.log(message.role, message.content),
      onCallEnded: () => console.log('call ended'),
    });

    document.getElementById('talk').onclick = () => webCall.call();
  }

  start();
</script>

call() starts a voice call and opens the call window. Call it from a click handler so the browser allows audio.

The dashboard’s Custom tab shows npm install @callers/web-sdk. That package isn’t on the public npm registry yet. Load the SDK from the CDN as shown here, or contact support@callers.ai for package access. With the package, replace window.CallersWebSdk with import { WebCall } from '@callers/web-sdk'.

Try in the playground

Labeled launcher, bottom left

See the launcher options, then copy the matching snippet with Get code.

With a talking avatar

Preview Maya, a stock avatar, in the call window.

Next steps

Configuration

Every option and script tag attribute.

Events and transcript

React to the call in your own code.

Theming

Match the widget to your brand.

Troubleshooting

Fix common setup errors.

Get started

Features

Reference

Advanced

Before you start

Option 1: script tag (2 minutes)

Option 2: programmatic (5 minutes)

Try in the playground

Labeled launcher, bottom left

With a talking avatar

Next steps

Configuration

Events and transcript

Theming

Troubleshooting

​Before you start

​Option 1: script tag (2 minutes)

​Option 2: programmatic (5 minutes)

​Try in the playground

Labeled launcher, bottom left

With a talking avatar

​Next steps

Configuration

Events and transcript

Theming

Troubleshooting

Before you start

Option 1: script tag (2 minutes)

Option 2: programmatic (5 minutes)

Try in the playground

Next steps