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
- The portal mints a short-lived preview token bound to that AppChat account and the saved domain (default ~10 minutes).
- The preview page loads
/widget/appchat.jswithdata-preview-token. Widget API calls sendX-Engagive-Widget-Previewso Origin can be the Engagive portal while still validating the account and domain binding. - 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.
- 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:
<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.