Controlling the widget from JavaScript
The install snippet (
<script async src="https://widget.airys.ai/v1/loader.js" data-client-id="…">) is enough for most websites. But if your app is a single-page app, gates the widget behind a login, mints short-lived identity tokens, or just wants its own Help button to open the chat, you'll need to drive the widget from JavaScript.
Once the loader script has executed, airys publishes a small global at window.airys
that gives you everything you need: open / close the panel, identify the visitor, rotate the JWT, and tear the widget down when the user logs out.
The full surface
| Method | Purpose |
|---|---|
window.airys.open() | Opens the chat panel — same effect as clicking the bubble. |
window.airys.close() | Closes the chat panel; the bubble reappears. |
window.airys.identify(jwt) | Registers or rotates the user-identity JWT. Call this BEFORE the visitor sends their first message — see When to identify for the timing contract; calling it mid-conversation leaves the in-flight thread attributed to "Anonymous" in your dashboard. The verified session is swapped immediately (no failed-then-retry round-trip) and the realtime stream reconnects in the background. Pass nullto clear (revert to anonymous). |
window.airys.shutdown() | Tears the widget down completely. Removes the bubble, kills network connections, clears internal state and event subscribers. Safe to call multiple times. |
window.airys.on(event, cb) | Subscribe to a lifecycle event. Returns an unsubscribe function. |
window.airys.off(event, cb) | Remove a specific listener. |
window.airys.version | Build identifier (a short git SHA, or "dev"). Include this in support tickets. |
All methods are safe to call before the panel has actually been built. The widget is lazy: the heavy panel DOM is constructed on the first
open()(or first bubble click), not at script load.
Events
Every event is a signal — none of them carry a payload. If your handler needs the conversation id, JWT, etc., read it from your own state.
| Event | Fires when |
|---|---|
'opened' | The chat panel becomes visible. |
'closed' | The chat panel is dismissed. |
'identity-verified' | A call to identify(jwt)(or the boot-time data-user-jwt) successfully minted a verified session. |
'identity-expired' | A call failed because the JWT itself is no longer accepted by the server (revoked, past exp, signature mismatch). Subscribe to this to recover — mint a fresh JWT from your auth system and call identify(newJwt). |
'identity-failed' | A non-401 error happened during identify (network blip, server outage). Same recovery path; just informational. |
'conversation-resolved' | The currently-open conversation transitioned from any other status to resolved. Useful for triggering an in-app survey or your own post-resolution UI. |
Patterns
Open the chat from your own button
document.querySelector('#help-button')!.addEventListener('click', () => {
window.airys.open()
})
If the panel has never been opened before, the first
open()waits for the in-flight config fetch (≤ ~100ms typically) before painting. Subsequent calls are instant.
Identify a logged-in user
Two equivalent ways: a
data-user-jwt="…"attribute on the loader script (set-and-forget for static pages) or a call to
identify():
// Anywhere after the loader has executed.
window.airys.identify(currentUserJwt)
identify()swaps the verified session immediately — by the time the call resolves, the widget has minted a fresh session token for the new JWT and reconnected its realtime stream. There's no "next request will use the new identity" lag and no wasted 401 + retry, even mid-conversation.
Calling
identify(null)clears the identity. The next API call uses anonymous mode.
Rotate the JWT before it expires
airys identity tokens have a hard maximum lifetime of 24 hours, but we recommend you mint shorter-lived tokens (e.g. 1 hour). When your app rolls a new token, hand it to the widget:
auth.onTokenRefresh((freshJwt) => {
window.airys.identify(freshJwt)
})
If the old token expires before you call
identify()with a new one, the widget fires an
'identity-expired'event. Subscribe to it from the same place you handle your own auth-refresh logic so you never have to poll:
window.airys.on('identity-expired', async () => {
const fresh = await auth.refreshToken()
window.airys.identify(fresh)
})
Between expiry and the next successful
identify()call, the open conversation keeps its current 10-minute session token — the user keeps chatting — and only the session-bound API calls (history fetch, new uploads) hold off until identity is restored.
Tear the widget down on logout
auth.onLogout(() => {
window.airys.shutdown()
})
shutdown()does the full cleanup: closes the panel, cancels the realtime stream, removes the
<airys-widget-host>element from the DOM, and clears the internal flag that prevents double-loading. After shutdown, simply re-injecting the loader script (e.g. when the user logs in again) mounts a fresh instance.
window.airysitself is replaced with a stub after shutdown — calling
airys.open()afterwards logs a warning instead of silently doing nothing.
Single-page app lifecycle
// On app boot (or on login)
function ensureWidgetLoaded() {
if (window.airys) return // already loaded
const s = document.createElement('script')
s.src = 'https://widget.airys.ai/v1/loader.js'
s.async = true
s.dataset.clientId = MY_CLIENT_ID
document.body.appendChild(s)
}
// On login
ensureWidgetLoaded()
window.airys.identify(currentUserJwt)
// On token refresh
window.airys.identify(freshJwt)
// On logout
window.airys.shutdown()
Note:
window.airysis published synchronously inside the loader script's execution. If you call
airys.identify(jwt)immediately after appending the
<script async>tag, you need to wait for the script's
loadevent first. The simplest pattern is the one above — set
data-client-id, then in a microtask after the
s.onload(or just check for
window.airysand try again) call
identify().
Internals you may need to know about
These names are stable and safe to inspect, but you shouldn't have to touch them in normal use:
<airys-widget-host>
— the custom element that holds the bubble + panel inside a closed Shadow DOM. Removed byshutdown()
.window.__airysWidgetLoaded
— a boolean guard the loader sets on script execution to prevent double-mounting if the script tag appears twice. Cleared byshutdown()
.
If you previously worked around the lack of a public API by manually removing the host element and the
__airysWidgetLoadedflag — you can replace all of that with a single
window.airys.shutdown()call now.
Versioning
window.airys.versionreturns the short git SHA of the deployed loader (or
"dev"in local builds). Include it whenever you file a support ticket — it tells us which build's behavior you're describing.
Showing the bubble only to signed-in visitors
Set
data-require-identity="true"on the loader script (or pass
requireIdentity: trueif you build the script tag programmatically). The widget then keeps the bubble hidden on page load and only reveals it after the first successful
identify(jwt).
<script async
src="https://widget.airys.ai/v1/loader.js"
data-client-id="wid_..."
data-require-identity="true"></script>
Two ways to satisfy the gate:
- Boot-time identity — also include
data-user-jwt="…"
. The loader mints a verified session as soon as it executes; the bubble pops in the moment the JWT verifies, fires'identity-verified'
, and the visitor can chat. - Runtime identity — leave the script alone and call
window.airys.identify(jwt)
from your own code (e.g. inside your login handler). Same lifecycle, just under your control.
If the JWT is rejected, the bubble stays hidden and
'identity-failed'fires. Calling
identify(null)(e.g. on logout) re-hides the bubble.
window.airysis published synchronously regardless of whether the bubble is visible, so your
identify()call always has somewhere to land.