Saltar al contenido principal

​
Identidad del visitante

Algunas acciones agenticas son personales: mostrar a un visitante sus pedidos, facturas, suscripcion o tickets de soporte. El bot solo las ejecuta cuando puede probar quien es el visitante. Lo pruebas enviando un JWT corto, firmado en tu backend, que lleva el email del visitante.
La identidad solo hace falta para acciones personales. Las acciones publicas (explorar productos, agendar una llamada, abrir un ticket) ya funcionan para visitantes anonimos.

​
Como funciona

Tu usuario inicia sesion en tu sitio

Tu app ya sabe quien es.

Tu backend firma un JWT

Con tu signing key de BestChatBot (HS256), tu backend genera un token corto con el email del visitante.

Entregas el token al widget

Mediante setUserToken() o el atributo data-user-token.

El bot verifica y actua

BestChatBot comprueba la firma, lee el email verificado y ejecuta las acciones personales de forma segura.

​
Que debe contener el token

El bot lee estos claims. Solo email es obligatorio.
ClaimObligatorio?Para que sirve
emailSiLa identidad verificada. Debe ser un email real y publico. El bot lo pasa a minusculas.
expRecomendadoCaducidad (segundos Unix). Mantenlo corto. El bot rechaza tokens con vida mayor de 24 horas.
nameRecomendadoPersonaliza las respuestas y fija el nombre del visitante en las acciones.
user_idOpcionalEl ID del usuario en tu sistema, util para tus registros.
picture, phone, otrosOpcionalesSe pasan tal cual. El bot ignora lo que no usa.
Token minimo (Node.js): 
const jwt = require("jsonwebtoken");

const token = jwt.sign(
  { email: user.email.toLowerCase(), name: user.name },
  process.env.BESTCHATBOT_SIGNING_KEY, // tu signing key, solo backend
  { algorithm: "HS256", expiresIn: "1h" }
);
En Firmar el JWT tienes Python, PHP, Go, Java, .NET y ejemplos por proveedor (WordPress, Clerk, Firebase, Supabase, Auth0).

​
Consigue tu signing key

Abre la configuracion de tu widget en el dashboard, ve a Security / Identity Verification y crea una Signing Key. Copiala una vez y guardala como secreto en tu backend. Puedes tener hasta 3 keys activas, asi rotas sin cortes: firmas con la nueva mientras la antigua sigue verificando, y luego retiras la antigua.
La signing key es un secreto compartido, como una contrasena. No es lo mismo que tu API key del widget (rk_live_...). Nunca la subas al repositorio ni la expongas al navegador.

​
Entrega el token al widget

Elige la via que encaje con tu app. Las dos envian el token al bot como Authorization: Bearer <jwt>. Opcion A, en runtime (SPAs): llama a la API del widget cuando tengas el token. 
window.BestChatBot.setUserToken(token);
// al cerrar sesion:
window.BestChatBot.clearUserToken();
Opcion B, renderizado en servidor: pon el token en el script tag. 
<script
  src="https://widget.bestchatbot.io/widget/v1/chat.js"
  data-api-key="rk_live_xxxxxxxxxxxxxxxxxxxx"
  data-user-token="EL_JWT_FIRMADO"
  defer>
</script>

​
Reglas de seguridad

  • Firma el JWT solo en tu backend. La signing key nunca llega al navegador.
  • Genera un JWT nuevo para BestChatBot. Nunca reenvies el token de sesion de Clerk, Supabase, Firebase o Auth0.
  • Pasa el email a minusculas antes de firmar.
  • Manten exp corto (1 hora es un buen valor). El limite duro son 24 horas.
  • Renueva el token cuando se renueve la sesion de tu usuario.

​
Tokens anonimos e invalidos

SituacionQue hace el bot
No se envia tokenTrata al visitante como anonimo. Las acciones personales quedan apagadas; el bot responde de forma segura.
Token validoEjecuta acciones personales con el email verificado.
Token caducado o manipuladoBloquea la accion a proposito. No cae a anonimo.
Email con dominio reservado (.local, .test, etc.)Tratado como anonimo. Usa un email real y publico.

​
Siguientes pasos

Firmar el JWT

Codigo de backend para cada stack y lenguaje.

Integraciones disponibles

Mira que acciones necesitan un visitante identificado.