airysdeveloper

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

  1. Open your dashboard.
  2. Go to Settings > Widget > Behavior.
  3. 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 until
    identify()
    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: null
it 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:

  1. Identify earlier — call
    identify(jwt)
    the instant your auth state resolves on page load, not on user interaction.
  2. 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

iat
and
exp
claims, 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

ClaimRequiredNotes
sub
required (or
externalUserId
)
Your stable internal user id, ≤ 128 chars. If both
sub
and
externalUserId
are present,
sub
wins.
externalUserId
alias for
sub
Same field, friendlier name. Useful when your auth system already overloads
sub
for something else.
iat
requiredIssue time (unix seconds).
exp
requiredExpiration (unix seconds). Lifetime capped at 24h.
email
optionalSurfaced on the Contact record in the airys dashboard.
name
optionalDisplay name on the Contact.
customAttributes
optionalFree-form object. Visible to your agents on the Contact panel.
companyExternalId
optionalStable 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
optionalThe 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

kid
header is optional. If you include one (so you're ready for future key rotation) it has to match the
kid
shown 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 successful
    identify()
    , 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-expired
handler 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 for
identify(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

requiresAuth
articles. 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;

requiresAuth
ones stay hidden). No login screen, no error banner.