When your customers are logged in on your website or in your app, you can identify them with a JWT (JSON Web Token). Your backend signs the token, and Conversation SDK passes it to Zowie when the conversation starts.

With authentication:

The customer always returns to the same conversation. The sub claim of the token identifies the conversation, so the customer continues it on any device and any platform where they log in.
The customer's details come from a trusted source. Name, email and your own attributes from the token are signed by your backend, so they can't be changed in the browser or in the app.

Customers who aren't logged in can still talk to your AI Agent. Without a token, the conversation is anonymous.

Set up authentication

Create a key. Zowie supports three signing algorithms:
- RS256: an RSA key pair.
- ES256: an elliptic curve key pair.
- HS256: a shared secret.
Send the key to your TAM. For RS256 and ES256, send the public key. For HS256, share the secret in a secure way. Your TAM turns on authentication for your Instance ID.
Generate tokens on your backend. Sign each token with your private key or secret. Never generate tokens in the browser or in the app, because anyone could then read your key.

Token payload

Claim	Type	Required	Description
`sub`	`string`	Yes	Unique ID of the customer. It identifies the conversation, so use the customer's ID from your system.
`firstName`	`string`	No	Customer's first name.
`lastName`	`string`	No	Customer's last name.
`email`	`string`	No	Customer's email address.
`phoneNumber`	`string`	No	Customer's phone number.
`locale`	`string`	No	Customer's locale, for example `en-US`.
`extraParams`	`object`	No	Your own attributes as key-value pairs with string values.
`exp`	`number`	No	Expiration time. Zowie rejects expired tokens.

{
  "sub": "customer-48213",
  "iat": 1762425600,
  "exp": 1762429200,
  "firstName": "Ada",
  "lastName": "Lovelace",
  "email": "[email protected]",
  "locale": "en-US",
  "extraParams": {
    "tier": "vip",
    "shopName": "Bike Store"
  }
}

⚠️
Use a stable ID in sub. If sub changes, the customer starts a new conversation. If two customers get the same sub, they share one conversation.

Pass the token

Widget and Embedded

Pass the token in the configuration object of init:

ZowieWidget.init("<your-instance-id>", {
  externalAccessToken: "<jwt-from-your-backend>",
});

For Embedded, pass the same option to ZowieEmbedded.init.

If the token isn't ready when the page loads, provide it on demand with setExternalAccessTokenCallback. Conversation SDK calls your function when the chat loads and waits until you call onSuccess or onFailure:

ZowieWidget.init("<your-instance-id>", {
  onLoaded: () => {
    ZowieWidget.setExternalAccessTokenCallback((onSuccess, onFailure) => {
      fetch("/api/zowie-token")
        .then((response) => response.text())
        .then((token) => onSuccess(token))
        .catch(() => onFailure("Could not get a token"));
    });
  },
});

When you set the callback, it takes priority over externalAccessToken.
If you call onFailure, the conversation doesn't start.
Set the callback in onLoaded. Calls made before the Widget or Embedded has loaded are ignored.

Mobile apps

All mobile SDKs accept the token in the externalAccessToken configuration option. See the documentation of your SDK in Mobile.

When the customer logs out

The conversation is stored on the device, so end it when the customer logs out. Otherwise the next person on the same device could see it.

Platform	What to call
Widget	`ZowieWidget.endChat()`
Embedded	Load Embedded with `resetSession: true` on the first page after logout.
Mobile SDKs	`endChat()` on the chat controller. See the documentation of your SDK.

Troubleshooting

If the token is invalid, expired or signed with a different key than the one your TAM set up, the conversation doesn't start. Check that:

the token is signed with the algorithm and key you sent to your TAM,
the token contains sub,
the token hasn't expired.