Identity & HMAC

Tell ForeverChat exactly who a signed-in visitor is — securely. A visitor’s identity is only trusted when it’s accompanied by a valid HMAC signature computed with your website secret.

How it works

The widget can carry an identity object. On boot, ForeverChat recomputes the signature and only applies the identity when it matches:

The signature formula

signature = HMAC_SHA256( externalId ?? email , website_hmac_secret )   // lowercase hex

The signed value is the externalId if you send one, otherwise the email. If the signature is missing or invalid, the visitor is treated as anonymous — the boot never errors, it just stays unidentified.

Never sign in the browser. Anyone can read client-side JavaScript. Always compute the signature on your server with the secret from Settings → Installation, then render it into the page.

Node.js

import crypto from 'node:crypto';

// Your website's secret — find it in Settings → Installation.
// Keep it on the SERVER. Never expose it to the browser.
const secret = process.env.FOREVERCHAT_HMAC_SECRET;

// Sign the externalId if you have one, otherwise the email.
const identifier = user.id; // or user.email
const signature = crypto
  .createHmac('sha256', secret)
  .update(identifier)
  .digest('hex');

// Pass { externalId, email, name, signature } to the widget config.

PHP

<?php
// Keep the secret server-side.
$secret = getenv('FOREVERCHAT_HMAC_SECRET');
$identifier = $user->id; // or $user->email
$signature = hash_hmac('sha256', $identifier, $secret);
?>
<script>
  window.ForeverChat = {
    appId: "fc_YOUR_APP_ID",
    identity: {
      externalId: "<?php echo $user->id; ?>",
      email: "<?php echo $user->email; ?>",
      name: "<?php echo $user->name; ?>",
      signature: "<?php echo $signature; ?>"
    }
  };
</script>
<script async src="https://gateway-381807041351.us-east4.run.app/widget.js"></script>

Ruby

require 'openssl'

secret = ENV['FOREVERCHAT_HMAC_SECRET']
identifier = user.id.to_s # or user.email
signature = OpenSSL::HMAC.hexdigest('SHA256', secret, identifier)

Fields

Field	Required	Notes
externalId	Optional	Your stable user ID. Signed when present.
email	Optional	Signed when no externalId is sent.
name	Optional	Display name shown to your agents.
signature	Required to trust identity	Lowercase hex HMAC-SHA256 of the signed value.

Ready to wire it up? Start from the install guide and add the identity object once your server can produce the signature.