Embedding the Widget
Add one script tag to your site. The widget positions, sizes, and animates itself. No CSS is added to your page.
Contents
- Install
- How it works
- Public key & embed URL
- Optional controls
- Visitor identity (optional)
- Allowed domains
- Checklist
- Troubleshooting
Install
Copy the install snippet from your SapAi project → Widget settings, or use this shape:
<script
src="https://YOUR_SAPAI_ORIGIN/widget.js"
data-public-key="YOUR_PUBLIC_KEY"
async
></script>
Optional attributes (defaults match today’s behavior):
| Attribute | Default | Meaning |
|---|---|---|
data-on-error-load |
true |
true: show the “Widget unavailable” card on failure. false: hide the iframe (no error UI). |
data-wait-until-loaded |
false |
true: keep the iframe hidden until config load succeeds. false: show the loading pulse immediately. |
<script
src="https://YOUR_SAPAI_ORIGIN/widget.js"
data-public-key="YOUR_PUBLIC_KEY"
data-on-error-load="false"
data-wait-until-loaded="true"
async
></script>
Example (local / your origin will differ in production):
<script
src="http://localhost:3000/widget.js"
data-public-key="c3e595a262334d36c91bde6cca787192"
async
></script>
Place it anywhere in your HTML (often once in the site layout, before </body>).
That is enough for an anonymous chat launcher on every page.
How it works
| Piece | Role |
|---|---|
widget.js |
Tiny host loader. Creates one fixed iframe. Does not inject stylesheets into your page. |
| Iframe | Runs the widget UI in isolation at /embed/widget/{publicKey}. |
| Your page | Only loads the script (and optionally pushes a visitor JWT). |
The loader owns the iframe’s box (position / size). The widget document owns everything visible (launcher, panel, animation). Host CSS cannot restyle the chat UI inside the frame.
Install once in your layout. Do not remount the script on every route change.
Public key & embed URL
From Widget settings (same values the UI labels Public key and Embed URL):
| Field | Example | Use |
|---|---|---|
| Public key | 1223334444555556666667777777 |
data-public-key on the script tag |
| Embed URL | /embed/widget/1223334444555556666667777777 |
Path the iframe loads (relative to your SapAi origin). You normally do not open this yourself widget.js does. |
The public key identifies which project’s widget to load. It is not a secret (it is embedded in the page), but only hosts you allow (see Allowed domains) should load it in production.
Optional controls
After the script loads, a global API is available:
window.SapAiWidget.open()
window.SapAiWidget.close()
window.SapAiWidget.setVisitorToken(token)
window.SapAiWidget.onVisitorTokenRequest(() => { /* remint + setVisitorToken */ })
window.SapAiWidget.destroy()
| Method | Purpose |
|---|---|
open() |
Open the chat panel |
close() |
Close the chat panel |
setVisitorToken(token) |
Pass a short-lived visitor JWT (see Visitor JWT) |
onVisitorTokenRequest(fn) |
Widget asks the host for a fresh token |
destroy() |
Remove the iframe (e.g. on logout / SPA teardown) |
If the script is still downloading, poll briefly until window.SapAiWidget exists, then call these APIs.
Visitor identity (optional)
Anonymous embed works with only the script tag.
To tell SapAi who the visitor is (and optional page context for tools), mint a visitor JWT on your backend and push it:
window.SapAiWidget.setVisitorToken(token)
Full guide: Visitor JWT.
Allowed domains
In Widget settings, configure which host origins may load the embed. Add your production and staging origins (e.g. https://www.example.com). Requests from other sites should not load your widget.
Also ensure the widget is enabled in SapAi, or the public embed will not load.
Checklist
- Widget enabled in SapAi
- Allowed domains include your site origin
- One
<script … widget.js data-public-key="…">in the layout - Correct SapAi origin in
src(production URL, not only localhost) - (Optional) Visitor JWT mint +
setVisitorTokenfor authenticated / contextual chat
Troubleshooting
| Symptom | Check |
|---|---|
| Nothing appears | Widget enabled? Wrong data-public-key? Script blocked by CSP / ad blocker? |
| Blank or refused embed | Is your site origin in Allowed domains? |
| Looks unstyled / broken on your CSS | Expected that host CSS does not enter the iframe; if the launcher box is clipped, check parent overflow / transforms on the host |
SapAiWidget is undefined |
Script not loaded yet, or src 404 wait for load or check Network tab |
| Need login / project tools | Push a Visitor JWT; anonymous sessions have no sub / claims |
Next step
Authenticate visitors and pass page context: Visitor JWT