Widget

#Instalación

Instala los bindings de React y el cliente JS subyacente:

1
npm install @customerhero/react @customerhero/js

La forma más rápida de añadir un chatbot es el componente listo para usar ChatWidget:

1
2
3
4
5
6
7
8
9
10
import { ChatWidget } from "@customerhero/react";

export default function App() {
  return (
    <>
      {/* El contenido de tu app */}
      <ChatWidget chatbotId="TU_CHATBOT_ID" />
    </>
  );
}

Toda la configuración del panel se obtiene automáticamente. También puedes sobreescribir opciones mediante props:

1
2
3
4
5
6
7
8
9
10
<ChatWidget
  chatbotId="TU_CHATBOT_ID"
  primaryColor="#0066FF"
  position="bottom-left"
  welcomeMessage="¡Hola! ¿En qué podemos ayudarte?"
  suggestedMessages={[
    "¿Con qué puedes ayudarme?",
    "¿Cómo funciona el precio?",
  ]}
/>

#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.

Pasa una prop identity al componente ChatWidget:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import { ChatWidget } from "@customerhero/react";

function App({ user }) {
  return (
    <ChatWidget
      chatbotId="TU_CHATBOT_ID"
      identity={user ? {
        userId: user.id,          // Obligatorio: ID único estable
        email: user.email,        // Opcional
        name: user.name,          // Opcional
        plan: user.plan,          // Propiedad personalizada
        accountAge: 365,          // Propiedad personalizada
      } : undefined}
    />
  );
}

Cuando cambia la prop identity, el widget borra la conversación actual e inicia una nueva para el usuario identificado.

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
   6
   7
   8
   <ChatWidget
     chatbotId="TU_CHATBOT_ID"
     identity={{
       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.