> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Add a Callers voice agent to your website with a script tag in two minutes, then control it from code in five.

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.

> [!TIP]
>
> Want to see it first? Open the [playground](https://docs.callers.ai/sdk/playground.md), paste your agent ID and secret, and start a test call without writing any code.

## Before you start

**1. 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](https://docs.callers.ai/documentation/widget-agents/installing-the-widget.md).

**2. 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)

**1. 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.

**2. Paste the snippet**

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

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

**3. Pass what you know about the visitor (optional)**

If your script uses [variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md), fill them from your page or template:

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

**4. 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.

> [!TIP]
>
> The conversation shows up in your agent's results with its transcript.

All script tag options are listed in the [script tag reference](https://docs.callers.ai/sdk/configuration.md#script-tag-attributes).

## Option 2: programmatic (5 minutes)

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

**1. 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.

```javascript server.js theme={"dark"}
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](https://docs.callers.ai/sdk/authentication.md).

**2. Load the SDK**

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

```html theme={"dark"}
<script src="https://cdn.callers.ai/sdk.js"></script>
```

**3. Create the call**

```html theme={"dark"}
<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.

> [!NOTE]
>
> 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](mailto: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](https://sdk-playground.callers.dev/?fab=Talk%20to%20us\&corner=bottom-left)**
>
> See the launcher options, then copy the matching snippet with **Get code**.

> **[With a talking avatar](https://sdk-playground.callers.dev/?avatar=maya)**
>
> Preview Maya, a stock avatar, in the call window.

## Next steps

> **[Configuration](https://docs.callers.ai/sdk/configuration.md)**
>
> Every option and script tag attribute.

> **[Events and transcript](https://docs.callers.ai/sdk/events-and-transcript.md)**
>
> React to the call in your own code.

> **[Theming](https://docs.callers.ai/sdk/theming.md)**
>
> Match the widget to your brand.

> **[Troubleshooting](https://docs.callers.ai/sdk/troubleshooting.md)**
>
> Fix common setup errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.