Product guides · AppChat

Website widget preview

From App Chat → Widget → Allowed domains, use Preview to load the real visitor widget against a saved domain — without deploying first.

Where to open it

Sign in at https://app.engagive.io, open an AppChat account, go to the Widget tab, save at least one allowed domain, then click Preview on that chip (opens a new tab). Admins see the same control when viewing a business user's AppChat Widget tab.

How Preview works

  1. The portal mints a short-lived preview token bound to that AppChat account and the saved domain (default ~10 minutes).
  2. The preview page loads /widget/appchat.js with data-preview-token. Widget API calls send X-Engagive-Widget-Preview so Origin can be the Engagive portal while still validating the account and domain binding.
  3. Unsaved form changes (theme, title, hours, etc.) can be applied as a live config for this session only — they do not expand Allowed domains without Save.
  4. Guest vs Identified toggles sample visitor attributes for identity testing.

Why some sites cannot iframe

Many production sites send X-Frame-Options or CSP frame-ancestors that block embedding in the portal. When that happens, Preview switches to a site stage fallback: you still get the real Engagive widget chrome and chat against that domain's allowlist entry, without the customer page underneath.

Use Retry iframe / Use stage in the preview toolbar, or open the customer site in a normal tab with the embed snippet for a true layout test.

Install the snippet for a true on-site test

Preview never puts secrets in NEXT_PUBLIC_* env vars. Your site only needs the public widget key. From Preview, use Copy snippet, or copy from the Widget tab embed section:

HTML
<script
  src="https://YOUR_API_HOST/widget/appchat.js"
  data-appchat-key="YOUR_WIDGET_PUBLIC_KEY"
></script>

Serve the page over HTTPS in production (except localhost). The page Origin must match a saved Allowed domain. For logged-in visitors, add data-user-* attributes (see Mobile SDK / Widget identity docs).

Security notes

  • Preview tokens are rate-limited and expire quickly; they are bound to one account + saved domain.
  • Only operators with Widget / AppChat Detail view permission can mint tokens.
  • Preview skips Origin allowlist matching for the portal host only when the token verifies; production sites still must be on Allowed domains to mint.
  • Do not share preview URLs or tokens outside your team — treat them like a short session.

QA checklist

  • Test mode + localhost — save localhost:3000 (or your port), Preview; widget connects and chat works.
  • Production domain — save a real host; Preview with iframe when the site allows framing.
  • XFO / CSP blocked site — confirm stage fallback appears and widget still works.
  • Multi-domain — Preview each saved domain; unsaved new chips stay disabled until Save.
  • Live form config — change title/color without Save, Preview, confirm badge + live look; Save separately for production.
  • Guest / Identified — toggle both modes; Identified uses sample visitor attributes.
  • Permission denied — user without AppChat Detail view cannot mint / open Preview successfully.
  • Admin parity — same Preview from admin → business user → AppChat → Widget.
  • Rate limit — rapid Refresh eventually returns 429 with a clear message.

Related docs