# Embed Facia

> Put your Facia chat on your own website with one script tag, or in an iframe or native app WebView, with theme and name hints.

# Embed Facia

Keep clients on your own website or inside your own app, and give them your Facia chat there. Embeds are for **clients**: staff who open one are pointed to the inbox.

## Option 1: the chat button (one line)

Paste this before `</body>` on your site:

```html
<script src="https://yourhandle.facia.chat/widget.js"
        data-handle="yourhandle"
        data-color="#3d6bff"
        data-position="right"
        async></script>
```

| Attribute | Meaning |
| --- | --- |
| `src` | `widget.js` on any of your Facia addresses (your domain, `yourhandle.facia.chat` or `facia.chat`) |
| `data-handle` | Your business handle |
| `data-color` | The button colour |
| `data-position` | `right` (default) or `left` |

It adds a floating chat button. The chat opens in a panel (380 px wide on desktop, full screen on phones) the first time someone clicks it. Control it from your own code:

```js
window.FaciaWidget.open();
window.FaciaWidget.close();
```

## Option 2: an iframe

Use this for a full chat page, a sidebar, or a help-centre panel:

```html
<iframe
  src="https://yourhandle.facia.chat/embed/yourhandle#theme=dark&accent=3d6bff"
  allow="microphone; camera; clipboard-write; fullscreen; autoplay"
  style="width:100%;height:640px;border:0;border-radius:16px"></iframe>
```

> [!WARNING]
> Keep `allow="microphone; autoplay"`. Without it, [voice calls](https://docs.facia.chat/business/calls) and voice messages can't use the microphone inside the frame.

### Hints after `#`

Settings after `#` in the address stay in the browser and are never sent to a server.

| Hint | Example | Effect |
| --- | --- | --- |
| `name` | `name=Pat` | Prefills the client's name (up to 64 characters) |
| `theme` | `theme=dark` | `light` or `dark` |
| `insets` | `insets=0` | Your page already handles the phone's safe areas |
| `accent` | `accent=3d6bff` | Accent colour, 6-digit hex without `#` |
| `bg` | `bg=0e1014` | Background colour |
| `surface` | `surface=171a20` | Card colour |

Facia works out the remaining colours from these.

### Query parameters

| Parameter | Effect |
| --- | --- |
| `?ref=CODE` | A member's invite code (4–16 letters and numbers), remembered for 30 days |
| `?src=name` | Campaign tag shown in [Sources](https://docs.facia.chat/business/growth#campaign-links). Embeds also record the site they're on |

### Messages from the frame

The embed tells your page about a few things with `postMessage`:

```js
window.addEventListener("message", (e) => {
  if (e.origin !== "https://yourhandle.facia.chat") return;
  const m = e.data;
  if (m?.ns !== "relay") return;
  if (m.type === "unread") setBadge(m.count); // unread messages for the client
  if (m.type === "close") hideChatPanel();    // the client pressed close
});
```

## Option 3: native apps (WebView)

Load `https://yourhandle.facia.chat/embed/yourhandle` in a WebView.

- **Grant microphone access** to the WebView (Android `onPermissionRequest`, iOS `WKUIDelegate` media capture).
- **iOS**: set `allowsInlineMediaPlayback = true`.
- Use `#insets=0` if your app already pads for the notch and home bar.
- Rule of thumb: web things go *inside* Facia as [apps](https://docs.facia.chat/build/overview), and native apps *wrap* Facia with an embed.

## Sign-in and storage

Each embedded business keeps its own sign-in in the browser, so a client signed in to one embedded business isn't signed in to another. Clients start as guests and can save their account from Settings inside the embed.

Signing clients in automatically from your own site's login (single sign-on) isn't available yet.