Letting airys know who your signed-in users are
When someone is already logged into your own app, you can let airys know who they are. This makes the chat feel personal and lets that person pick up their past conversations right where they left off. It is completely optional, so you can turn it on whenever you are ready.
Why turn this on
- The chat can greet your customer by name.
- They can see the conversations they had with you before.
- Your team gets clearer context about who they are helping.
How it works in plain terms
When this is on, your website quietly hands the widget a secure sign-in token. You create that token on your own server using a secret key that airys gives you. When the widget receives the token, airys checks it and trusts the details inside it, such as the person's name, email, and company.
Think of the token as a sealed note that only your server can write and only airys can open. Because it is signed with your secret key, airys knows it really came from you.
One important rule
airys only knows what you choose to include in that secure sign-in token. It never guesses who someone is from their email address or anything else. If you do not put a detail in the token, airys will not assume it. This keeps every identity accurate and under your control.
Turning it on
- Open your dashboard.
- Go to Settings > Widget > Behavior.
- Find identity verification and switch it on.
Once it is on, signed-in visitors who arrive with a valid token will be recognized automatically.
Setting up the technical side
Creating and signing the token happens on your server, so a developer on your team will handle that part. The full developer guide is right below.
If you only want a friendly chat experience without personalization, you can simply leave this turned off. Everything else in the widget keeps working the same way.
Developer guide
When to identify {#when-to-identify}
Identify the visitor BEFORE they send their first message. This is the one timing rule. The widget attaches the contact to a conversation at the moment the conversation is created — message #1. If you identify later, the conversation that already exists keeps its original anonymous record, and the dashboard will show "Anonymous" for that thread forever.
In practice this means:
- If you know who's logged in by the time the loader script runs, set the JWT on the script tag itself with
data-user-jwt="…"
. Simplest path; nothing else to wire up. - In a single-page app, call
window.airys.identify(jwt)
from your auth-resolved callback that fires on page load — the same place you'd hydrate your user-state store. Don't wait until the user opens the widget or sends a message; by then it's too late to attribute the conversation. - If your auth lifecycle can't finish before the widget mounts (slow OAuth, async revalidation), add
data-require-identity="true"
to the loader script. The chat bubble stays hidden untilidentify()
succeeds, so the visitor never has the option of starting an anonymous conversation that you'll later wish was attributed.
Two ways to hand airys the token
// Static page — set-and-forget:
// <script async src="…/loader.js"
// data-client-id="wid_…"
// data-user-jwt="<token>"></script>
// SPA / token rotation — call as soon as auth resolves on page load,
// NOT when the user opens the widget:
window.airys.identify(currentUserJwt)
Both routes hit the same code path on the airys backend; pick whichever fits your app's lifecycle, and respect the timing rule above. See Controlling the widget from JavaScript for the full lifecycle (inject → identify → refresh → shut down).
What if I call identify
mid-conversation?
If the visitor has already started chatting anonymously when you call
identify(jwt), the new identity DOES take effect for everything that comes next: history, file uploads, and any future conversations all see the verified contact. But the conversation that's already in flight is NOT retroactively attributed — it keeps the
contactId: nullit was created with, and the dashboard keeps showing it as "Anonymous."
If your integration sometimes runs into this (for example, the visitor opens the widget and chats while your login modal is mid-flight), the two clean fixes are:
- Identify earlier — call
identify(jwt)
the instant your auth state resolves on page load, not on user interaction. - Use
data-require-identity="true"
— keep the bubble hidden until identify succeeds. The visitor can't start an anonymous thread you'll later want to claim.
Signing the token
Sign an HS256 JWT with your widget client's secret (copy it from Settings > Widget > Setup — treat it like a password and keep it on your server). The token must include
iatand
expclaims, and its lifetime must not exceed 24 hours (airys allows ±1 minute of clock skew). We recommend short-lived tokens — 1 hour or less — that you rotate via
window.airys.identify().
Minimal Node example:
import jwt from 'jsonwebtoken'
const token = jwt.sign(
{
sub: user.id, // or externalUserId
email: user.email,
name: user.fullName,
companyExternalId: user.orgId, // optional, links to a Company
companyName: user.orgName, // optional, used only if the company is being auto-created
},
process.env.AIRYS_CLIENT_SECRET,
{ algorithm: 'HS256', expiresIn: '1h' },
)
Claim reference + precedence
| Claim | Required | Notes |
|---|---|---|
sub | required (or externalUserId) | Your stable internal user id, ≤ 128 chars. If both suband externalUserIdare present, subwins. |
externalUserId | alias for sub | Same field, friendlier name. Useful when your auth system already overloads subfor something else. |
iat | required | Issue time (unix seconds). |
exp | required | Expiration (unix seconds). Lifetime capped at 24h. |
| optional | Surfaced on the Contact record in the airys dashboard. | |
name | optional | Display name on the Contact. |
customAttributes | optional | Free-form object. Visible to your agents on the Contact panel. |
companyExternalId | optional | Stable internal company id. airys looks up the Company by (project, companyExternalId); if none exists, one is auto-created. Company linking is never inferred from email domain — if you want the Contact attached to a Company, send this claim. |
companyName | optional | The display name to use when airys auto-creates the company from companyExternalId. Ignored when a company with that id already exists (rename existing companies from the dashboard). |
Headers
The
kidheader is optional. If you include one (so you're ready for future key rotation) it has to match the
kidshown in the dashboard, otherwise airys rejects the token.
What happens when the token expires mid-session
The widget caches a short-lived session token (about 10 minutes) derived from your JWT. There are two kinds of expiry to keep apart:
- Session token expired, JWT still valid — totally transparent. The widget re-mints the session in the background using the JWT you last supplied. The visitor never notices.
- JWT itself expired (or revoked) — the widget fires the
'identity-expired'
event. Subscribe to it from your auth-refresh handler:window.airys.on('identity-expired', async () => { const fresh = await auth.refreshToken() window.airys.identify(fresh) })
Between expiry and the next successfulidentify()
, the open conversation keeps its current 10-minute session token so the user keeps chatting; only session-bound features (history, file uploads) wait until identity is restored.
When you do call
identify(freshJwt), the swap is immediate — by the time the call resolves, the widget has minted a fresh session token and reconnected its realtime stream. No wasted 401 + retry round-trip mid-conversation.
The
identity-expiredhandler is load-bearing for long-idle visitors. When a visitor's JWT expires while they're idle and they later try to send a message, the widget pauses briefly waiting foridentify(fresh). If your handler doesn't respond within ~3 seconds, the visitor sees "Your session expired. Please refresh the page or sign in again." and can't send until they reload. The handler isn't optional for sessions that outlive the JWT lifetime — wire it.
Linking signed-in visitors to your help center
When the AI cites an article, the widget already appends the visitor's session to the help-center link so a click lands them authed — including on
requiresAutharticles. No setup needed; it just works as long as
identify()was called before the message.
For deep-links you build yourself (in-app docs links, transactional emails, a "Help" button in your product), append
?identify=<jwt>to the help-center URL:
const helpHref = `https://help.acme.com/articles/billing-faq?identify=${encodeURIComponent(jwt)}`
When the visitor clicks, the help-center server verifies the JWT, plants a same-origin session cookie, and redirects to the clean URL (
?identify=stripped). The cookie covers the rest of their visit — clicking around the help-center menu keeps them authed without further tokens.
If the JWT is missing, expired, or invalid, the help center silently renders anonymous (public articles still load;
requiresAuthones stay hidden). No login screen, no error banner.