@bitpalm/ai-agents

Drop-in AI chat agent widget for any website. Works with React, Next.js, Vue, vanilla JS, or a simple script tag.

Installation

npm install @bitpalm/ai-agents

React / Next.js

import { BitPalmAgent } from '@bitpalm/ai-agents/react';

export default function Layout({ children }) {
  return (
    <>
      {children}
      <BitPalmAgent slug="your-agent-slug" token="your-embed-token" />
    </>
  );
}

Place it in your root layout so the widget persists across page navigations.

Vanilla JavaScript

import { createWidget } from '@bitpalm/ai-agents';

const widget = createWidget({ slug: 'your-agent-slug', token: 'your-embed-token' });

// Programmatic control
widget.open();
widget.close();
widget.identify({
  externalUserId: 'cust_123',
  name: 'Max Mustermann',
  email: '[email protected]',
});
widget.destroy();

Script Tag

No build step required — add a single script tag to any HTML page:

<script async src="https://unpkg.com/@bitpalm/ai-agents" data-slug="your-agent-slug" data-token="your-embed-token"></script>

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | slug | string | — | Required. Your agent slug from the BitPalm dashboard. | | token | string | — | Required for restricted/private agents. Embed token from dashboard access settings. | | locale | string | auto-detected | Widget language ("en", "de", "ar", …). Falls back to document.documentElement.lang. | | baseUrl | string | "https://agents.bitpalm.ae" | Agent platform URL. Only change this for self-hosted setups. | | zIndex | number | 9999 | z-index for the widget iframe and chat button. | | autoIdentify | boolean | true | Auto-detects form submissions and sends found identity fields (email/phone/name/company) for visitor stitching. |

Features

• Visitor Intelligence — automatically sends page URL, title, and navigation history to the agent for context-aware responses
• Returning visitor detection — recognizes returning visitors, restores chat history, and enables session/page-count-based triggers
• SPA support — detects client-side navigation (pushState / replaceState) and keeps the widget alive across route changes
• Trigger bubbles — proactive chat bubbles configured from the dashboard, including visitor-data-driven triggers (session count, visited pages)
• Scroll & exit tracking — scroll depth and exit intent signals for smart triggers
• Automatic form identity stitching — captures common form fields on submit and links them to the current visitor profile
• Privacy-friendly — respects visitor opt-out (_bp_optout in localStorage); when opted out, no tracking beacons are sent and no visitor ID is stored
• Light & fast — no dependencies (React is optional), tiny bundle size

Optional Field Hints

The widget already detects common field names automatically. For custom forms, you can add explicit markers:

• data-bp-email
• data-bp-phone
• data-bp-name (or data-bp-first-name / data-bp-last-name)
• data-bp-company
• data-bp-field="email|phone|name|first-name|last-name|company" (generic fallback)

Disable auto-identity for one specific form:

<form data-bp-identify="off">...</form>

Manual Identify (Logged-in Users)

If your website has authenticated users, call identify() after login to attach trusted profile data to the current visitor:

widget.identify({
  externalUserId: "user_42",
  name: "Alex Example",
  email: "[email protected]",
  phone: "+491701234567",
  company: "Example GmbH",
});

Optional signed identify fields (forwarded to your BitPalm backend):

• signature: backend-generated HMAC signature
• signedAt: unix timestamp (seconds)
• signatureVersion: currently "v1"

For script-tag integrations, trigger identify via a browser event:

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

License

MIT — AI Agent Platform by BitPalm