Facia Docs
For AI Open Facia
Connect your stuff Developers

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>
AttributeMeaning
srcwidget.js on any of your Facia addresses (your domain, yourhandle.facia.chat or facia.chat)
data-handleYour business handle
data-colorThe button colour
data-positionright (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>

#Hints after #

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

HintExampleEffect
namename=PatPrefills the client's name (up to 64 characters)
themetheme=darklight or dark
insetsinsets=0Your page already handles the phone's safe areas
accentaccent=3d6bffAccent colour, 6-digit hex without #
bgbg=0e1014Background colour
surfacesurface=171a20Card colour

Facia works out the remaining colours from these.

#Query parameters

ParameterEffect
?ref=CODEA member's invite code (4–16 letters and numbers), remembered for 30 days
?src=nameCampaign tag shown in Sources. 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, 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.

View as Markdown