> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Widgets and embeds

> Add a Flowra chat widget to your website, bound to an agent.

A **widget** is a branded chat surface on an external site, tied to one agent. Configure widgets in the dashboard, then paste the embed snippet or iframe URL on your site.

## Configure a widget

<Steps>
  <Step title="Open widgets">
    Go to [Workflow widgets](https://flowra.dev/dashboard/workflows/widgets), use **Create widget** on an agent card, or add a **Chat widget** under the agent’s **Entry points** tab.
  </Step>

  <Step title="Create or edit">
    Set a friendly name, which agent answers, active flag, on-screen position, button size, colors, header text, optional quick-reply chips (from the agent’s starter prompts), whether file upload is allowed, and whether threads persist (plus retention/expiry when shown).
  </Step>

  <Step title="Copy embed details">
    After save, the UI provides embed instructions and a **widget id** for the public URL.
  </Step>
</Steps>

## Identify logged-in visitors

Anonymous visitors get a widget external user automatically. To prove a host-site login:

1. Generate **HMAC** and/or **JWT** secrets on the project **End users** tab — [Projects and API keys](/product/projects-and-keys#end-users).
2. On the agent, open **Identity** → **End-user identity** and enable Host HMAC, Host JWT, Email OTP, or other methods as needed.
3. Your server must stamp `data-user-id` + `data-user-hash`, or `data-user-token`, on the embed script (sent via postMessage — not in the iframe URL). The dashboard widget UI shows a short identity snippet hint.

Unsigned email on the widget tag is not trusted. See also [External users switcher](/product/external-users).

## Public embed URL

Pattern:

```text theme={null}
https://flowra.dev/embed/chat?widgetId=<identifier>
```

You can open that URL directly, embed it in an iframe, or paste the dashboard snippet (script or iframe) into your site. Prefer HTTPS. If your site sets a strict Content-Security-Policy, allow `flowra.dev` (and any asset hosts the snippet references) for frame/script sources.

The page uses minimal chrome and loads branding and persistence settings from the widget config. Treat the widget id like a capability: do not post it publicly if the bound workflow can access private data or powerful tools.

| Setting | Effect |
| - | - |
| Persistence | When enabled, visitors can continue prior threads subject to retention/expiry |
| File upload | Allow or block visitor uploads into the widget chat |
| Position / colors | On-page bubble placement and branding |

Widget visitors appear as [external users](/product/external-users) with source **Widget**. Use the End user switcher to inspect their threads and connections.

## Security hygiene

* Use a dedicated **agent** for public embeds — limit tools and knowledge under **Actions**, and harden **Behavior** (guardrails, usage caps) when needed.
* Prefer separate agents for internal automations vs customer-facing chat.
* Test on a staging page before production.

## Try it

[Embed a widget](/product/try-embed).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.