Merchant identity
A merchant never signs in to Whoa Chat. Your server says who they are, in a token signed with your app's chat secret, and the chat trusts nothing else.
The merchant token
signMerchant(chatSecret, identity, opts?) from @whoa-chat/connector returns an HS256 JWT. The chat package sends it as Authorization: Bearer on every merchant call and as token on the live connection.
| Field | What it is |
|---|---|
app | Your app's Shopify client id. It picks the workspace and the secret. |
shop | The store's *.myshopify.com domain, from your Shopify session. Required. |
email | Where Whoa Chat emails replies the merchant has not seen. Required. |
name | The person writing, shown to your team. |
timezone, locale, country | Optional. An IANA time zone, a language tag such as de or pt-BR, a two-letter country code. |
store | Optional details for your team's store panel, at most 6 KB of JSON. |
import { signMerchant } from "@whoa-chat/connector";
const token = signMerchant(process.env.WHOA_CHAT_SECRET!, {
app: process.env.SHOPIFY_API_KEY!,
shop: session.shop, // from authenticate.admin, never from the browser
email: shop.email,
name: staffMember.name,
locale: "de",
timezone: "Europe/Berlin",
country: "DE",
}, { ttlS: 3600 }); // one minute to one hour, an hour by defaultWhat the chat checks
- The signature, with your app's current secret or, during a rotation, the previous one.
- The purpose and version, so no other token of ours can pass as a merchant token.
- The app named in the token is the app the secret belongs to.
exphas not passed,iatis not in the future, and the token lives at most an hour.shopis amyshopify.comdomain andemailis an address.
The shop, email and name come only from the verified token: nothing the browser sends can change which store a message belongs to.
Keeping it fresh
Serve the token from a route of yours and let the chat fetch it. cachedMerchantToken(fetchToken) from @whoa-chat/react/chatApi returns a getter that keeps the token until five minutes before it expires, then fetches a new one; give the same getter to merchantChatApi and useLive.
const token = cachedMerchantToken(() => fetch("/api/chat-token", { cache: "no-store" }).then((r) => r.text()));Rotating the secret
In Settings, Apps, New secret gives you a new chat secret once. The previous one keeps working for 24 hours, time to update your servers. If a secret leaked, choose New secret, old one stops now instead: the previous secret is refused at once.
Removing an app in Settings deletes its secret. Merchants of that app can no longer reach the chat until it is added again.