Configuration

All available options for createWidget(), <BitPalmAgent />, and the script-tag attributes.

Options

Option	Type	Default	Description
`slug`	`string`	—	Required. Your agent slug from the dashboard.
`token`	`string`	—	Required for restricted/private agents.
`locale`	`string`	auto	Widget language (`"en"`, `"de"`, `"ar"`). Falls back to `document.documentElement.lang`.
`theme`	`"auto" \| "light" \| "dark"`	`"auto"`	Light or dark widget colors. `"auto"` follows your website. Needs a dark theme set up in the dashboard, see Light & Dark Theme.
`baseUrl`	`string`	`https://agents.bitpalm.ai`	Agent platform URL. Only change for self-hosted.
`zIndex`	`number`	`9999`	z-index for the iframe and button.
`autoIdentify`	`boolean`	`true`	Auto-detects form submissions and sends found identity fields (email/phone/name/company).
`launcher`	`boolean`	`true`	Shows the round chat button. Set to `false` when your site opens the chat from a button of its own, see Own Chat Button.
`triggers`	`boolean \| "events"`	`true`	Proactive messages. `true` shows them as a bubble, `"events"` fires `trigger_shown` instead, `false` switches them off.

Per-integration syntax

React component

<BitPalmAgent
  slug="your-slug"
  token="your-token"
  locale="de"
  theme="auto"
  zIndex={50}
  autoIdentify={false}
/>

Vanilla JS

const widget = createWidget({
  slug: "your-slug",
  token: "your-token",
  locale: "de",
  theme: "auto",
  zIndex: 50,
  autoIdentify: false,
});

Script tag

<script
  async
  src="https://unpkg.com/@bitpalm/ai-agents"
  data-slug="your-slug"
  data-token="your-token"
  data-locale="de"
  data-theme="auto"
  data-z-index="50"
  data-launcher="false"
  data-triggers="false"
></script>

Locale auto-detection

If you don't pass locale, the widget reads document.documentElement.lang (the lang="..." attribute on <html>). If that's missing, it defaults to English.

To force a specific language regardless of the page setup, pass it explicitly.

Z-index conflicts

Some sites use very high z-index values for sticky headers, modals, or cookie banners. If the chat button gets covered, raise zIndex:

createWidget({ slug: "...", zIndex: 100000 });

Disabling auto-identify globally

The widget watches form submissions and tries to extract email, phone, name, and company from common field names. If you don't want this:

createWidget({ slug: "...", autoIdentify: false });

You can still call widget.identify() manually whenever you have trusted data.

For per-form opt-out, see Form Field Hints.

Privacy / opt-out

Visitors who set _bp_optout=1 in their browser localStorage are excluded from tracking. No beacons are sent and no visitor ID is created. The widget still works as a chat surface but treats them as anonymous.

You can wire an "opt out of analytics"-button on your site to set that key:

localStorage.setItem("_bp_optout", "1");