Identify customers and pass context

Basic customer details

These values fill the current visitor’s profile. Plain contact details do not authorize another person’s conversations.

await TruComWidget.identify({
  name: 'John Doe',
  email: '[email protected]',
  phone: '+2348000000000',
  company: 'Example Ltd'
});

Website attributes

Use strings up to 1,000 characters, numbers or booleans. null removes a key. Names start with a letter and contain letters, digits, underscores, dots or hyphens, up to 64 characters. Keep the merged context within 50 attributes and 20 KB. Nested values and reserved prototype names are rejected.

Attributes are stored on the current visitor session and appear separately as Website details in the authenticated customer profile and inbox. They do not overwrite CRM attributes or serve as verified account facts.

await TruComWidget.setAttributes({
  user_id: '1234',
  subscription: 'Business',
  customer_status: 'VIP',
  orders: 12,
  opted_in: true
});
await TruComWidget.setAttributes({ customer_status: null });

Signed identity

Create a signing secret in widget settings. On your server, issue a short-lived tcid1 proof for a stable internal user ID. Pass only the proof to the browser. The same signed subject can recover its authorized history across sessions.

The token consists of tcid1, base64url JSON claims, and an HMAC-SHA256 hex signature over the first two parts. Required claims are widget, sub, iat, exp and profile. Lifetime is at most 3,600 seconds. Use a stable subject; email is a profile field, not the history authorization key.

// A token issued by YOUR authenticated backend for the current user.
const response = await fetch('/support/identity', { credentials: 'same-origin' });
if (!response.ok) throw new Error('Could not verify support identity');
const { identity_token } = await response.json();
await TruComWidget.identify({ identity_token });

Issue a proof in PHP

// Server only. Never expose $secret to the browser.
$claims = [
    'widget' => $widgetPublicKey,
    'sub' => (string) $authenticatedUser->id,
    'iat' => time(),
    'exp' => time() + 900,
    'profile' => ['name' => $authenticatedUser->name,
                  'email' => $authenticatedUser->email],
];
$payload = rtrim(strtr(base64_encode(json_encode($claims)), '+/', '-_'), '=');
$unsigned = 'tcid1.'.$payload;
$token = $unsigned.'.'.hash_hmac('sha256', $unsigned, $secret);

Sign out or switch accounts

Reset before a different person signs in on the same device. Reset revokes the current widget session and clears its displayed conversations, drafts, selected attachments and local outbox.

await TruComWidget.reset();
// After the next user signs in, request a new proof from your backend.
await TruComWidget.identify({ identity_token: nextUserToken });

Expiry and rotation

Generate a fresh proof when a signed identity expires. Replacing a signing secret invalidates old proofs; update the website backend at the same time. Do not cache a proof across users or embed one permanently in public HTML.