Guides

Embedding the Chat Widget

Add the FutureBase chat widget to your website

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.

Get your embed code

Open Channels in the sidebar, then Chat bubble → Install. You'll see the snippet and step-by-step guides for HTML, WordPress, Shopify, Webflow, Wix, Squarespace, Google Tag Manager and React. The page tells you as soon as the bubble loads on your site.

Using a coding agent like Claude Code, Cursor or Codex? It can do this step for you. See Set up with your coding agent.

Add the script to your website

Paste the code snippet just before the closing </body> tag of your website.

Verify the installation

Visit your website and you should see the chat bubble in the bottom-right corner.

Customization

You can customize the appearance of your chat widget under Channels → Chat bubble → Appearance. Options include:

  • Bubble color and icon: match the launcher to your brand
  • Position: place the chat bubble in the bottom-left or bottom-right corner
  • Welcome message and greeting: what customers see when they open the chat
  • Placeholder text and customer message color: the message box hint and the colour of the customer's own messages

Saved changes show on your site the next time a page loads, with no change to your embed code. To use the dark home colours, add data-futurebase-theme="dark" (or "auto" to follow the customer's device) to the script tag. See Customizing your agent.

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;

The chat widget is designed to be lightweight and loads asynchronously, so it won't impact your site's performance.

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

Generate a signing secret

Go to Settings → Widget → User Identification and copy your signing secret. Keep this secret server-side — never expose it in client-side code.

Sign the identity payload server-side

On your server, generate an HMAC-SHA256 signature of the user's data:

import { createHmac } from "crypto";

const secret = process.env.FUTUREBASE_WIDGET_SECRET;

const user = {
  userId: "user_123",
  email: "[email protected]",
  name: "Jane Smith",
};

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

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

Pass identity to the widget

Initialize the widget with the signed user data. Do this after the widget script has loaded:

<script>
  window.FutureBase = window.FutureBase || {};
  window.FutureBase.identify = {
    userId: "user_123",
    email: "[email protected]",
    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

FieldTypeRequiredDescription
userIdstringYesYour internal user ID
emailstringNoUser's email address
namestringNoUser's display name
hashstringYesHMAC-SHA256 signature generated server-side

Never generate the hash client-side. If your signing secret is exposed in browser code, anyone can impersonate any user.

Troubleshooting

IssueSolution
Widget not appearingCheck that the script is loading (look for network requests to embed.futurebase.io in browser DevTools)
Widget appears but doesn't respondVerify your agent has content in its Knowledge Base
Styling conflictsThe widget uses Shadow DOM to isolate styles, but if you see issues, check for global CSS resets that might affect iframes
CORS errorsEnsure your CSP headers allow connections to embed.futurebase.io

On this page