Embedding the Chat Widget

The FutureBase chat widget is a lightweight, customizable bubble that appears on your website and lets visitors chat with your AI agent. There are two ways to add it.

Choose Your Integration Method

npm Package (React & Next.js)

If you're using React or Next.js, install the @futurebase/chat package for full control over the widget via components and hooks.

Script Tag (Any Website)

For any website — including plain HTML, WordPress, Astro, and others — add a single <script> tag. No build step required.

Quick Install

The fastest way to get started is with the script tag approach.

Customization

You can customize the appearance of your chat widget from the Playground page in your dashboard. Options include:

• Theme — match your website's light or dark mode
• Accent color — align the widget with your brand colors
• Position — place the chat bubble on the left or right side
• Welcome message — set the initial greeting customers see
• Placeholder text — customize the input field hint

All styling changes are applied in real time — no need to update your embed code.

Advanced Options

Controlling Widget Visibility

Hide the widget on specific pages using ignore paths. Both the npm package and script tag support this:

• npm Package: pass ignorePaths={["/admin/*", "/login"]} to ChatProvider
• Script Tag: add data-futurebase-ignore-paths="/admin/*,/login" to the script element

Content Security Policy (CSP)

If your site uses a strict Content Security Policy, add the following to your CSP headers:

script-src 'self' https://embed.futurebase.io;
frame-src 'self' https://embed.futurebase.io;
connect-src 'self' https://embed.futurebase.io;

User Identification

By default, conversations are anonymous. If your users are logged in to your app, you can pass their identity to the widget so conversations are attributed to known users in your dashboard.

How it works

Pass a signed identity payload when initializing the widget. FutureBase verifies the signature server-side to prevent spoofing.

Setup

import { createHmac } from "crypto";

const secret = process.env.FUTUREBASE_WIDGET_SECRET;

const user = {
  userId: "user_123",
  email: "jane@example.com",
  name: "Jane Smith",
};

const hash = createHmac("sha256", secret)
  .update(JSON.stringify(user))
  .digest("hex");

// Pass `user` and `hash` to your frontend

<script>
  window.FutureBase = window.FutureBase || {};
  window.FutureBase.identify = {
    userId: "user_123",
    email: "jane@example.com",
    name: "Jane Smith",
    hash: "SERVER_GENERATED_HASH",
  };
</script>

Once configured, conversations from this user will be linked to their identity in the dashboard, and you'll see their name and email alongside the conversation.

Supported identity fields

Troubleshooting