Embed Widget Guide

Add an AI chatbot to any website with a single line of code. This guide covers setup, configuration, domain restrictions, and multi-client deployments for agencies.

Quick Start

Create a chatbot

Customize appearance

Set your brand colors, welcome message, and chatbot personality in the chatbot settings.

Copy the embed code

Go to the Deploy tab in your chatbot settings, copy the script tag, and paste it into your website's HTML.

Embed Code

<script
  src="https://app.talkbuildr.com/embed.js"
  data-chatbot-id="YOUR_CHATBOT_ID"
  defer
></script>

Paste this before the closing </body> tag. Replace YOUR_CHATBOT_ID with the ID from your chatbot's Deploy tab.

How It Works

embed.js reads the data-chatbot-id attribute from the script tag.

It creates a container div and loads embed-component.js.

The embed component creates an iframe-based widget with Shadow DOM isolation, so your page styles don't leak in.

The iframe loads /chat/{chatbotId}?embed=1 -- the same chat interface, optimized for embedded use.

A launcher button (60px circle) appears in the bottom-right corner of the page.

Clicking the launcher opens a chat dialog (380x480px, expandable by the user).

Custom CSS must go in the dashboard, not your HTML

Because the chat widget loads inside an iframe and the launcher button uses Shadow DOM, CSS on your host page cannot reach the widget. Writing .cbp-header { ... } in your site's stylesheet will have no effect.

To style the chat window, paste your CSS into the Custom CSS field in Chatbot Settings > Appearance. This CSS is injected inside the iframe where it can target .cbp-* classes.

The launcher button (floating circle) is styled via the Primary Color picker in Appearance settings — it cannot be customized with CSS.

Configuration

All configuration is done in the dashboard -- no HTML attributes needed beyond data-chatbot-id.

Setting	Description	Location
Primary color	Main color for the launcher button and chat header	Chatbot Settings > Appearance
Secondary color	Accent color for message bubbles and interactive elements	Chatbot Settings > Appearance
Border radius	Corner roundness of the chat widget (0 = square, 16 = rounded)	Chatbot Settings > Appearance
Welcome message	The first message visitors see when they open the chat	Chatbot Settings > Personality
Chatbot personality	System prompt that defines tone, style, and response behavior	Chatbot Settings > Personality
Custom CSS	Override default widget styles with your own CSS	Chatbot Settings > Appearance
Show/hide branding	Toggle the TalkBuildr branding in the chat footer	Chatbot Settings > Appearance

Domain Restrictions

Control which websites can load your chatbot. Set allowed_domains in your chatbot settings to restrict access.

allowed_domains value	Result
(empty)	Allow all origins (default)
example.com	Only allow example.com
*.example.com	Allow all subdomains of example.com
app.example.com	Only allow app.example.com specifically

Non-matching origins will see: "This chat is not available on this website." This prevents unauthorized sites from embedding your chatbot and consuming your credits.

For Agencies: Multi-Client Setup

Running chatbots for multiple clients? Here's the recommended workflow.

One chatbot per client

Create a separate chatbot for each client. This keeps knowledge bases, analytics, and conversations isolated.

Brand each chatbot

Set the primary and secondary colors to match each client's brand. Customize the welcome message and personality per client.

Lock down domains

Set allowed_domains to each client's website URL. This prevents the chatbot from being loaded on unauthorized sites.

Distribute embed codes

Give each client their unique embed snippet. They paste it into their site -- no further setup needed.

Monitor from your dashboard

Track per-chatbot analytics (conversations, messages, satisfaction) across all your clients from a single dashboard.

Pro tip: Use the Pro or Business plan to get enough chatbot slots and message credits for multiple clients. Each chatbot has independent analytics, so you can report per client.

Troubleshooting

Widget not showing up

Verify the script tag is placed before the closing </body> tag
Check that the data-chatbot-id matches your actual chatbot ID
Open browser DevTools (Console tab) and look for errors
Make sure the chatbot is published (not in draft mode)

CORS / domain restriction errors

If you see "This chat is not available on this website", your domain is not in the allowed list
Add your domain (without https://) to Settings > Allowed Domains
Wildcard *.example.com does not match the bare domain example.com -- add both if needed
When testing locally, use localhost or leave allowed_domains empty

Content Security Policy (CSP) blocking the widget

Add app.talkbuildr.com to your CSP frame-src and script-src directives
Example: frame-src 'self' https://app.talkbuildr.com;
Example: script-src 'self' https://app.talkbuildr.com;
If you use a strict CSP, also add connect-src for API calls

Widget conflicts with existing page styles

The widget uses Shadow DOM + iframe isolation, so host-page CSS cannot affect it
To style the chat window, use the Custom CSS field in Chatbot Settings > Appearance
CSS on your host page (e.g. in <style> tags) will not reach inside the widget
The launcher button is styled via the Primary Color picker, not CSS