Widget verified identity

Sign on your server who is chatting: how it’s computed, what changes and how to test it.

GuideHMAC-SHA256Server-side

Generate the secret

In Settings › Web chat (widget) › Verified identity › Generate secret. It’s shown only once: keep it in a server environment variable (BYDOMU_WIDGET_SECRET). If you rotate it, the old one stops working immediately and, until you update the server, your users chat as anonymous visitors.

Compute userHash on your server

userHash = HMAC-SHA256(secreto, userId) in hex. Use a stable internal id, not the email or anything the person can change. Without a userId the email is signed, but then the email becomes the identity: only do that if your site verifies it.

import { createHmac } from "node:crypto";

// Tu backend: el usuario ya inició sesión en tu web.
app.get("/api/bydomu-identity", requireLogin, (req, res) => {
  const userId = String(req.user.id);              // estable: nunca cambia
  const userHash = createHmac("sha256", process.env.BYDOMU_WIDGET_SECRET)
    .update(userId)
    .digest("hex");
  res.json({ userId, email: req.user.email, name: req.user.name, userHash });
});

Hand it to the page

The browser only receives the result, never the secret. Call boot when the person signs in and shutdown when they sign out, so the next user on the same browser doesn’t inherit the conversation.

HTML

<script>
  // Después del código de instalación del widget.
  fetch("/api/bydomu-identity", { credentials: "include" })
    .then((r) => (r.ok ? r.json() : null))
    .then((identity) => identity && Domu("boot", identity));
</script>

<!-- Al cerrar sesión en tu web -->
<script>Domu("shutdown")</script>

What a valid signature changes

With a userId, the contact is looked up by that id (its “external id”), not by email: the email isn’t signed, so nobody can claim someone else’s contact by typing their email. If it doesn’t exist, it’s created with source WEBSITE.
The conversation follows the person across devices, and the attributes and events the page sent before sign-in move to their contact.
Noa sees the contact as verified for 24 hours, and the attributes you send with update count as verified (an unsigned one never overwrites a verified one).
If the signature doesn’t match or there’s no secret, the chat stays anonymous and the visitor sees no error.

Test it

Compare what your server computes with openssl. Then sign in on your site, write in the chat and open the conversation in ByDomu: the contact must be your user’s, not a new visitor.

Shell

# Debe dar lo mismo que tu servidor (hex en minúsculas)
printf '%s' 'u_123' | openssl dgst -sha256 -hmac "$BYDOMU_WIDGET_SECRET"

# Con el secreto «secreto_de_prueba» y userId «u_123»:
# 957e886ac44041d2fe2094ad46f8eade58ef58cd593a62e51d76a7f652d9e4ce

The widget’s full JavaScript API