Embed a Chatbot

Add a configurable Fluo chatbot to a site with one script tag and a publishable embed key.

The chat widget is the fastest way to turn an agent into something customers can use. It loads a hosted chat frame, connects it to one agent, and lets you customize placement and appearance from a small config object.

Basic Embed

Add this snippet before the closing </body> tag on the page where the chatbot should appear.

<script>
  window.FluoConfig = {
    agentId: "agent_123",
    embedKey: "pk_fluo_123",
    widget: {
      position: "bottom-right",
      openByDefault: false,
      trigger: {
        color: "#111111",
        icon: "Chat"
      }
    }
  };
</script>
<script src="https://platform.fluo.one/widget.js" async></script>

Use publishable keys:

The widget should use a publishable embed key. Do not place a full secret API key in the browser. See Public Embed Keys for the recommended security model.

Required Fields

Field	Description
`agentId`	The agent the widget should talk to.
`embedKey`	A browser-safe key scoped to this published chatbot.

Common Options

Option	Type	Default	Notes
`widget.position`	string	`bottom-right`	Supports `bottom-right`, `bottom-left`, and `center-bottom`.
`widget.openByDefault`	boolean	`false`	Opens the chat frame when the page loads.
`widget.trigger.color`	string	`#000000`	Button background color.
`widget.trigger.icon`	string	`Chat`	Short text or icon for the launcher.
`widget.container.width`	number	`380`	Chat frame width in pixels.
`widget.container.height`	number	`520`	Chat frame height in pixels.

Pass Visitor Context

Use metadata for non-sensitive product context such as plan, locale, or current page. Avoid sending passwords, access tokens, payment data, or private identifiers unless your data policy allows it.

<script>
  window.FluoConfig = {
    agentId: "agent_123",
    embedKey: "pk_fluo_123",
    metadata: {
      locale: "en",
      plan: "pro",
      page: window.location.pathname
    }
  };
</script>
<script src="https://platform.fluo.one/widget.js" async></script>

Production Setup

Before embedding on a public site:

Add your production domains to the key's allowed origins.
Set per-key and per-IP rate limits.
Set daily or monthly usage caps.
Restrict write-capable tools unless public users are allowed to trigger them.
Test from every domain where the script will run.

Troubleshooting

Symptom	Check
Widget does not appear	Confirm `agentId` and `embedKey` are present before `widget.js` loads.
Requests are rejected	Confirm the page domain is in allowed origins.
Chat opens but does not answer	Confirm the agent is published and the key has not exceeded rate or budget limits.
Uploads fail	Confirm uploads are enabled for the embed key and the file type is allowed.

PreviousQuickstart

NextCall the API