Website widget

Identify signed-in widget customers

Connect the widget to verified customer profiles and safely make previous support conversations available.

Anonymous chat works without identification. For signed-in customers, use OutcomeArc.identify(customer, signature) so OutcomeArc can recognize the customer, accept their profile data, and show their support history.

Sign the customer on your server

Copy the server signing secret from Widget settings as an owner or administrator. Keep it in your server’s secret storage, never in the install snippet or browser code.

Build the customer object from your authenticated user. Include a valid email, a stable id when available, optional name, and the custom properties you want to send. Sign compact JSON with recursively sorted object keys using HMAC-SHA256.

This Node.js helper signs the object your server has built:

import { createHmac } from "node:crypto";

const canonical = (value) => Array.isArray(value)
  ? `[${value.map(canonical).join(",")}]`
  : value && typeof value === "object"
    ? `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`
    : JSON.stringify(value);

export function signWidgetCustomer(customer, secret) {
  return createHmac("sha256", secret).update(canonical(customer)).digest("hex");
}

Use JSON-compatible values. Your server should choose the identity and properties itself, rather than signing arbitrary customer objects sent by a browser.

Identify after the script loads

Return the customer object and signature to the signed-in page. After the widget script has loaded, call:

await OutcomeArc.identify(customer, signature);

Wait for this promise before showing a customer-specific message or survey. Identification alone doesn’t start a conversation, open the panel, or invoke AI.

Send a complete property snapshot, not just changed fields, and generate a new signature whenever the object changes. Use the custom-field keys and types configured for the inbox.

Account changes and history

After successful identification, the contact form no longer asks for an email address. Previous conversations are limited to that verified customer and the widget’s inbox.

A typed email is a follow-up address, not identity verification. It doesn’t unlock another session’s history.

Changing the signed customer clears the old local conversation context. On logout, use a full-page navigation to clear the in-memory identity; an empty identify call is not a logout API.

If identification fails, check the signed object, canonical serialization, correct widget secret, allowed domain, availability, and field validation. A changed property with an old signature will be rejected.

Browse all topics →

Still need a hand? Ask our team.