Integration Guide

Widget Integration

Add FlowChat to any website with a single script tag. The widget renders an isolated iframe and communicates with the public chat API.

Quick Start

Include the widget script and call FlowChat.init() with your workspace configuration. The widget will appear as a floating chat button on the bottom-right corner of your page.

html

<script src="https://your-cdn.example.com/widget/v0.0.1/widget.js"></script>
<script>
  FlowChat.init({
    projectId: 'your-workspace-id',
    apiUrl:    'https://api.flowchat.ai',
    embedUrl:  'https://app.flowchat.ai',
    publicKey: 'your-public-key',
    theme:     'light',
  });

  // Optionally open the widget immediately
  FlowChat.open();
</script>

SDK API

The global FlowChat object exposes four methods:

FlowChat.init(config)

Initialize the widget with your workspace configuration. Must be called before any other method.

FlowChat.open()

Open the chat window. If the widget has not been initialized, this is a no-op.

FlowChat.close()

Close the chat window while keeping the floating button visible.

FlowChat.destroy()

Remove the widget from the page entirely, cleaning up all DOM elements and event listeners.

Configuration

Pass a configuration object to FlowChat.init() with the following properties:

Property	Status	Description
`projectId`	Required	Your workspace ID. Messages from the widget are routed to this workspace.
`apiUrl`	Required	Base URL for the FlowChat backend API (e.g. https://api.flowchat.ai).
`embedUrl`	Optional	Base URL that serves the iframe UI (/embed/chat). Defaults to apiUrl.
`publicKey`	Optional	Public read-only key for the project. Required when the server enforces key validation.
`theme`	Optional	"light" or "dark". Controls the widget's color scheme. Defaults to "light".

The SDK automatically requests a short-lived token from your API to prevent users from tampering with the iframe URL. Tokens expire after 10 minutes by default and are refreshed transparently.

Token endpoint

POST /public/chat/widget-token
Content-Type: application/json

{
  "projectId": "your-workspace-id",
  "publicKey": "your-public-key"
}

You can test token generation manually during local development:

bash

curl -X POST http://localhost:3001/public/chat/widget-token \
  -H "Content-Type: application/json" \
  -d '{"projectId":"YOUR_WORKSPACE_ID","publicKey":"YOUR_PUBLIC_KEY"}'

Then open the embed route with the returned token:

http://localhost:3000/embed/chat?token=PASTE_TOKEN&apiUrl=http://localhost:3001

Embed Route

The widget loads an iframe pointing at /embed/chat from the configured embedUrl. The embed UI calls public endpoints under /public/chat.

https://app.flowchat.ai/embed/chat?token=...&apiUrl=...&theme=light

Server Configuration

The following environment variables control widget behavior on the API server:

PUBLIC_WORKSPACE_KEYS

Comma-separated list of workspaceId:publicKey pairs. When defined, requests without a matching public key are rejected.

PUBLIC_WORKSPACE_KEYS=ws-1:pk-abc123,ws-2:pk-def456

WIDGET_EMBED_SECRET

Secret key used to sign and verify widget tokens. Must be set for token-based widget authentication.

WIDGET_EMBED_TTL_SECONDS

Token time-to-live in seconds. Defaults to 600 (10 minutes).

Note: Tool access (product catalog, pricing, availability) is enabled only when a valid publicKey is provided for the workspace.

Versioning & CDN

Use versioned CDN paths so integrators can pin a specific release. A latest alias is also available for convenience.

# Pinned version
https://your-cdn.example.com/widget/v0.0.1/widget.js

# Latest alias
https://your-cdn.example.com/widget/latest/widget.js

The widget build outputs files to:

apps/widget/dist/cdn/vX.Y.Z/widget.js
apps/widget/dist/cdn/latest/widget.js
apps/widget/dist/manifest.json