Widget

#Instalación

Añade este script a tu sitio web, justo antes de la etiqueta de cierre </body>:

1
2
3
4
5
6
<script
  src="https://widget.customerhero.app/v1/loader.js"
  data-chatbot-id="TU_CHATBOT_ID"
  data-api-base="https://us.api.customerhero.app"
  async
></script>

Encuentra tu ID de chatbot en la pestaña Incrustar de la configuración de tu chatbot. El script es ligero (~15KB) y se carga de forma asíncrona, así que no ralentizará tu página.

El atributo data-api-base indica al widget a qué host regional de la API conectarse. CustomerHero almacena los datos de cada organización en una sola región (US o EU), y el widget debe hablar con el host de esa región. Usa https://us.api.customerhero.app para chatbots de la región US y https://eu.api.customerhero.app para chatbots de la región EU. La pestaña Incrustar de tu dashboard genera el snippet con el valor correcto ya rellenado para tu chatbot.

#Personalización

Personaliza la apariencia del widget desde la pestaña Personalizar en la configuración de tu chatbot. Las opciones incluyen:

• Color primario — El color de acento principal para la cabecera y botones del widget
• Posición — Abajo a la derecha (predeterminado) o abajo a la izquierda
• Mensaje de bienvenida — El primer mensaje que ven los visitantes al abrir el chat
• Nombre y avatar del bot — Se muestra en la cabecera del chat

#Identidad del cliente

En las páginas donde tus usuarios han iniciado sesión, puedes pasar su identidad al widget para que las conversaciones se vinculen a los registros de clientes en tu bandeja de entrada.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<script
  src="https://widget.customerhero.app/v1/loader.js"
  data-chatbot-id="TU_CHATBOT_ID"
  data-api-base="https://us.api.customerhero.app"
  async
></script>
<script>
  window.CustomerHero = window.CustomerHero || { q: [] };
  CustomerHero.q.push(["identify", {
    userId: "user_12345",        // Obligatorio: ID único estable de tu sistema
    email: "jane@acme.com",      // Opcional
    name: "Jane Smith",          // Opcional
    phone: "+1234567890",        // Opcional
    company: "Acme Corp",        // Opcional
    plan: "pro",                 // Cualquier propiedad personalizada
    accountAge: 365
  }]);
</script>

El patrón de cola de comandos ({ q: [] }) garantiza que los comandos se almacenen en búfer si el script del widget aún no se ha cargado, similar a las librerías de analíticas. Una vez cargado, puedes llamar a CustomerHero.identify({ ... }) directamente.

El userId debe ser un identificador estable y único de tu sistema (p. ej., un ID de base de datos). Cuando el mismo userId aparece desde otro navegador, la conversación se vincula al mismo registro de cliente.

Los campos estándar como email, name, phone y company se almacenan como campos de cliente de primer nivel. Cualquier propiedad adicional (como plan en el ejemplo) se guarda como metadatos personalizados.

#Verificación de identidad (HMAC)

Para evitar que los usuarios se hagan pasar por otros adivinando un userId, puedes activar la verificación de identidad basada en HMAC. Es opcional pero recomendada para producción.

1. Ve a la página Personalizar de tu chatbot y genera un secreto de verificación de identidad en la sección Verificación de identidad.
2. En tu servidor, calcula un HMAC-SHA256 del ID del usuario usando el secreto:

   1
   2
   3
   4
   5
   const crypto = require("crypto");
   const userHash = crypto
     .createHmac("sha256", "TU_SECRETO_DE_IDENTIDAD")
     .update(userId)
     .digest("hex");

3. Pasa el userHash junto con el userId:

   1
   2
   3
   4
   5
   CustomerHero.q.push(["identify", {
     userId: "user_12345",
     email: "jane@acme.com",
     userHash: "a1b2c3d4..." // HMAC-SHA256 calculado en el servidor
   }]);

Cuando un chatbot tiene configurado un secreto de identidad y se proporciona un userHash, el servidor verifica el HMAC antes de confiar en la identidad. Si la verificación falla, la solicitud es rechazada con un error 403.

#Política de seguridad de contenido (CSP)

Si tu sitio usa una Política de seguridad de contenido, añade estas directivas:

1
2
3
script-src 'self' https://widget.customerhero.app;
connect-src 'self' https://api.customerhero.app;
frame-src 'self' https://widget.customerhero.app;

Sin estas directivas, el navegador bloqueará el script del widget y las solicitudes a la API.