SDK de chat en vivo

Validación de identidad

Cuando llamas a setUser desde el navegador, cualquiera que lea tu JavaScript puede hacerse pasar por cualquiera de tus clientes. La validación de identidad cierra esa brecha exigiendo una firma que solo tu servidor puede generar.

Cómo funciona

Cada bandeja de entrada de widget web tiene un secreto privado — el token HMAC — que solo vive del lado del servidor. Para demostrar que un visitante es realmente el usuario que dices, firmas su identifier con ese token usando HMAC-SHA256 y envías el resultado junto con los datos del usuario.

Tu backend lee el token HMAC desde el panel una sola vez y lo guarda como secreto.
Cuando generas una página para un usuario con sesión iniciada, tu backend calcula identifier_hash = HMAC-SHA256(identifier, hmacToken).
El hash se inserta en la página y se pasa a $hellouOne.setUser.
HellouOne vuelve a calcular el hash de su lado y solo acepta la identidad si coincide.

Solo se firma el identificador

La firma cubre la cadena identifier y nada más. El nombre, el correo electrónico, la URL del avatar y los demás campos del usuario viajan junto con ella, pero no forman parte del hash — trata el identificador como el campo canónico de “quién es esta persona”.

1. Encuentra tu token HMAC

En el panel, abre Bandejas de entrada → (tu widget web) → Configuración. El token HMAC aparece debajo del snippet de inserción. Cópialo en un almacén de secretos de tu backend — nunca lo subas a un repositorio público ni lo expongas al navegador.

2. Calcula el hash en el servidor

A continuación hay ejemplos mínimos en algunos lenguajes comunes. En todos los casos, la entrada es el identificador del usuario como cadena y la clave es el token HMAC.

Node.js

const crypto = require('crypto');

const identifierHash = crypto
  .createHmac('sha256', process.env.HELLOUONE_HMAC_TOKEN)
  .update(String(user.id))
  .digest('hex');

Ruby

require 'openssl'

identifier_hash = OpenSSL::HMAC.hexdigest(
  'sha256',
  ENV.fetch('HELLOUONE_HMAC_TOKEN'),
  user.id.to_s
)

Python

import hmac, hashlib, os

identifier_hash = hmac.new(
    os.environ['HELLOUONE_HMAC_TOKEN'].encode(),
    str(user.id).encode(),
    hashlib.sha256
).hexdigest()

PHP

$identifierHash = hash_hmac(
  'sha256',
  (string) $user->id,
  getenv('HELLOUONE_HMAC_TOKEN')
);

3. Envía el hash al navegador

Inserta el hash en la página junto con el resto del contenido del usuario y pásalo a $hellouOne.setUser cuando el SDK esté listo.

<script>
  window.addEventListener('hellouone:ready', function () {
    window.$hellouOne.setUser('42', {
      name: 'Ada Lovelace',
      email: '[email protected]',
      avatar_url: 'https://example.com/ada.png',
      phone_number: '+15551234567',
      identifier_hash: '<%= identifier_hash %>'
    });
  });
</script>

Convierte el identificador en cadena

El hash en el servidor debe calcularse sobre la forma de cadena del identificador. Si firmas 42 como entero en un lugar y pasas "42" como cadena en otro, los resúmenes no coincidirán y la llamada será rechazada.

Modo obligatorio frente a opcional

Cada widget web se puede configurar en uno de dos modos:

Opcional — setUser funciona con o sin identifier_hash. Cuando el hash está presente y coincide, el contacto resultante queda marcado como verificado.
Obligatorio — setUser se rechaza a menos que identifier_hash esté presente y coincida. Úsalo cuando tienes usuarios con sesión iniciada y quieres garantizar que nadie pueda suplantarlos desde el navegador.

Rotar el token

Si el token HMAC se filtra (por ejemplo, si terminó por error en un bundle del cliente), rótalo desde el panel. Todos los hashes emitidos anteriormente dejan de ser válidos de inmediato, así que vuelve a desplegar tu backend con el nuevo secreto como parte del mismo cambio — de lo contrario, las sesiones activas empezarán a fallar.