Cómo instalar el Web Widget de Cloud Chat: público, con datos o en área logada (HMAC)

Cuándo usar

• Quieres añadir el chat de Cloud Chat en cualquier página de tu sitio web

• Quieres pasar datos del contacto automáticamente (nombre, correo electrónico, teléfono, atributos) sin que el cliente tenga que escribir

• Quieres validar la identidad del usuario (HMAC) para impedir que alguien se haga pasar por otra persona

• Quieres permitir múltiples conversaciones simultáneas y acceder al historial dentro del widget

• Quieres restringir el widget a dominios específicos (por ejemplo, solo en producción)

Requisitos previos

• Estar logueado como administrador en Cloud Chat

• Acceso al código fuente del sitio donde se instalará el widget

• Para el Escenario 3 (área logada con HMAC): backend propio para generar el identifier_hash — no puede hacerse en el frontend (exponer la clave secreta)

Sobre este tutorial

Este artículo cubre el ciclo completo de instalación del Web Widget de Cloud Chat. Antes de seguir los pasos de código, debes decidir cuál de los 3 escenarios se ajusta a tu caso de uso — tienen requisitos y complejidad muy distintos.

¿Cuál escenario es el tuyo?

Etapa común para todos los escenarios — Crear la bandeja de entrada del tipo Web Widget

Antes de configurar cualquier escenario, debes crear una bandeja de entrada del tipo Sitio Web en Cloud Chat. El procedimiento es el mismo para los 3 escenarios.

1. Acceder a la pantalla de Bandejas de Entrada

En el panel de Cloud Chat, ve a Configuraciones → Bandejas de Entrada y haz clic en el botón Agregar Bandeja de Entrada (arriba a la derecha).

2. Elegir el canal Website

Selecciona la tarjeta Sitio Web en la cuadrícula de canales disponibles.

3. Configurar el canal del sitio web

Completa los campos:

• Nombre del sitio — nombre visible para el cliente (ej: "Cloud Humans")

• Dominio del sitio web — dominio donde correrá el widget (ej: cloudhumans.com)

• Color del Widget — color principal del botón y encabezado

• Sé bienvenido — título inicial del widget (ej: "¡Hola!")

• Mensaje de bienvenida, saludo — mensaje de bienvenida

• Activar saludo del canal — si quieres enviar un mensaje automático al iniciar la conversación

Haz clic en Crear bandeja de entrada.

4. Agregar agentes

Selecciona los agentes que tendrán acceso a esta bandeja. Como administrador, agregate a ti mismo si quieres ver todas las conversaciones.

Haz clic en Agregar agentes.

5. Configuración del script

En la pantalla final (“¡Tu bandeja está lista!”), Cloud Chat muestra el script básico de instalación del widget. Sin embargo, hay otras opciones de configuración que se pueden usar según tu escenario.

Haz clic en Más configuraciones. En esa sección, verás las tres opciones de scripts disponibles para instalación, que explicaremos a continuación.

Escenario 1 — Web Widget público (sin pasar datos del cliente)

Usa este en páginas públicas (landing, blog, sitio institucional). El cliente escribe su nombre/correo/teléfono al comenzar.

Cómo instalar

Copia el script de la Etapa Común (Paso 5) justo antes del cierre de la etiqueta </body> en el HTML de la página:

Escenario 2 — Web Widget pasando datos, fuera de área logada

Úsalo cuando ya conoces el contacto, pero la página no requiere login. Ejemplos:

• Enlace único enviado por email o WhatsApp con el identifier en la URL

• Página posterior a registro (el cliente acaba de completar un formulario)

• Página accedida vía enlace profundo de campaña de CRM

Aquí quieres prellenar nombre, email, teléfono y atributos personalizados sin que el cliente tenga que escribir.

Cómo instalar

Escenario 3 — Web Widget en área logada (con HMAC + opcionalmente múltiples conversaciones)

Úsalo cuando el widget está dentro de una área logada (portal del cliente, panel, app autenticada). Aquí HMAC es obligatorio.

Este escenario también es el único donde tiene sentido habilitar múltiples conversaciones + historial.

3.1 — Cómo funciona HMAC

La validación usa HMAC SHA-256: un código generado a partir del identifier del usuario combinado con una llave secreta (token) de la bandeja de entrada.

3.2 — Copiar el token de la bandeja

En Configuraciones → Bandejas de Entrada → (tu bandeja Sitio Web) → Configuración avanzada → Validación de Identidad del Usuario → Copiar.

Este token es secreto — guárdalo solo en el backend, nunca en el frontend.

3.3 — Calcular el identifier_hash en el backend

Cuando el usuario inicia sesión en tu sistema, el backend calcula:

identifier_hash = HMAC_SHA256(token_de_la_bandeja, identifier)

Donde identifier es el ID único del usuario (UUID interno, email corporativo, etc).

Ejemplos en servidor:

// Node.js
const crypto = require('crypto');
const hash = crypto
  .createHmac('sha256', '<token-de-la-bandeja>')
  .update('<identifier>')
  .digest('hex');

# Python
import hashlib, hmac
hash = hmac.new(b'<token-de-la-bandeja>', b'<identifier>', hashlib.sha256).hexdigest()

// PHP
$identifier_hash = hash_hmac('sha256', '<identifier>', '<token-de-la-bandeja>');

3.4 — Enviar el hash al widget usando setUser

<script>
  (function(d,t) {
    var BASE_URL="https://cloudchat2.cloudhumans.com";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g,s);

    g.onload=function(){
      window.cloudchatSDK.run({
        websiteToken: 'TU_TOKEN_AQUI',
        baseUrl: BASE_URL
      });

      window.addEventListener('cloudchat:ready', function() {
        window.$cloudchat.setUser('<id-usuario>', {
          identifier_hash: '<hash-generado-en-backend>',
          email: '[email protected]',
          name: 'João da Silva',
          phone_number: '+5511999999999'
        });
      });
    }
  })(document,"script");
</script>

3.5 — Forzar validación en la bandeja

En Configuraciones avanzadas, activa la opción "Forzar validación de identidad del usuario" → Habilitado. Desde ese momento, las solicitudes sin un identifier_hash válido serán rechazadas.

3.6 — (Opcional) Activar múltiples conversaciones e historial

Con el HMAC funcionando, puedes activar la función de múltiples conversaciones + historial: el mismo usuario puede mantener varias atenciones abiertas en paralelo y ver el historial de conversaciones ya cerradas dentro del propio widget.

Útil para SaaS, B2B o comercio electrónico con altas tasas de recompra/recontacto.

Cómo funciona para el usuario: el widget mostrará dos pestañas — Conversaciones activas (en curso) y Historial de conversaciones (cerradas, con búsqueda por fecha inicial, final y ID del ticket; carga 5 a la vez).

Videos demostrativos:

Cómo habilitar:

1. En el panel de Cloud Chat, ve a Bandejas de Entrada → (tu bandeja Sitio Web) → Configuración

2. Activa la opción Múltiples conversaciones por usuario

3. Copia el nuevo script que aparece tras la activación — ya viene con user_id y identifier_hash en el formato correcto

4. Sustituye el script actual en la página por este nuevo

Validación de Dominio (opcional, en todos los escenarios)

Configura los dominios donde puede funcionar el widget — útil para evitar uso fuera de dominios autorizados (sandbox, terceros no autorizados).

En Bandejas de Entrada → (tu bandeja) → Configuración, en la sección Validación de Dominio:

Cómo probar

1. Abre la página con el widget instalado

2. Verifica que el widget aparece en la esquina de la pantalla

3. Escenarios 2 y 3: confirma que nombre, email, teléfono y atributos aparecen ya completados sin que el cliente tenga que escribir

4. Escenarios 2 y 3: prueba con al menos 2 usuarios diferentes — abre el widget con uno y luego con otro, revisa en el panel si aparecen como contactos separados (no fusionados en uno solo). Si aparecen fusionados, el identifier está fijo — corrige antes de pasar a producción

5. Escenario 3: prueba con un identifier_hash inválido y confirma que el widget rechaza la solicitud cuando “Forzar validación” está habilitado

6. Escenario 3 con múltiples conversaciones: abre dos tickets en paralelo y confirma que aparecen como conversaciones separadas dentro del widget

Preguntas frecuentes

¿Qué pasa si ya existe una información previa del contacto?

La nueva información enviada vía script sobrescribe los datos antiguos. El dato más reciente prevalece.

¿Y si cometo un error en el nombre de algún campo personalizado?

No se genera ningún error. El campo incorrecto se ignora silenciosamente. Solo se actualizan los campos existentes.

¿Puedo pasar atributos también de la conversación?

¿Qué formatos de texto acepta el widget?

El Widget acepta la mayoría de los formatos de Markdown:

• Negrita / Tachado / Cursiva

• Bloques de código

• Enlaces

• Imágenes

• Puntos en lista

¿Puedo usar HMAC sin activar conversaciones múltiples?

Sí. HMAC es una capa de seguridad independiente — puedes activar solo HMAC (Escenario 3, pasos 3.1 a 3.5) sin activar múltiples conversaciones (paso 3.6). Lo contrario no es recomendable.

¿Puedo usar esto también en aplicaciones móviles?

Sí, mediante WebView. Consulta Cómo integrar el Web Widget en apps móviles.

Consideraciones

• Para compartir la sesión del widget entre pestañas del navegador: Cómo compartir la sesión del Web Widget entre pestañas

• Para usar el widget en apps mobiles vía WebView: Cómo integrar el Web Widget en aplicaciones móviles

• Para crear atributos personalizados antes de pasarlos vía script: Cómo crear campos personalizados de contactos y conversaciones

• Para activar la continuidad de conversación por email: Cómo habilitar la continuidad de conversaciones por email

• Para activar el widget en el Portal de Ayuda: Cómo activar el Web Widget en el Portal de Ayuda