> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/protocols-and-integration/chat-ui-embedding.md).

# Embedding the Chat UI

> The token hand-off protocol and `eddi.chat.img-sources` are newer than 6.5.0. Under 6.5.0 a framed widget with authentication on could not start a conversation, and agent output images from other hosts were blocked.

EDDI serves a chat widget at `/chat`. Another site can show it in an `<iframe>`, or add one `<script>` tag and get a floating chat button that opens it ([section 6](#6-the-launcher-chatembedjs)). This page is the contract between that host page and the widget: who may frame it, how a signed-in user's token gets into it with authentication on, and which images it may load.

## 1. Allow the host page to frame `/chat`

By default `/chat` answers with `Content-Security-Policy: frame-ancestors 'none'`, so every browser refuses to render it inside someone else's page. List the origins allowed to frame it, separated by spaces:

```properties
# application.properties, or EDDI_CHAT_FRAME_ANCESTORS in the environment
eddi.chat.frame-ancestors=https://portal.example.com
```

This is the operator's allow-list, and the browser enforces it before the widget runs. A page that is not listed cannot frame the widget, so it cannot talk to it either. Only `/chat` takes this setting. The Manager and the API always refuse to be framed. Keep the list exact: a wildcard such as `https://*.example.org` lets every subdomain frame the widget and hand it a token.

```html
<iframe
  id="eddi-chat"
  src="https://eddi.example.com/chat/production/<agentId>?tokenOrigin=https%3A%2F%2Fportal.example.com"
  style="width: 400px; height: 600px; border: none;"
></iframe>
```

The display parameters (`theme`, `title`, `hideUndo`, the colour parameters) are listed in the [Chat UI README](https://github.com/labsai/EDDI/tree/main/ui/chat/README.md). `theme` accepts only `dark`, `light` or `system`. Every colour parameter must be a plain colour: hex, `rgb()`/`hsl()` with numeric arguments, or a named colour. `fontFamily` must be a plain font list. The widget ignores any other value and logs a warning in the console.

These parameters beat the deployment's [brand](https://docs.labs.ai/deployment-and-infrastructure/white-labeling.md#the-chat-ui): with a brand set, the widget's default title, logo and accent come from it, and a `title` or `accentColor` parameter still overrides them.

Each colour parameter sets one or more `--chat-*` CSS variables (`bgColor` → `--chat-bg`, `accentColor` → `--chat-accent`, the user bubble and the focus ring, …). Those names are stable: since the shared design tokens arrived, the ones with a shared meaning are declared as aliases of them (`--chat-bg` is `var(--color-background)`), and setting the `--chat-*` name still wins, so an existing link renders as it did. The table is `CHAT_TOKEN_ALIASES` in [`ui/packages/ui/src/chat-aliases.ts`](https://github.com/labsai/EDDI/tree/main/ui/packages/ui/src/chat-aliases.ts).

`lang` picks the widget's language — any of the eleven the Manager ships (`en`, `de`, `fr`, `es`, `ar`, `zh`, `th`, `ja`, `ko`, `pt`, `hi`); without it the browser's languages decide, falling back to English. `lang=ar` lays the widget out right to left. Only the widget's own text is translated, never the agent's.

## 2. Hand the widget a token (authentication on)

With OIDC enabled, every API call the widget makes needs a bearer token. The widget has no login flow of its own; the host page, which has already signed the user in, passes it an access token by `postMessage`.

### The protocol

| Direction     | Message                                                | When                                                                                                            |
| ------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| widget → host | `{ type: "eddi-chat-ready", protocol: 1 }`             | As soon as the widget is listening, then every second until the first token arrives or the widget stops waiting |
| widget → host | `{ type: "eddi-chat-token-request", protocol: 1 }`     | About a minute before the current token expires, and whenever the backend answers `401`                         |
| host → widget | `{ type: "eddi-chat-token", token: "<access token>" }` | In answer to either message, and at any other time the host has a newer token                                   |

Rules the widget enforces:

* **Opt-in, exact origins.** The widget only takes part when its URL names the host with `?tokenOrigin=`, as a bare origin (`https://portal.example.com`) or several separated by commas. The widget drops a wildcard, a path, the opaque origin `null` and any scheme other than `http`/`https`. Without `tokenOrigin` the widget accepts no token and posts nothing.
* **Never a `*` target.** Every message the widget sends is posted with an allow-listed origin as its `targetOrigin`. If the parent is at any other origin, the browser discards the message.
* **Only the parent, only from an allow-listed origin.** A token is accepted only when `event.source` is the widget's own parent window and `event.origin` is in the list. A message from a sibling frame, a popup or any other origin is ignored. The token must be printable ASCII without whitespace, at most 16 KB.
* **Refresh.** If the token is a JWT, the widget reads its `exp` claim, only to schedule the next request, and asks for a new token a minute before it expires; for a token shorter-lived than five minutes it asks at about 80 % of its life. The backend still verifies every token.
* **The start waits for the first token.** With `tokenOrigin` set, the widget holds the start of the conversation (and the agent profile lookup) until the first token arrives, for up to five seconds. A host that never answers cannot leave it blank: after five seconds it starts without a token, and an agent that needs a login answers with its "Please sign in" message.
* **401 retry.** When a request is answered `401`, the widget asks for a new token, waits up to ten seconds, and sends the request once more. The same applies to a request that went out before the first token arrived. If no token comes, the `401` is shown as usual.
* **Memory only.** The token is held in a JavaScript variable. It is never written to the URL, `localStorage`, `sessionStorage` or a cookie.

### Host page example

```html
<script>
  const CHAT_ORIGIN = "https://eddi.example.com";
  const frame = document.getElementById("eddi-chat");

  // getAccessToken() is your application's: for keycloak-js, something like
  //   await keycloak.updateToken(30); return keycloak.token;
  async function sendToken() {
    const token = await getAccessToken();
    frame.contentWindow.postMessage({ type: "eddi-chat-token", token }, CHAT_ORIGIN);
  }

  window.addEventListener("message", (event) => {
    // Answer only the widget: the right origin AND our own iframe.
    if (event.origin !== CHAT_ORIGIN || event.source !== frame.contentWindow) return;
    const type = event.data && event.data.type;
    if (type === "eddi-chat-ready" || type === "eddi-chat-token-request") sendToken();
  });
</script>
```

The host must also post to an exact origin (`CHAT_ORIGIN`), never `"*"`: a `*` target would hand the token to whatever document the iframe happens to be showing.

### Which token to send

Send an access token issued for EDDI. That means its audience and roles must satisfy the backend (`eddi-user` is enough to chat; see [security.md](https://docs.labs.ai/security-and-compliance/security.md)). The widget acts as that user, and conversation ownership is checked against the token's subject. Use a short-lived token. The refresh protocol exists so that a long lifetime is never needed.

### Other ways to pass a token

* `?token=` in the iframe URL is **off by default**. A crafted link could sign the widget in as somebody else (login CSRF), the token passes through the host page's markup, and the first request writes it into the server's access log before the widget strips it from the address bar. The widget ignores the parameter and logs a console warning naming the switch, `eddi.chat.url-token.enabled` (`EDDI_CHAT_URL_TOKEN_ENABLED=true`), which an operator sets on the EDDI server for an embedding that cannot use the hand-off. Enabled, the widget reads the token once and strips it from the address bar on load. Either way, prefer the hand-off above.
* A `tokenOrigin` over plain `http` is accepted, since local development runs on one, but the widget warns in the console about any that is not `localhost`: the token the host page posts is only as private as that page's own transport.
* A page that bundles the widget itself can set `ChatConfig.authToken`.
* `?apiServer=` points the widget at a different API path on the **same origin** (a sub-path deployment or a dev proxy), for example `?apiServer=/eddi/api`. The widget accepts only a clean absolute path: it must start with a single `/` and may not contain a query string (`?`), a fragment (`#`), a percent-encoded character (`%`), a `.` or `..` segment, a backslash, whitespace or a control character. Anything else, and every other origin, is ignored with a console warning and the configured API server is used. The widget builds request URLs by concatenating this value with the API path, so a `?` or `#` in it would turn the real path into a query string and send a state-changing request to a different endpoint, with the page's credentials.

## 3. Images in agent output

An agent designer can put an image in an agent's output: an output item `{ "type": "image", "uri": "https://cdn.example.com/a.png", "alt": "…" }`. The widget renders these as `<img>`, for `http(s)` URLs and same-origin paths only.

Under the widget's original policy, `img-src 'self' data: blob:`, the browser refused every image hosted anywhere but EDDI itself. The `/chat` policy now appends `eddi.chat.img-sources`:

| Setting                                           | Effect                                                                                |
| ------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `https:` (default)                                | Images from any https host are shown                                                  |
| `https://cdn.example.com https://img.example.org` | Only those hosts                                                                      |
| `'self'`                                          | None beyond EDDI itself (the old behaviour). An empty value falls back to the default |

**The trade-off.** Markdown images in model-written text are never rendered as `<img>`: the widget turns them into links, so a model cannot make the browser fetch a URL of its choosing, whatever this setting says. What `https:` gives up is `img-src` as a second line of defence. If some other flaw let markup into the page, an injected `<img>` could send data to any https host. If you know where your designers' images live, list those hosts. The setting applies to `/chat` only. The Manager and Swagger UI keep their own `img-src`.

## 4. Agent appearance and controls

What the widget shows for an agent — display name, avatar, accent colour, conversation starters — and which controls it offers (undo, redo, attachments, rating, quick replies, streaming, HTML in replies) are set on the agent, in `appearance` and `conversationControls` ([agent-config-authoring.md](https://docs.labs.ai/agent-configuration/agent-config-authoring.md#agent-presentation-appearance-conversationcontrols)). `GET /agents/{agentId}/profile` serves both, for the deployed version, to anyone who may use the agent, so an embedding needs no extra parameters for them. The URL colour parameters and `/branding/brand.css` keep working as before; they style the deployment, `appearance` styles one agent.

## 5. What the widget does during a reply

Nothing here needs configuring; it is listed so an embedder knows what users see.

* **Stop** (the square button, or **Esc** inside the widget) aborts the stream and calls `POST /agents/{conversationId}/cancel`. That stops a running turn only on the node running it ([HITL](https://docs.labs.ai/conversations-and-orchestration/hitl.md)), so the widget reads the conversation again shortly after: when the turn ran on, a line in the conversation says so and shows the reply in full.
* When the stream drops mid-reply, the widget says it is reconnecting and re-reads the conversation for about half a minute; a turn that finished on the server meanwhile is shown in place of the partial reply.
* Code blocks name their language, and a block marked `mermaid` is drawn as a diagram by Mermaid (`securityLevel: "strict"`). Mermaid, like KaTeX and highlight.js, is a separate chunk under `/scripts/js/`, loaded only when a reply needs it: the widget's first load is unchanged. The paused-turn and rating cards load the same way, the first time they are shown. All of them are same-origin scripts, so `script-src 'self'` covers them.

## 6. The launcher (`/chat/embed.js`)

Instead of placing an iframe yourself, add one script tag. It draws a floating button in a corner of your page; the button opens the agent's widget in a panel, and closes it again.

```html
<script
  src="https://eddi.example.com/chat/embed.js"
  data-agent-id="<agentId>"
  defer
></script>
```

The panel is the same `/chat` widget in an iframe, so everything above still applies. In particular, **list your page's origin in `eddi.chat.frame-ancestors`** ([section 1](#1-allow-the-host-page-to-frame-chat)); otherwise the button appears but the browser refuses to show the panel. The agent must be deployed to the environment the launcher names.

### Settings

All settings are `data-` attributes on the script tag. Only `data-agent-id` is required.

| Attribute             | Default        | What it does                                                                                                                                                                                                                                                                              |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-agent-id`       | —              | The agent to chat with. Letters, digits, `.`, `_` and `-` only. Without a usable value, the launcher draws nothing and logs a console warning                                                                                                                                             |
| `data-environment`    | `production`   | The environment the agent is deployed to, for example `test`                                                                                                                                                                                                                              |
| `data-position`       | `bottom-right` | `bottom-right` or `bottom-left`                                                                                                                                                                                                                                                           |
| `data-color`          | blue           | The button's and the panel header's colour; it is also passed to the widget as `accentColor`. Only a plain colour is accepted (hex, `rgb()`/`hsl()` with numbers, or a named colour), by the same rule as the widget's colour parameters; anything else is ignored with a console warning |
| `data-label`          | per locale     | The button's text and the panel's accessible name, at most 60 characters. Without it the launcher uses a built-in word for "Chat" in the widget's eleven languages, picked from `data-lang`, then your page's `<html lang>`, then the browser                                             |
| `data-open`           | off            | `"true"` opens the panel when the page loads, without moving focus into it. On a narrow screen (480 px or less), where the panel covers the page, it stays closed until the person taps the button                                                                                        |
| `data-lang`           | —              | Passed to the widget as `lang` (any of its eleven languages)                                                                                                                                                                                                                              |
| `data-theme`          | —              | Passed to the widget as `theme`: `light`, `dark` or `system`                                                                                                                                                                                                                              |
| `data-token-provider` | —              | The name of a function on your page that returns an access token, or a promise of one. Only needed with authentication on; see below                                                                                                                                                      |

The launcher also puts one object on your page, `window.EddiChat`, with `open()`, `close()`, `toggle()` and `setTokenProvider(fn)`. Including the script twice draws one button.

### With authentication on

The launcher relays the widget's own token hand-off ([section 2](#2-hand-the-widget-a-token-authentication-on)), so your page does not need to write the message listener itself. Give it a function that returns a fresh access token:

```html
<script>
  // Your application's: for keycloak-js, something like this.
  async function getEddiToken() {
    await keycloak.updateToken(30);
    return keycloak.token;
  }
</script>
<script
  src="https://eddi.example.com/chat/embed.js"
  data-agent-id="<agentId>"
  data-token-provider="getEddiToken"
  defer
></script>
```

Or call `window.EddiChat.setTokenProvider(fn)` before the panel is first opened. With a provider, the launcher frames the widget with `?tokenOrigin=<your page's origin>` and answers its `eddi-chat-ready` and `eddi-chat-token-request` messages with your token. Without one, it leaves `tokenOrigin` off, since the widget would otherwise wait five seconds for a token that never comes, and the widget chats anonymously, as an agent that allows it permits.

What the launcher enforces:

* **Exact origins.** A message is answered only when it comes from the launcher's own iframe (`event.source`) and from the EDDI origin the script was loaded from (`event.origin`). The token is posted to that exact origin, never to `"*"`. A message of any other type, or from any other window or origin, is ignored.
* **Nothing read from your page.** The launcher never reads your cookies, `localStorage` or `sessionStorage`, never uses `eval`, `new Function` or `innerHTML`, and keeps the token only as long as it takes to post it. Its button and panel live in a shadow root, so your page's styles do not reach them and theirs do not reach your page.
* **Plausible tokens only.** A value that is not printable ASCII without whitespace, at most 16 KB, is not sent.

### Your page's Content Security Policy

If your page sends a CSP, allow the EDDI origin for the script and for the frame:

```
script-src 'self' https://eddi.example.com;
frame-src  https://eddi.example.com;
```

The launcher's styles are inside its shadow root as a `<style>` element, so a page whose `style-src` forbids inline styles must allow `'unsafe-inline'` for them. The script is a fixed URL, not content-hashed, so it cannot carry a Subresource Integrity hash that would survive an EDDI upgrade. EDDI serves it with `Cache-Control: public, max-age=3600`, so an upgrade reaches your page within an hour. A jar built with `-DskipUi=true` answers `/chat/embed.js` with 404.

### Accessibility

* The button is a real `<button>` with a visible label, `aria-expanded` and `aria-controls`.
* The panel is a labelled dialog (`role="dialog"`). When the person opens it, focus moves to the panel; **Tab** cycles through the close button and the conversation without leaving the panel; **Esc** on the panel, or the close button (named "Close chat" in the page's language), closes it and puts focus back on the button. Inside the conversation, Esc keeps its widget meaning and stops a running reply; press Shift+Tab to reach the close button, then Esc.
* On a screen 480 px wide or less, the panel fills the screen and respects the safe areas of a notched phone.
* The opening animation runs only under `prefers-reduced-motion: no-preference`.

## Upgrading: HTML in replies is off by default

`conversationControls.rawHtml` decides whether HTML in an agent's replies is rendered (through the sanitizer) or shown as text, and it **defaults to `false`**. Until 6.7.0 the widget rendered HTML for every agent; the Manager never did.

**From 6.7.0 the widget follows the setting** (decision D9 of the frontend unification plan): it reads `conversationControls` from `GET /agents/{agentId}/profile` and renders HTML only for an agent that sets `"rawHtml": true`. For every other agent — and for a profile that reports no controls — `<b>bold</b>` in a reply appears as the literal text `<b>bold</b>`, while markdown (`**bold**`) renders as before. No image in model text loads either way: a markdown image becomes a link, and a raw `<img>` is text, or a link for an agent with `rawHtml` ([section 3](#3-images-in-agent-output)).

**What to do when upgrading:** if an agent's replies are meant to contain HTML, set `"conversationControls": { "rawHtml": true }` on it and deploy the new version. Agents whose replies are plain text or markdown need nothing. The HTML parser stays a separate chunk, loaded only when a reply of such an agent contains HTML.

The other switches are honoured too: an agent with `undo`, `redo`, `attachments`, `quickReplies` or `rating` set to `false` gets no such control in the widget, and `streaming: false` sends its turns without streaming. The `hide*` URL parameters still hide a control for every agent; the agent's switch can only take one away, never bring back one the URL hid.
