Embedding the Chat Widget

Overview

Flow Builder at the Flow Builder can generate an embeddable chat widget that you drop into any website. The widget runs your flow as a chat assistant, giving visitors a conversational interface without leaving your site.

Generating the Widget Code

1. Open your flow at the Flow Builder.
2. Click the Deploy or Widget button in the toolbar.
3. Configure your widget options (colors, position, welcome message).
4. Copy the generated script tag.
5. Paste it into your website's HTML, ideally just before the closing </body> tag.

The Script Tag

The embed code is a single script tag that loads the widget asynchronously. It looks like this:

<script
  src="https://flow.assistable.ai/widget.js"
  data-flow-id="your-flow-id"
  data-position="bottom-right"
  data-primary-color="#4F46E5"
  data-welcome-message="Hi! How can I help you today?"
  async
></script>

The script is lightweight and loads asynchronously, so it does not block your page from rendering.

Customization Options

Attribute	Description	Default
data-flow-id	Your flow's unique identifier (required)	None
data-position	Widget position: bottom-right or bottom-left	bottom-right
data-primary-color	Primary color for the widget header and send button (hex)	#4F46E5
data-welcome-message	Initial message shown when the widget opens	None
data-button-text	Text label on the launcher button	Chat

Colors accept any valid hex value. Choose colors that match your brand to keep the widget visually consistent with the rest of your site.

Shadow DOM Isolation

The chat widget renders inside a Shadow DOM. This means its styles are completely isolated from your website's CSS, and your website's styles do not leak into the widget.

This isolation prevents common problems like:

• Your site's global CSS overriding widget fonts or spacing
• Widget styles conflicting with your site's design system
• CSS frameworks (Tailwind, Bootstrap) altering the widget appearance

The widget looks and behaves consistently regardless of what CSS framework or reset your site uses.

Session Persistence with localStorage

The widget stores conversation state in the browser's localStorage. When a visitor navigates to another page or refreshes, the conversation picks up where it left off. The session key and conversation history are preserved automatically.

This means:

• Visitors do not lose their conversation when browsing your site.
• Returning visitors within the same browser session see their previous messages.
• Clearing browser data or using incognito mode starts a fresh session.

Deployment Considerations

• Single Page Apps (SPAs): The widget handles SPA navigation automatically. No extra configuration needed for React, Vue, or Next.js sites.
• Multiple pages: Place the script tag in your site's global template or layout so it loads on every page.
• Content Security Policy: If your site uses a strict CSP, add flow.assistable.ai to your script-src and connect-src directives.
• Performance: The widget script is small and loaded asynchronously. It does not affect your site's Core Web Vitals.

Important: Make sure your flow has an API key configured and a start node designated before embedding the widget. Without these, the widget will load but the agent will not respond.