> ## 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.

# Configuration

> Every WebCall option and script tag attribute in the Callers Web SDK, with types and defaults.

Configure the SDK by passing a `WebCallConfig` object to `new WebCall(config)`, or with `data-*` attributes on the script tag. Every option is optional except a way to identify the agent: `campaignId` or `token`.

```javascript theme={"dark"}
const webCall = new CallersWebSdk.WebCall({
  token,                              // or campaignId: 'YOUR_AGENT_ID' with allowed domains
  vars: { name: 'Jane Doe' },
  fabText: 'Talk to us',
  launcherPosition: 'bottom-left',
  theme: { base: 'dark' },
  avatar: 'maya',
  pageGuide: true,
  onTranscriptMessage: (message) => console.log(message),
});
```

> [!NOTE]
>
> **`campaignId` is the agent ID.** Agents used to be called campaigns, and the SDK option keeps the old name. Pass your agent ID wherever the SDK asks for a campaign ID. On the script tag, use `data-agent`; the older `data-campaign` still works.

## Agent and authentication

**campaignId** `string`

The agent ID. Use it with [allowed domains](https://docs.callers.ai/sdk/authentication.md#allowed-domains). Not needed when you pass a `token`, because the token starts with the agent ID.

**token** `string`

A short-lived token from your server, in the form `agentId.expiry.signature`. See [Authentication](https://docs.callers.ai/sdk/authentication.md#server-generated-tokens).

**secret** `string`

Web call secret used to sign a token in the browser. For local testing only; never ship it.

**apiKey** `string`

An API key used the same way as `secret`. For local testing only.

**apiEndpoint** `string` (default: [https://api.callers.ai](https://api.callers.ai))

The Callers API base URL. Leave it unset unless Callers support gives you a different endpoint.

The constructor throws `WebCall: unable to resolve campaign ID. Provide campaignId or a valid token (campaignId.expiry.signature).` when neither identifies the agent.

## Conversation

**vars** `Record\<string, unknown\>`

Values for your agent's [script variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md), for example `{ name: 'Jane', plan: 'pro' }`. Sent when the call starts.

**playGreeting** `boolean`

`true` makes the agent speak first, `false` waits for the visitor. Leave unset to use the agent's own setting.

## Widget UI

**fabText** `string`

Label on the collapsed launcher. Empty or unset shows a round icon-only button. Takes precedence over a theme's `fab.text`.

**precallPrompt** `string` (default: Voice Call)

Label of the button that starts a voice call on the pre-call card.

**showInput** `boolean` (default: true)

Shows the **Or send a message...** composer, which is also how visitors start a [text conversation](https://docs.callers.ai/sdk/text-and-voice.md). In-call forms still appear when it is `false`.

**showTranscript** `boolean` (default: false)

Opens the live transcript stream on voice calls. The stream also opens whenever the composer is visible, a transcript callback is set, Page Guide is on, or the call is a text call. The script tag sets it to `true`.

**showFab** `boolean` (default: true)

Set to `false` to hide the idle launcher. The call window still appears once you call `call()`. See [Headless use](https://docs.callers.ai/sdk/headless-and-react-native.md).

**hidden** `boolean` (default: false)

Start with the whole widget hidden. Show it later with `show()`.

**containerId** `string`

ID of an element to embed the whole call UI in, instead of floating it over the page. If no element has this ID, the widget floats as usual.

**title** `string` (default: Call In Progress)

The call window element's `title` attribute (shown by browsers as a tooltip).

**launcherPosition** `'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'` (default: bottom-right)

Which corner the launcher sits in. The call window grows from the same corner. Applies on top of any theme, including the dashboard theme.

**launcherOffset** `number` (default: 24)

Distance in pixels from both edges of that corner, 0–200. Values above 200 are capped; negative or invalid values use 24.

**theme** `WidgetThemeConfig`

Colors, fonts, sizes and radii. Overrides the theme saved on the agent. See [Theming](https://docs.callers.ai/sdk/theming.md).

## Audio

**noiseSuppression** `boolean | NoiseSuppressionOptions` (default: \{ aiNoiseSuppression: true, browserNoiseSuppression: false })

Microphone processing. `true` or `false` turns AI noise suppression on or off. Pass an object for finer control:

**NoiseSuppressionOptions**

**aiNoiseSuppression** `boolean`

AI noise suppression that runs in the browser on the visitor's microphone. On by default. If it fails mid-call, audio passes through unfiltered and the call continues.

**browserNoiseSuppression** `boolean`

The browser's built-in noise suppression. The default configuration turns it off so it doesn't stack with AI suppression. If you pass your own object without this field, the browser's suppression stays on.

**browserEchoCancellation** `boolean`

The browser's echo cancellation. On unless you set `false`.

**browserAutoGainControl** `boolean`

The browser's automatic gain control. On unless you set `false`.

## Avatar

See [Avatars](https://docs.callers.ai/sdk/avatars.md) for details and examples.

**avatar** `string`

A library avatar by name, for example `maya` or `john`, or a custom avatar name Callers created for you.

**avatarUrl** `string`

URL of a packaged avatar folder. Wins over `avatar`.

**avatarLayout** `'compact' | 'expanded' | 'minimized'` (default: compact)

The avatar's starting size in the call window. Visitors can change it during the call.

**avatarFraming** `'face' | 'photo'`

`face` zooms in on head and shoulders, `photo` shows the whole photo. Defaults to `face` for compact and minimized layouts, `photo` for expanded and for `avatarContainer`.

**avatarBackground** `string` (default: photo)

What shows behind the avatar: `photo`, `transparent`, `blur`, `preset:<id>`, a CSS color, or `url(...)`.

**avatarContainer** `HTMLElement | string`

An element, or a CSS selector, to render the avatar in instead of the call window.

**avatarLibraryUrl** `string` (default: [https://cdn.callers.ai/avatars](https://cdn.callers.ai/avatars))

Where library avatars and background presets are hosted. Leave unset.

## Page Guide

**pageGuide** `boolean | PageGuideConfig` (default: false)

Shares a text summary of the page with the agent so it can answer questions about it and highlight or scroll to elements. See [Page Guide](https://docs.callers.ai/sdk/page-guide.md).

## Callbacks

All callbacks are optional. Details and examples are in [Events and transcript](https://docs.callers.ai/sdk/events-and-transcript.md).

| Callback | Signature | Fires when |
| - | - | - |
| `onStatusChange` | `(status: PhoneStatus) => void` | The connection status changes |
| `onCallStarted` | `() => void` | The call connects |
| `onCallEnded` | `() => void` | The call ends, for any reason |
| `onError` | `(error: Error) => void` | Starting the call, sending input or the connection fails |
| `onTranscriptMessage` | `(message: TranscriptMessage) => void` | A message is new or changed |
| `onTranscriptChanged` | `(messages: TranscriptMessage[]) => void` | The transcript changed (full list) |
| `onWidgetInputSent` | `(data: { content: string; widgetMessageId?: string }) => void` | The visitor sends a message or form answer from the built-in UI |
| `onMuteChange` | `(muted: boolean) => void` | The microphone is muted or unmuted |
| `onDeafenChange` | `(deafened: boolean) => void` | The speaker is turned off or on |

## Script tag attributes

The script tag creates a `WebCall` on page load and exposes it as `window.Callers.widget`. For the dashboard-side setup, see [Installing the widget](https://docs.callers.ai/documentation/widget-agents/installing-the-widget.md). It needs `data-agent` or `data-token`; with neither, nothing is created.

```html theme={"dark"}
<script
  src="https://cdn.callers.ai/sdk.js"
  data-agent="YOUR_AGENT_ID"
  data-fab-text="Talk to us"
  data-launcher-position="bottom-left"
  data-theme="dark"
  data-vars='{"name":"Jane Doe"}'
></script>
```

| Attribute | Maps to | Notes |
| - | - | - |
| `data-agent` | `campaignId` | The agent ID. Required unless you use `data-token`. |
| `data-campaign` | `campaignId` | Legacy name of `data-agent`. Still works. |
| `data-token` | `token` | A token rendered by your server. |
| `data-api` | `apiEndpoint` | Defaults to `https://api.callers.ai`. |
| `data-vars` | `vars` | JSON object. Use single quotes around the attribute. Invalid JSON logs `[CallerWebSDK] Invalid JSON in data-vars attribute.` |
| `data-theme` | `theme` | `light`, `dark`, or a full theme as JSON. Invalid JSON logs an error and uses the agent theme. |
| `data-fab-text` | `fabText` | Launcher label. Omit for an icon-only button. |
| `data-show-fab` | `showFab` | `"false"` hides the idle launcher. |
| `data-launcher-position` | `launcherPosition` | `bottom-right`, `bottom-left`, `top-right` or `top-left`. |
| `data-launcher-offset` | `launcherOffset` | Pixels, 0–200. |
| `data-avatar` | `avatar` | Library avatar name, e.g. `maya`. |
| `data-avatar-url` | `avatarUrl` | Packaged avatar folder URL. |
| `data-avatar-layout` | `avatarLayout` | `compact`, `expanded` or `minimized`. Unknown values warn and are ignored. |
| `data-avatar-framing` | `avatarFraming` | `face` or `photo`. |
| `data-avatar-background` | `avatarBackground` | `photo`, `transparent`, `blur`, `preset:<id>`, a CSS color, or `url(...)`. |
| `data-avatar-container` | `avatarContainer` | CSS selector. |
| `data-avatar-library` | `avatarLibraryUrl` | Leave unset. |
| `data-page-guide` | `pageGuide` | `"true"` turns Page Guide on. |
| `data-page-guide-actions` | `pageGuide.actions` | Comma-separated: `highlight,scroll,navigate`. Default `highlight,scroll`. |
| `data-page-guide-hide` | `pageGuide.hideSelectors` | Comma-separated CSS selectors to keep private. |
| `data-page-guide-highlight` | `pageGuide.highlight` | `soft` (default), `glow`, `outline`, `spotlight` or `none`. |
| `data-page-guide-dim` | `pageGuide.dim` | Shade over the rest of the page, `0`–`0.5`. |
| `data-page-guide-color` | `pageGuide.color` | Any CSS color. Defaults to the theme's primary color. |
| `data-page-guide-label` | `pageGuide.label` | `"false"` hides the name label. |

The script tag always sets `showInput: true` and `showTranscript: true`. Callbacks, `containerId`, `hidden`, `precallPrompt`, `playGreeting` and `noiseSuppression` are available only in code. To combine the script tag with callbacks, load the SDK without `data-agent` and create the `WebCall` yourself.

## Try in the playground

The [playground](https://docs.callers.ai/sdk/playground.md) sets most of these options with controls and generates both the script tag and the programmatic code.

> **[Configure visually](https://sdk-playground.callers.dev/)**
>
> Open the playground and use **Get code**.

> **[Methods](https://docs.callers.ai/sdk/methods.md)**
>
> Control the call at runtime.

## Related

> **[Theming](https://docs.callers.ai/sdk/theming.md)**
>
> Colors, launcher position, and the WidgetThemeConfig reference.

> **[Methods](https://docs.callers.ai/sdk/methods.md)**
>
> Start, stop, mute, and control the call at runtime.

> **[Installing the widget](https://docs.callers.ai/documentation/widget-agents/installing-the-widget.md)**
>
> Dashboard-side setup, domains, and the embed snippet.

> **[Events and transcript](https://docs.callers.ai/sdk/events-and-transcript.md)**
>
> React to call state and read the live transcript.


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