Live chat widget JavaScript API

Embed

Paste this before the closing </body> tag. Your widget token is on the live chat channel's settings page.

<script>
  window.ZonoChat = { token: 'wgt_your_widget_token' };
</script>
<script src="https://zono.support/widget.js" async></script>

window.ZonoChat options

Light and dark themes

The widget comes in light and dark, tinted with your channel's primary color. By default it matches your page: a dark class or data-theme="dark" on <html>, or color-scheme: dark, and otherwise the visitor's system setting, switching live when either changes. Pick a fixed theme for the channel in Settings > Channels > Live chat, or per page with theme or a data-theme attribute on the script tag. It renders in a Shadow DOM, so your site's CSS never restyles it.

<script>
  // 'auto' (default) follows your page's dark mode, then the visitor's system setting.
  window.ZonoChat = { token: 'wgt_your_widget_token', theme: 'dark' };
</script>
<!-- or: <script src="https://zono.support/widget.js" data-theme="dark" async></script> -->
<script src="https://zono.support/widget.js" async></script>

Identity verification

Generate your identity secret under Settings > Customer sign-in > Identity verification (admins and owners). One workspace secret covers every live chat channel and, if you use it, customers signing in to the portal. It is shown once: keep it on your server and never ship it to the browser. Your server signs each logged-in user and passes the signature as user.hash. A channel's own identity secret (Settings > Channels > Live chat) still works as a fallback.

• hash = hex(HMAC-SHA256(secret, identifier)). The identifier is user.id as a string (trimmed) when you pass an id; otherwise the email, trimmed and lowercased. The same semantics as Intercom's user_hash.
• Sign exactly what you send: if the widget gets id 42, sign "42". Name and, when you sign an id, email are not covered by the hash.
• A hash is your server's assertion about who the visitor is, and Zono trusts it as far as it trusts the secret: whoever holds the secret can sign any identity. See the Customer identity guide for the trust model.
• A valid hash links the chat to that customer on every device, folds the visitor's anonymous chat on this browser into it, and always issues a fresh visitor token.
• A hash the server cannot verify is refused (403 identity-verification-failed): the widget logs a console warning and continues as an anonymous visitor.
• Without a hash, or before a secret exists, the id and email are unverified claims: they never link the visitor to an existing customer.
• Require verified identities (enforcement mode) ignores unsigned identity fields altogether.
• The workspace secret is checked first, then the live chat channel's own secret, so embeds signed with a channel secret keep working.
• Recommended: pass user.token instead of user.hash. It is an HS256 JWT with claims typ "identity", sub (the user id, or the lowercased email), optional email and name, iat, and exp at most 24 hours after iat. Add aud (this widget's token) to make it valid for this widget only. Unlike a hash, a token expires, so one copied out of a page stops working. Zono tolerates 60 seconds of clock difference; only alg HS256 is accepted.
• Sign the token with a key derived from your secret, never the secret itself: key = hex(SHA-256("zono-widget-identity-v1:" + secret)), the 64 lowercase hex characters used as the HMAC key. Metadata tokens use "zono-widget-metadata-v1:" instead, so neither kind of token can stand in for the other or for a user.hash.
• A token that is expired, lives longer than 24 hours, has another typ, names another aud, uses another algorithm or is signed with another key is refused (403 identity-verification-failed), like a bad hash. If you also send user.id, it must match sub. user.hash keeps working unchanged.
• Once a session's identity token expires (60 seconds of grace), the session is trusted with nothing until the page passes a fresh token: its widget calls answer 401 identity-expired. Call Zono('identify', { id, token }) with a new token before the old one runs out.
• Rotating the workspace secret keeps the previous one verifying for 24 hours, so you can update your servers without breaking chats. Revoke deletes every secret at once.

<script>
  window.ZonoChat = {
    token: 'wgt_your_widget_token',
    user: {
      id: 'usr_12345',            // your user id (externalId is accepted as an alias)
      email: '[email protected]',
      name: 'Jane Doe',
      hash: '<?= $userHash ?>'    // hex HMAC-SHA256 computed on your server
    }
  };
</script>
<script src="https://zono.support/widget.js" async></script>

Computing the hash on your server

function zonoWidgetHash(string $secret, ?string $userId, ?string $email = null): string
{
    // The user id as a string, or the lowercased, trimmed email when there is no id.
    $id = trim((string) $userId);
    $identifier = $id !== '' ? $id : mb_strtolower(trim((string) $email));

    return hash_hmac('sha256', $identifier, $secret);
}

// $userHash = zonoWidgetHash(getenv('ZONO_IDENTITY_SECRET'), (string) $user->id);

Signing an expiring identity token (recommended)

<?php
// Identity token: an HS256 JWT that expires (at most 24 hours).
function zono_b64url(string $value): string
{
    return rtrim(strtr(base64_encode($value), '+/', '-_'), '=');
}

// Signed with a key derived from the secret, never the secret itself.
$key = hash('sha256', 'zono-widget-identity-v1:'.getenv('ZONO_IDENTITY_SECRET'));

$header = zono_b64url(json_encode(['alg' => 'HS256', 'typ' => 'JWT']));
$payload = zono_b64url(json_encode([
    'typ' => 'identity',
    'sub' => (string) $user->id,      // or the lowercased email
    'email' => $user->email,
    'name' => $user->name,
    'aud' => 'wgt_your_widget_token',             // optional: this widget only
    'iat' => time(),
    'exp' => time() + 3600,           // at most 24 hours after iat
]));
$signature = zono_b64url(hash_hmac('sha256', "$header.$payload", $key, true));

$userToken = "$header.$payload.$signature"; // pass as user.token

The same secret can sign customers in to your portal. The customer identity guide covers the trust model, portal tokens and the redirect contract.

Events

Besides open, close and message, Zono.on(name, callback) delivers these events. The callback receives the payload shown.

Open an article from a link

Add data-zono-article with an article id or slug to any link or button on your page. A click opens that article in the widget. Links added later work too, and a new-tab click (Ctrl or Cmd) behaves as usual.

<!-- Opens the article in the widget. Without the widget, the link works as a normal link. -->
<a href="https://help.example.com/articles/how-refunds-work" data-zono-article="how-refunds-work">How refunds work</a>

Calling Zono before the script loads

widget.js loads asynchronously. Add the one-line stub first and call Zono('method', ...args) right away: the calls are queued and replayed in order once the widget has loaded.

<script>
  window.Zono=window.Zono||function(){(window.Zono.q=window.Zono.q||[]).push(arguments)};
  window.ZonoChat = { token: 'wgt_your_widget_token' };
  // Safe before widget.js has loaded: replayed in order once it has.
  Zono('identify', { id: 'usr_12345', email: '[email protected]', hash: 'USER_HASH' });
  Zono('open');
</script>
<script src="https://zono.support/widget.js" async></script>

Logout on sign-out

The browser keeps a visitor token so a returning visitor sees their chat. Call Zono.logout() when your user signs out, so the next person on a shared device starts a fresh, anonymous chat.

async function signOut() {
  await fetch('/logout', { method: 'POST' });
  // Forget this browser's chat so the next person starts fresh.
  window.Zono?.logout();
}

Custom CSS and behaviour rules

CSP, allowed origins and storage