Quickstart: React / Next.js

The SDK ships with a ready-to-use React component. Drop it into your root layout and you're done.

Install

npm install @bitpalm/ai-agents

Add the component

Place <BitPalmAgent /> in your root layout so the widget persists across page navigations.

Next.js (App Router)

// app/layout.tsx
import { BitPalmAgent } from "@bitpalm/ai-agents/react";
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <BitPalmAgent slug="your-agent-slug" token="your-embed-token" />
      </body>
    </html>
  );
}

Next.js (Pages Router)

// pages/_app.tsx
import { BitPalmAgent } from "@bitpalm/ai-agents/react";
 
export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <BitPalmAgent slug="your-agent-slug" token="your-embed-token" />
    </>
  );
}

Vite / CRA / any React app

// App.tsx
import { BitPalmAgent } from "@bitpalm/ai-agents/react";
 
export default function App() {
  return (
    <>
      <YourRoutes />
      <BitPalmAgent slug="your-agent-slug" token="your-embed-token" />
    </>
  );
}

Component props

PropTypeDefaultDescription
slugstring—Required. Your agent slug from the dashboard.
tokenstring—Required for restricted agents.
localestringauto"en", "de", "ar". Falls back to document.documentElement.lang.
baseUrlstringhttps://agents.bitpalm.aiOnly for self-hosted.
zIndexnumber9999z-index for the iframe and button.
autoIdentifybooleantrueAuto-capture form fields on submit.

Server-side rendering

The component is client-only and safely no-ops during SSR. You don't need dynamic() or useEffect wrappers.

Programmatic control

To call methods like identify(), context(), send(), open(), etc., use the Vanilla SDK approach instead — it gives you a widget instance reference. Or fire browser events:

useEffect(() => {
  if (user) {
    window.dispatchEvent(
      new CustomEvent("bitpalm-identify", {
        detail: {
          slug: "your-agent-slug",
          externalUserId: user.id,
          email: user.email,
          name: user.name,
        },
      })
    );
  }
}, [user]);

See Identify and Context for full details.

Next steps