Identifying visitors

Tell the chat agent who the visitor is with a signed identity assertion

Without integration, every visitor chats as an anonymous guest. If your site has its own login, you can assert the visitor's identity to Limio. Identified visitors get the same conversation history on every device they sign in from, and your Limio data ties chat sessions to a stable user ID instead of a random guest.

The mechanism: your backend signs a short-lived JWT with a secret you share with Limio, and your page hands that JWT to the snippet. The browser never sees the secret, only the signed token.

1. Get your identity secret

Ask your Limio contact to generate an embed identity secret for your tenant. Store it in your backend's secret storage (an environment variable is fine). Never put it in frontend code or the page: anyone holding the secret can impersonate any of your users to the chat agent.

2. Sign assertions on your backend

The assertion is an HS256 JWT with three claims:

Claim	Required	Value
sub	yes	Your stable ID for the visitor (up to 128 characters)
iat	yes	Issued-at, now
exp	yes	Expiry. Keep it short; 15 minutes is plenty. The assertion is a one-shot credential exchanged for a chat session; it isn't reused.
aud	no	limio-chat:<tenant>, if your Limio environment is configured to require an audience

Node

import { SignJWT } from "jose"

const secret = new TextEncoder().encode(
  process.env.LIMIO_CHAT_IDENTITY_SECRET
)

export async function signChatAssertion(userId) {
  return new SignJWT({ sub: userId })
    .setProtectedHeader({ alg: "HS256" })
    .setIssuedAt()
    .setExpirationTime("15m")
    .sign(secret)
}

Python

import os
import time
import jwt  # PyJWT

def sign_chat_assertion(user_id: str) -> str:
    now = int(time.time())
    return jwt.encode(
        {"sub": user_id, "iat": now, "exp": now + 900},
        os.environ["LIMIO_CHAT_IDENTITY_SECRET"],
        algorithm="HS256",
    )

PHP

use Firebase\JWT\JWT;

function signChatAssertion(string $userId): string
{
    $now = time();
    return JWT::encode(
        ['sub' => $userId, 'iat' => $now, 'exp' => $now + 900],
        getenv('LIMIO_CHAT_IDENTITY_SECRET'),
        'HS256'
    );
}

3. Hand the assertion to the snippet

Set window.LimioChatConfig before the snippet's script tag. Two options, which you can combine:

<script>
  window.LimioChatConfig = {
    // Option A: your server renders the signed JWT into the page.
    identityAssertion: "<jwt rendered by your backend>",

    // Option B: the snippet fetches a fresh assertion when it needs one,
    // at first load if no static assertion is set, and again if the chat
    // session expires mid-visit. Point it at a small endpoint on your site
    // that returns a JWT for the logged-in user.
    getIdentityAssertion: async () => {
      const res = await fetch("/api/limio-chat-identity", {
        credentials: "include"
      })
      if (!res.ok) return null // visitor not logged in, chat as guest
      const { jwt } = await res.json()
      return jwt
    }
  }
</script>
<script src="https://<your-limio-domain>/__core/embed/bootstrap.js" defer></script>

The static assertion is used first when both are set. If neither produces a JWT, or your endpoint errors, the visitor chats as a guest; identity is never a hard requirement unless your Limio environment is configured to require it.

Sign-in and sign-out without a page reload

On a single-page app, call the JavaScript API when the visitor's login state changes:

await LimioChat.identify(jwt) // after sign-in: switch to an identified session
await LimioChat.logout()      // after sign-out: switch to a fresh guest session

Both start a fresh conversation under the new identity. A guest conversation isn't carried over when the visitor signs in.

How sessions behave

Exchanging an assertion gives the browser a chat session token, kept in your site's localStorage for 24 hours. The stored session is keyed to the asserted user: if a different user signs in (or the visitor signs out), the embed detects the mismatch on the next page load and starts the correct session automatically. If the session expires mid-visit, the embed calls your getIdentityAssertion endpoint once to renew it.