Configuration

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.

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),
});

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

string

The agent ID. Use it with allowed domains. Not needed when you pass a token, because the token starts with the agent ID.

string

A short-lived token from your server, in the form agentId.expiry.signature. See Authentication.

string

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

string

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

string

default:"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

Record<string, unknown>

Values for your agent’s script variables, for example { name: 'Jane', plan: 'pro' }. Sent when the call starts.

boolean

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

string

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

string

default:"Voice Call"

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

boolean

default:"true"

Shows the Or send a message… composer, which is also how visitors start a text conversation. In-call forms still appear when it is false.

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.

boolean

default:"true"

Set to false to hide the idle launcher. The call window still appears once you call call(). See Headless use.

boolean

default:"false"

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

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.

string

default:"Call In Progress"

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

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

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.

WidgetThemeConfig

Colors, fonts, sizes and radii. Overrides the theme saved on the agent. See Theming.

Audio

boolean | NoiseSuppressionOptions

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

Show NoiseSuppressionOptions

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.

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.

boolean

The browser’s echo cancellation. On unless you set false.

boolean

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

Avatar

See Avatars for details and examples.

string

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

string

URL of a packaged avatar folder. Wins over avatar.

'compact' | 'expanded' | 'minimized'

default:"compact"

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

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

string

default:"photo"

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

HTMLElement | string

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

string

default:"https://cdn.callers.ai/avatars"

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

Page Guide

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.

Callbacks

All callbacks are optional. Details and examples are in Events and transcript.

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. It needs data-agent or data-token; with neither, nothing is created.

<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 sets most of these options with controls and generates both the script tag and the programmatic code.

Configure visually

Open the playground and use Get code.

Methods

Control the call at runtime.

Theming

Colors, launcher position, and the WidgetThemeConfig reference.

Methods

Start, stop, mute, and control the call at runtime.

Installing the widget

Dashboard-side setup, domains, and the embed snippet.

Events and transcript

React to call state and read the live transcript.

Get started

Features

Reference

Advanced

Agent and authentication

Conversation

Widget UI

Audio

Avatar

Page Guide

Callbacks

Script tag attributes

Try in the playground

Configure visually

Methods

Theming

Methods

Installing the widget

Events and transcript

​Agent and authentication

​Conversation

​Widget UI

​Audio

​Avatar

​Page Guide

​Callbacks

​Script tag attributes

​Try in the playground

Configure visually

Methods

​Related

Theming

Methods

Installing the widget

Events and transcript

Agent and authentication

Conversation

Widget UI

Audio

Avatar

Page Guide

Callbacks

Script tag attributes

Try in the playground

Related