API Reference

Complete reference for everything the SDK exposes.

`createWidget(options)`

Initializes the widget. Returns an instance with control methods.

import { createWidget } from "@bitpalm/ai-agents";
 
const widget = createWidget({
  slug: string,
  token?: string,
  locale?: string,
  baseUrl?: string,
  zIndex?: number,
  autoIdentify?: boolean,
});

See Configuration for option details.

Methods

Visibility

widget.open(): void
widget.close(): void
widget.toggle(): void
widget.isOpen(): boolean

Send a message

widget.send(message: string): void

Opens the widget if closed, then submits the message as if the user typed it. See Programmatic Messages.

Identify

widget.identify(payload: {
  externalUserId?: string;
  name?: string;
  email?: string;
  phone?: string;
  company?: string;
  // Optional signed payload for verified data:
  signature?: string;
  signedAt?: number;
  signatureVersion?: "v1";
}): void

Merges with previous identify calls. See Identify.

Custom Context

widget.context(data: Record<string, unknown>): void
widget.resetContext(): void

Merges by default. Total payload limited to 4 KB. See Context.

Events

widget.on(event: EventName, handler: (data: any) => void): () => void

Returns an unsubscribe function. See Events for the list.

Tear down

widget.destroy(): void

Removes the widget DOM and unbinds all listeners.

`<BitPalmAgent />` (React)

import { BitPalmAgent } from "@bitpalm/ai-agents/react";
 
<BitPalmAgent
  slug="..."
  token="..."
  locale="en"
  zIndex={9999}
  autoIdentify={true}
/>

The component renders nothing visible itself — it manages the widget lifecycle. Place it once in your root layout.

To call identify, context, send, etc., dispatch browser events (see below).

Browser events

For setups where you don't have a widget instance reference (script tag, React component), you can control the widget via window.dispatchEvent:

`bitpalm-identify`

window.dispatchEvent(
  new CustomEvent("bitpalm-identify", {
    detail: {
      slug: "your-agent-slug",
      externalUserId: "user_42",
      email: "[email protected]",
    },
  })
);

`bitpalm-context`

window.dispatchEvent(
  new CustomEvent("bitpalm-context", {
    detail: {
      slug: "your-agent-slug",
      cart: { total: 99 },
    },
  })
);

`bitpalm-send`

window.dispatchEvent(
  new CustomEvent("bitpalm-send", {
    detail: {
      slug: "your-agent-slug",
      message: "What can you tell me about plan X?",
    },
  })
);

`bitpalm-open` / `bitpalm-close`

window.dispatchEvent(new CustomEvent("bitpalm-open",  { detail: { slug: "your-slug" }}));
window.dispatchEvent(new CustomEvent("bitpalm-close", { detail: { slug: "your-slug" }}));

The slug in the detail is required so multi-agent setups (rare) target the right widget.

TypeScript types

import type {
  WidgetOptions,
  WidgetInstance,
  IdentifyPayload,
  EventName,
} from "@bitpalm/ai-agents";

Bundle size

Build	Gzipped
`@bitpalm/ai-agents` (vanilla)	~6 KB
`@bitpalm/ai-agents/react`	~7 KB
Script tag (UMD via unpkg)	~7 KB

The widget UI itself (chat window, message rendering) loads from the BitPalm domain in a sandboxed iframe — it doesn't ship in your bundle.

Privacy & opt-out

Visitors with localStorage["_bp_optout"] = "1" are excluded from tracking. The widget still works as a chat surface but treats them as anonymous (no visitor ID, no beacons).