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

Don't have an agent yet? Create one for free — takes less than 10 minutes.

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.toggle();       // open if closed, close if open
widget.isOpen();       // check if widget is open
widget.identify({
  externalUserId: 'cust_123',
  name: 'Max Mustermann',
  email: '[email protected]',
});
widget.context({
  cart: { items: [{ name: 'Sneakers', price: 99.99 }], total: 99.99 },
});
widget.resetContext(); // clear all custom context
widget.send('Tell me about the Enterprise plan'); // send message as user
widget.on('lead_captured', (data) => console.log('Lead!', data)); // listen to events
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.ai" | 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
• Custom context — pass business data (cart, user tier, listings) to the AI for contextual, relevant answers
• 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]",
    },
  })
);

Custom Context (Business Data for the AI)

Pass custom data from your website to the AI chatbot so it can give contextual, business-specific answers. Context is merged — calling context() multiple times adds to the existing data without replacing it.

// Shopify / E-Commerce: pass cart data
widget.context({
  cart: {
    items: [
      { name: "Nike Air Max 90", size: "42", price: 149.99 },
      { name: "Adidas Hoodie", qty: 2, price: 59.99 },
    ],
    total: 269.97,
    currency: "EUR",
  },
});

// SaaS: pass user status
widget.context({
  plan: "trial",
  trialDaysLeft: 3,
  accountId: "acc_12345",
});

// Real Estate: pass current listing
widget.context({
  property: { address: "Musterstr. 12, Berlin", price: 450000, rooms: 3 },
});

// Merges with previous context (doesn't replace)
widget.context({ promoCode: "SUMMER20" });

The bot automatically uses this context in its responses — e.g. referencing specific cart items, tailoring advice to the user's plan, or answering questions about the current listing.

For script-tag integrations, use a browser event:

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

Note: Context is session-only (not persisted to the database) and limited to 4 KB. Exceeding the limit logs a console warning.

Programmatic Messages

Send a message as the user without them typing. Opens the widget automatically if closed.

// E.g. triggered by a "Ask about this product" button on your page
widget.send('Tell me more about the Enterprise plan');

// Or from a product page CTA
document.querySelector('#ask-bot').addEventListener('click', () => {
  widget.send(`What can you tell me about ${productName}?`);
});

Event Listeners

React to chat events for analytics, conversion tracking, or custom UI updates.

// Track leads in Google Analytics
widget.on('lead_captured', (data) => {
  gtag('event', 'generate_lead', { source: 'chatbot' });
});

// Track conversation starts
widget.on('conversation_started', () => {
  analytics.track('Chat Started');
});

// React to widget open/close
widget.on('widget_opened', () => console.log('Chat opened'));
widget.on('widget_closed', () => console.log('Chat closed'));

// Unsubscribe
const unsub = widget.on('message_sent', (data) => { ... });
unsub(); // stop listening

Available events: | Event | Fired when | Data | |-------|-----------|------| | widget_opened | Chat widget opens | — | | widget_closed | Chat widget closes | — | | conversation_started | First message in a new conversation | — | | message_sent | User sends a message | { message } | | message_received | AI responds | — | | lead_captured | AI captures a lead via tool | { conversationId } |

License

MIT — AI Agent Platform by BitPalm