Embed the web widget

Basic embed

<script src="https://chat.agent4.io/ui/embed.js"
        data-token="YOUR_SHARE_TOKEN" async></script>

The loader injects a floating chat bubble (bottom-right) that expands into a window or full screen. The iframe points at the platform origin, so your site needs no CORS setup.

Options

Keyboard: Ctrl/⌘ + Shift + F cycles bubble → window → full screen.

Command palette (Ask bar)

Prefer the modern "Ask a question" pattern you see on documentation sites? Swap embed.js for ask.js — same single line, no other change:

<script src="https://chat.agent4.io/ui/ask.js"
        data-token="YOUR_SHARE_TOKEN" async></script>

This injects a slim Ask a question bar. Clicking it — or pressing ⌘K / Ctrl+K anywhere on the page — expands it into a centered command palette over a dimmed backdrop; Esc or a click outside closes it. The bar isn't a static label: it types out, one after another, the questions your visitors are most likely to ask on that page (drawn from the same page playbooks that power the bubble's suggested questions).

The palette runs the identical agent, retrieval, and authentication as the bubble — including the host-session mode below — so everything else on this page applies unchanged. Choose bubble or Ask bar per share in the console (Website embed → Chat bubble / Ask bar).

Domain allow-list

Each share carries an allowed_domains list. The platform enforces it with a frame-ancestors CSP, so the widget only renders inside the sites you listed. Configure it on the share in the console.

Two things about this list are easy to get wrong, and neither reports an error:

• A wildcard does not cover the bare domain. https://*.example.com does not match https://example.com. List both.
• Host-session shares must fill it in. An empty list sends no CSP header at all, which means any site may put your widget in an iframe. For a host-session share — one that exists to be embedded on a site you control — that is never what you want, so the platform now refuses to save it empty. If the share is only ever called from your own server and never rendered in a browser, enter 'none', which is exactly how CSP spells "never embed this".

Authentication modes

1. Anonymous — visitors chat without an account; each browser gets its own space.
2. Account login — visitors sign in with a platform end-user account; history and memory follow them across devices.
3. Host session (HMAC) — your backend tells the widget who the user is, so your logged-in users are recognized without a second login:

<script src="https://chat.agent4.io/ui/embed.js"
        data-token="YOUR_SHARE_TOKEN"
        data-uid="user-42"
        data-ts="1767139200"
        data-sig="HMAC_SHA256(secret, uid + ts)"
        async></script>

Your server computes data-sig with the share's signing secret; the platform verifies it and maps user-42 to a stable end-user identity.

A share is either open or it is not. An agent does not switch between modes per visitor. Pick anonymous for anything a stranger may use — pre-sales, product questions — and host session for anything that is part of what a customer paid for. The distinction matters because those two agents usually read different knowledge bases, and the second one's material is not public.

Choosing host session (or account login) makes the whole share protected, not just the chat: every endpoint under it refuses a request that carries no credential, including the ones that come before the first message — the page playbook, the greeting, and the share's own description. An unsigned visitor learns that the conversation requires signing in, and nothing else.

Where an unsigned visitor goes

Set Sign-in page on a host-session share to your own login URL. A visitor who opens the chat without a valid signature is sent there instead of being left at a refusal:

• The standalone page redirects straight to it, carrying next= back to the chat.
• The embedded widget shows a short "sign in to continue" panel with a button. The button navigates the top window, not the iframe — most login pages send X-Frame-Options: DENY, so loading one inside a 400×640 iframe produces a blank box.

Leave it empty and the refusal still happens; the visitor just has nowhere to go from it.

Standalone page

Every share is also reachable as a full page at https://chat.agent4.io/s/YOUR_SHARE_TOKEN — useful for QR codes, email links, or ad landing pages when you don't control the hosting site.