Identity verification
Identity verification lets your website prove which signed-in customer is chatting. Your server signs a short-lived JSON Web Token (JWT) with the bot’s secret, and the widget hands it to FluentChat. FluentChat checks the signature before it links the conversation to that customer.
Open Bot > Channels > Chat bubble, select Add to website, then Website widget. The Identity verification section is below the install code. Center stage shows the same section.
Before you start
- Permission to update the bot. Without it, the section shows “You need permission to update this bot to change these settings.”
- The JavaScript widget. Install the widget with the code from Website widget. The iframe embed doesn’t support signed identity: “For host-page events and signed visitor identity, use the JavaScript widget.”
- A server that knows the signed-in user. You add one endpoint to your own application that returns a token for the current user.
If your site runs on WordPress with the FluentChat connector, the connector can recognize logged-in WordPress users itself. See WordPress integration.
How it works
- You turn on verification. FluentChat generates a signing secret for this bot.
- You store the secret on your server. When a customer signs in, your server issues a JWT for them.
- Your page passes the token to the widget with
identify(), or withidentityTokenwhen it mounts. - FluentChat checks the token. If it’s valid, the visitor is linked to your customer ID. If it isn’t, the widget rejects it; it doesn’t fall back to an anonymous visitor.
Visitors without a token still chat anonymously. “Anonymous visitors can still chat.”
Set up identity verification
-
Turn on verification. In the Identity verification section, turn on the switch.
-
Generate the secret. If the section shows “Setup required. Old team signatures no longer work.”, select Generate bot secret.
-
Copy the secret. Under Copy your new secret now, select Copy secret. “It is shown only once.” Store it on your server as
FLUENTCHAT_IDENTITY_SECRET. Use it exactly as shown; don’t decode it. -
Issue tokens from your server. Add an endpoint that authenticates the current user and returns a token. See Create the token.
-
Pass the token to the widget. After the customer signs in, fetch a token from your endpoint and call
identify(). On sign-out, calllogout(). See Connect the widget.
Create the token
Sign an HS256 JWT on your server for each signed-in customer. These examples expire after one hour, the longest lifetime FluentChat accepts.
// Server only. Install jsonwebtoken in your backend: npm install jsonwebtokenimport jwt from "jsonwebtoken";
export function createChatIdentityToken(user) { return jwt.sign( { sub: String(user.id), aud: "fluentchat:bot:YOUR_BOT_ID", name: user.name, email: user.email, }, process.env.FLUENTCHAT_IDENTITY_SECRET, { algorithm: "HS256", expiresIn: "1h" }, );}
// Return { token } from your own authenticated endpoint, such as /api/chat-identity.// Never return the signing secret.<?php// Server only. Install firebase/php-jwt in your backend:// composer require firebase/php-jwtuse Firebase\JWT\JWT;
function createChatIdentityToken(object $user): string{ $now = time();
return JWT::encode([ 'sub' => (string) $user->id, 'aud' => 'fluentchat:bot:YOUR_BOT_ID', 'iat' => $now, 'exp' => $now + 3600, 'name' => $user->name, 'email' => $user->email, ], getenv('FLUENTCHAT_IDENTITY_SECRET'), 'HS256');}
// Return ['token' => $token] from your own authenticated endpoint, such as /api/chat-identity.// Never return the signing secret.jsonwebtoken adds iat for you, and expiresIn: "1h" sets exp. In PHP, set both yourself as whole seconds.
Connect the widget
Your page asks your server for a token, then passes it to the widget. window.fluentChatWidget is the handle the install code saves.
// Call after the widget has loaded and the customer has signed in.async function identifyCustomer() { const response = await fetch("/api/chat-identity", { credentials: "same-origin", cache: "no-store", }); if (!response.ok) throw new Error("Could not verify identity"); const { token } = await response.json(); await window.fluentChatWidget.identify(token);}
// Call when the customer signs out of your website.async function logoutCustomer() { await window.fluentChatWidget.logout();}If the customer is already signed in when the page loads, you can pass the token when you mount the widget instead:
const widget = await window.FluentChat.mount({ botId: "YOUR_BOT_ID", identityToken: tokenFromYourServer,});window.fluentChatWidget = widget;Always await identify() and logout() before you call other widget methods. While a switch is running, other methods throw widget_not_ready, and a second switch rejects with identity_in_progress.
When the token expires
The widget doesn’t refresh tokens. When a token expires, the widget emits identity.expired and switches to an anonymous visitor. Wait for that switch to finish, then identify the customer again with a fresh token:
window.fluentChatWidget.on("identity.expired", () => { // The widget is switching to an anonymous visitor. Identify again when it's ready. window.fluentChatWidget.once("initialized", () => { identifyCustomer().catch((error) => console.warn(error)); });});Token requirements
The token must be a compact JWT signed with HS256 and this bot’s secret. The header must contain only alg: "HS256" and typ: "JWT". Extra header fields, such as kid, are rejected.
| Claim | Type | Required | Description |
|---|---|---|---|
sub | string | Yes | Your stable customer ID, 1 to 255 characters. Use an ID that never changes, not an email address. |
aud | string | Yes | Exactly fluentchat:bot:YOUR_BOT_ID. A list of audiences is rejected. |
iat | integer | Yes | Issued-at time in whole seconds. It can’t be in the future. |
exp | integer | Yes | Expiry in whole seconds. It must be in the future, and no more than 3,600 seconds after iat. |
nbf | integer | No | Not-before time in whole seconds. It can’t be in the future. |
name | string or null | No | The customer’s name, up to 255 characters. An empty or blank name is rejected. |
email | string or null | No | A valid email address, up to 255 characters. |
data | object or null | No | Extra profile data as JSON: strings, numbers, booleans, null, lists, and objects. Up to 32 KB and 15 levels deep. |
Leave out name, email, or data when you don’t have a value. Don’t send an empty string.
FluentChat links the visitor to the bot and the exact sub. The same sub on another device reaches the same visitor and history. A different sub is a different visitor, even with the same email.
What FluentChat does with the identity
- Signed profile fields stay out of AI context.
name,email, anddataare saved to the visitor’s profile, not sent to the AI. - Public hints go through
setContext(). To tell the AI something non-secret about the page or plan, usesetContext(). Don’t put identity or secrets there. - The widget keeps the token in memory. It isn’t written to browser storage.
- Signing out clears the widget identity, not the token. “An issued token remains valid until it expires or you change its signing policy.” Stop issuing tokens when the customer signs out.
Manage the secret
| State or control | What it means |
|---|---|
| ”Off. Enable to generate a secret for this bot.” | Verification is off. Signed tokens aren’t accepted. |
| ”Setup required. Old team signatures no longer work.” | Verification was on with the old team signature. Select Generate bot secret and update your signing server. |
| ”Configured. Only this bot uses its signing secret.” | Verification is on and the bot has a secret. |
| Regenerate secret | Creates a new secret. “Existing tokens and website sessions verified with this bot’s secret will stop working.” Other bots are unaffected. |
| Copy secret / Hide secret | Copies or hides a newly generated secret. Reloading or leaving the bot also clears it from the screen. |
Turning verification off deletes the bot’s secret. When you turn it on again, FluentChat generates a new secret, so update your server.
Move from team signatures
Earlier versions signed a visitor object with a team-wide HMAC secret. That method no longer works:
- The
visitoroption is rejected.FluentChat.mount()and the olderinjectWidget()throwinvalid_configurationwhen you passvisitor. - Team secrets don’t verify visitors. Each bot now has its own secret and audience.
To move, generate the bot secret, replace your HMAC code with one of the token examples, and pass the token with identify() or identityToken.
Limitations
- Tokens last at most one hour. Request a fresh token from your server when one expires; the widget never refreshes it for you.
- One secret per bot. Each bot needs tokens with its own
audand secret. - Logout doesn’t revoke a token. A copied token keeps working until it expires or you regenerate the secret.
- The iframe embed has no signed identity. Use the JavaScript widget.
Troubleshooting
identify() rejects with identity_rejected
Possible cause: FluentChat rejected the token. Common reasons: aud names another bot, the secret is old or wrong, the token expired, exp is more than an hour after iat, iat or exp isn’t a whole number, the header has extra fields, or name is empty.
Solution: Decode the token on your server and compare it with the token requirements. Then call identify() again with a new token, or call logout() to continue anonymously.
Tokens are rejected right after they’re issued
Possible cause: Your server’s clock is ahead, so iat is in the future when FluentChat checks it.
Solution: Sync your server’s clock with a time service.
All signed-in visitors are rejected after a change
Possible cause: Someone selected Regenerate secret, or turned verification off and on, and your server still signs with the old secret.
Solution: Copy the new secret, update FLUENTCHAT_IDENTITY_SECRET on your server, and issue new tokens.
mount() or identify() fails with invalid_configuration
Possible cause: The code passes the old visitor object, or the token isn’t a compact JWT string.
Solution: Remove visitor, and pass the token string from your server as identityToken or to identify().
identify() rejects with connection_unavailable
Possible cause: The widget couldn’t reach FluentChat. An invalid token can also surface this way, because the browser hides the server’s reason.
Solution: Check the network and the token, then call identify() again.