Testing the widget locally and on a phone
For developers, in code: allowing localhost on a widget key, testing on a phone over the local network, and what the panel's preview is and is not.
The widget key is restricted to origins, so a page served from http://localhost:3000 is
refused until that origin is on the key’s list. Everything else about local testing follows from
that.
Allow your local origin
On the panel’s API keys screen, open the widget key and add your local origin to Allowed
origins — the full origin, scheme and port included: http://localhost:3000,
http://127.0.0.1:8080. One line per origin. A refused origin shows as a 403 on
GET /widget/config in the network tab; the launcher still appears, but questions are refused.
Keep a separate widget key for development if you prefer — a key is cheap, and a key whose list holds only your production domains cannot be used from a developer’s laptop.
Test on a phone
A phone on the same network reaches your dev server by the computer’s LAN address, and two things
on the widget need https there: the microphone (a browser grants getUserMedia to secure
origins only) and audio autoplay rules. Serve your page over https on the LAN — a self-signed
certificate the phone trusts, or a tunnelling tool that gives you an https:// address — and add
that origin to the key.
On iOS, sound plays only after a tap: a remembered conversation comes back at rest, and the first tap on the launcher resumes it with sound. That is the browser’s rule, not a bug to work around.
The panel’s live preview
The widget screen in the panel shows the widget in an iframe, with the colours and settings of the form as you edit them. It is the quickest way to try appearance. Two things it is not:
- It runs with
previewModeon, which switches page actions off completely — the iframe’s document is nearly empty and reading it would tell the assistant the screen is blank. Test page actions on your real page. - It spends credits like any other turn once the site is on a plan. Before a plan is active, it answers up to 50 credits a day and 300 a month, and then says the trial allowance is used up.
A widget switched off on its Install tab shows nothing in the preview either.
Never set previewMode on a real site.
What to look at when something is off
| Symptom | Where to look |
|---|---|
no launcher, GET /widget/config answered active: false |
the site is out of credits or not on a plan — GET /widget/config answered active: false |
launcher shows, answers refused, GET /widget/config answered 403 |
the page’s origin is not on the key’s allowed list |
no launcher, GET /widget/config answered 404 |
the widget is switched off (Active on its Install tab), deleted, or the snippet’s data-code names no widget of this site; the console says so in one line |
a warning about data-code |
the snippet lacks the code; the site’s default widget loaded instead |
| answers in the wrong language | <html lang> on the page is not what you think; the reply follows the visitor’s message, the chrome follows lang |
| the assistant does not see your form | page actions are off on the widget, or not on the site’s plan, or the controls are hidden by CSS — Page actions |
| a filled field reverts | your framework re-rendered the control; give it a data-sa-id and bind it to state, not to the DOM value |
The browser’s network tab shows the two calls that matter: GET /widget/config on load, and the
WS /ws socket the conversation runs over.