Identity & HMAC

Anonymous visitors work with no setup. To attach conversations to a known user — and prevent anyone from impersonating them — identify the user and sign the identity value with HMAC.

Identity values

Pass one identity key:

userEmail — the user's email, or
userExternalUserId — your own stable user id (wins if both are set).

new SupportWireWidget({
  widgetSlug: 'YOUR_WIDGET_SLUG',
  userEmail: 'customer@example.com',
});

This is enough to identify the user, but unsigned — only use it for low-trust contexts. For production, add an HMAC signature.

Find your widget secret in Settings → Widgets. Compute an HMAC-SHA256 of the identity value (the same email or external id you pass to the widget), hex-encoded, and pass it as userSignature.

Compute the signature on your server. Never ship the widget secret to the browser.

Server (Node.js)

import crypto from 'node:crypto';

function widgetSignature(identity, secret) {
  return crypto
    .createHmac('sha256', secret)
    .update(identity.trim().toLowerCase())
    .digest('hex');
}

const userSignature = widgetSignature('customer@example.com', process.env.WIDGET_SECRET);

Send userSignature to the page and pass it through:

new SupportWireWidget({
  widgetSlug: 'YOUR_WIDGET_SLUG',
  userEmail: 'customer@example.com',
  userSignature, // from your server
});

Server (Elixir)

identity = String.downcase(String.trim(email))

signature =
  :crypto.mac(:hmac, :sha256, secret, identity)
  |> Base.encode16(case: :lower)

Server (Ruby)

require "openssl"

identity = email.strip.downcase
signature = OpenSSL::HMAC.hexdigest("SHA256", secret, identity)

Custom attributes

Attach extra data to the contact via userData:

new SupportWireWidget({
  widgetSlug: 'YOUR_WIDGET_SLUG',
  userEmail: 'customer@example.com',
  userSignature,
  userData: {
    name: 'Alice Johnson',
    plan: 'Pro',
    account_created_at: 1640995200,
  },
});

Attributes show up on the contact in the admin dashboard.