Widget de chat web

​

Qué es

• Anónimo — no requiere nada de tu backend. El widget genera un identificador de visitante propio (guardado en localStorage del navegador) para reconocerlo entre mensajes.
• Identificado — si el visitante ya está logueado en tu sitio, tu backend puede firmarle la identidad para que MINDO la reconozca. Esto une, bajo un mismo contacto, todos los chats que ese usuario abra desde distintos dispositivos, y le deja la conversación disponible cuando vuelve.

​

Antes de empezar

• Acceso a Configuración → Canales en MINDO con rol de administrador.
• Acceso al código de tu sitio (para pegar un <script>).
• Si vas a identificar usuarios logueados: acceso al backend de tu sitio, para firmar la identidad. La firma se calcula siempre en el servidor, nunca en el navegador.

​

Paso a paso

1

Crear el canal Web

Desde MINDO, andá a Configuración → Canales y buscá la sección Widget de chat web. Hacé clic en + Agregar canal Web.

Completá:

• Nombre de la sesión — identifica el canal dentro de MINDO y, además, es el título que ve el visitante en el header del chat (por ejemplo, “Chat de la tienda”).
• Color primario — el color del header del panel, de las burbujas del visitante y del botón Enviar.
• Mensaje de bienvenida — el primer mensaje que ve el visitante mientras no haya conversación. No se guarda como mensaje ni dispara al agente.
• Agente (opcional) — si querés que un agente de IA responda automáticamente en este canal.

El agente no responde en el widget por el solo hecho de existir en la empresa: tiene que estar asignado acá. Con Sin agente, los mensajes esperan respuesta humana en el Inbox, como cualquier otro canal.

Una empresa puede tener varios canales Web a la vez —uno por marca, por sitio o por país—. Cada uno tiene su token, su color y su agente, y las conversaciones de uno nunca se mezclan con las del otro.

2

Copiar el snippet

Al crear el canal, MINDO te muestra el snippet listo para copiar:

<script
  src="https://app.mindosoftware.com/widget.js"
  data-mindo-token="TU_TOKEN_DE_CANAL"
  async
></script>

También vas a ver un Secret HMAC — lo necesitás únicamente si vas a identificar visitantes logueados (Paso 4). Guardalo en un lugar seguro; nunca debe quedar expuesto en el HTML de tu sitio.

El token del snippet es público: viaja en el HTML de tu sitio y es esperable que se vea. El Secret no: se muestra enmascarado y solo lo pueden ver los usuarios con rol ADMIN de la empresa (a un MEMBER o VIEWER la API le devuelve el campo vacío).

3

Pegar el snippet en tu sitio

Pegá el <script> antes del cierre de </body> en las páginas donde querés que aparezca el chat. No hace falta ningún build step ni dependencia — es un script vanilla, autocontenido.Al cargar la página vas a ver una burbuja de chat abajo a la derecha. Al hacer clic, se abre un panel con el chat (es un <iframe> a MINDO, así que tu sitio no necesita implementar ninguna UI de chat).

Si no aparece la burbuja, revisá la consola del navegador: el error más común es un data-mindo-token vacío o incorrecto.

La burbuja flotante siempre es azul. El color primario que configuraste aplica adentro del panel (header, burbujas del visitante, botón Enviar), no a la burbuja. Es el comportamiento esperado, no un error de configuración.

A partir de acá, cada mensaje del visitante crea un chat en tu Inbox con canal Web, y tu equipo lo atiende con el mismo composer de siempre. El chat del widget suma un dato que ningún otro canal tiene: el indicador “Está en la página”, que te dice si el visitante sigue con tu sitio abierto en este momento.

4

(Opcional) Identificar visitantes logueados

Si tu sitio tiene usuarios logueados y querés que MINDO los reconozca (en vez de tratarlos como anónimos), tu backend firma un JWT y lo pasa en el atributo data-mindo-identity.El JWT se firma con algoritmo HS256 usando el Secret HMAC del canal, y su payload admite estos campos:

Campo	Obligatorio	Qué es
sub	Sí	El identificador único de tu usuario — el que uses vos internamente.
exp	Sí	Vencimiento (timestamp Unix, en segundos).
name	No	Nombre del usuario, para que el contacto no quede como “Visitante”.
email	No	Email del usuario.
phone	No	Teléfono en formato internacional. Es lo que permite unificar este contacto con el de WhatsApp.

El exp no puede estar a más de 7 días. Un JWT con un vencimiento más lejano se considera inválido y el visitante queda anónimo. Es un tope deliberado: si a alguien le roban el token, siete días es lo máximo que ese robo puede servir. Un TTL de 24 a 72 horas es lo habitual.

Node.js

Python

const jwt = require("jsonwebtoken");

function firmarIdentidad(usuario, secretDelCanal, ttlSegundos = 60 * 60 * 24) {
  return jwt.sign(
    {
      sub: String(usuario.id),
      name: usuario.nombre,
      email: usuario.email,
      phone: usuario.telefono,
      exp: Math.floor(Date.now() / 1000) + ttlSegundos,
    },
    secretDelCanal,
    { algorithm: "HS256" }
  );
}

Renderizá el token en el <script> desde una plantilla del lado del servidor:

<script
  src="https://app.mindosoftware.com/widget.js"
  data-mindo-token="TU_TOKEN_DE_CANAL"
  data-mindo-identity="{{ identityToken }}"
  async
></script>

El Secret HMAC es un secreto de servidor. Nunca lo incluyas en HTML, JavaScript del cliente, ni en un repositorio público — solo debe existir en tu backend, del mismo modo que guardarías cualquier otra API key.

Con la identidad firmada, el chat deja de mostrar “Visitante ####” y pasa a ser la persona real, con su teléfono y su email ya cargados en la ficha del contacto:

La firma es opcional por diseño: si falta, está vencida o es inválida, el visitante simplemente queda anónimo — el chat nunca se bloquea por un error de firma. Eso hace que puedas probar sin riesgo de dejar el widget caído.La contracara es que un JWT mal armado falla en silencio. Si el contacto sigue apareciendo como “Visitante ####”, revisá en este orden: que el secret sea el del mismo canal que el token, que el exp esté en segundos (no milisegundos) y a menos de 7 días, que el claim se llame sub, y que el algoritmo sea HS256.

Método anterior: los tres atributos con firma HMAC

Antes del JWT, la identidad se pasaba con tres atributos separados. Sigue funcionando y no hace falta que migres: si ponés los dos esquemas a la vez, gana el JWT, y si el JWT está roto se cae a este.

Atributo	Qué es
data-mindo-user	El identificador único de tu usuario (userId).
data-mindo-expires	Timestamp Unix (segundos) hasta cuándo es válida la firma.
data-mindo-signature	HMAC_SHA256(secret, "{userId}:{expires}") en hexadecimal.

Node.js

Python

const crypto = require("crypto");

function firmarVisitante(userId, secretDelCanal, ttlSegundos = 60 * 60 * 24) {
  const expires = Math.floor(Date.now() / 1000) + ttlSegundos;
  const signature = crypto
    .createHmac("sha256", secretDelCanal)
    .update(`${userId}:${expires}`)
    .digest("hex");
  return { userId, expires, signature };
}

<script
  src="https://app.mindosoftware.com/widget.js"
  data-mindo-token="TU_TOKEN_DE_CANAL"
  data-mindo-user="{{ userId }}"
  data-mindo-signature="{{ signature }}"
  data-mindo-expires="{{ expires }}"
  async
></script>

Por qué conviene el JWT si estás empezando: este esquema firma la cadena userId:expires usando : como separador, así que no admite sumarle el nombre o el email sin volverse ambiguo. El JWT firma los datos exactos y te deja mandar name, email y phone — que es lo que permite que el contacto tenga nombre real y se unifique con su chat de WhatsApp.

5

(Opcional) Identificar al visitante después de que inició sesión

Si tu sitio es una SPA, o el visitante abre el chat antes de loguearse, no hace falta recargar la página para que MINDO lo reconozca. El widget expone un objeto window.Mindo:

// Después de que tu usuario inicia sesión, con el JWT que firmó tu backend:
window.Mindo.setUser(identityToken);

// Al cerrar sesión:
window.Mindo.clearUser();

El script se carga con async, así que puede que window.Mindo todavía no exista cuando tu código corre. Para eso hay una cola de comandos: encolá las llamadas y el widget las procesa al terminar de cargar.

window.Mindo = window.Mindo || { q: [] };
(window.Mindo.q = window.Mindo.q || []).push(["setUser", identityToken]);

También podés hacerlo sin escribir código de integración: si tu página guarda el JWT en localStorage bajo la clave mindo_identity, el widget lo toma solo. Sirve para el caso del login en una pestaña nueva o con un redirect de OAuth, porque el widget escucha los cambios de esa clave. El mismo valor se puede difundir por un BroadcastChannel llamado mindo-identity.

Además de setUser y clearUser, window.Mindo expone open(), close() y toggle() para manejar el panel desde tu propia UI (por ejemplo, un botón “¿Necesitás ayuda?”), y on(evento, callback) / off(evento, callback) para escuchar open, close, unread, identity, identity:cleared, auth:login y auth:register.

6

(Opcional) Invitar a iniciar sesión desde el chat

El widget puede mostrarle al visitante anónimo un bloque con botones de Iniciar sesión y Crear cuenta que apuntan a las páginas de tu sitio. Desaparece solo cuando el visitante queda identificado.

Se configura desde Configuración → Canales → Widget de chat web, editando el canal: activá Botones de inicio de sesión y completá las URLs, los textos de los botones y el mensaje que va arriba.

Campo	Qué es
URL de inicio de sesión	Adónde mandar al visitante que ya tiene cuenta.
URL de registro	Adónde mandarlo si todavía no la tiene.
Textos de los botones	Opcionales. Por defecto, “Iniciar sesión” y “Crear cuenta”.
Mensaje sobre los botones	La frase que explica para qué conviene loguearse.

Alcanza con una de las dos URLs: el botón que no tenga URL no se muestra.También se puede hacer por API, con un usuario ADMIN de la empresa:

curl -X PATCH https://api.mindosoftware.com/web-widget/channels/<ID_DEL_CANAL>/ \
  -H "Authorization: Bearer <TOKEN_DE_UN_ADMIN>" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "enabled": true,
      "loginUrl": "https://tusitio.com/login",
      "registerUrl": "https://tusitio.com/registro",
      "loginLabel": "Iniciar sesión",
      "registerLabel": "Crear cuenta",
      "prompt": "Iniciá sesión para ver tus pedidos y retomar la conversación desde cualquier dispositivo."
    }
  }'

Al hacer clic, el widget abre la URL en una pestaña nueva. Si preferís manejar la navegación vos (por ejemplo, abrir tu propio modal de login), interceptalo: devolver false en el handler cancela la apertura.

window.Mindo.on("auth:login", ({ url }) => {
  abrirMiModalDeLogin();
  return false;
});

Las URLs deben ser https://. Una http:// se rechaza al guardar, y si se cargó a mano desde el admin el botón directamente no se renderiza.

Mandá el bloque en el campo auth, no adentro de config. Un config explícito reemplaza al guardado (salvo prechat y auth), así que un {"config": {"auth": {...}}} te borra el color y el mensaje de bienvenida. El campo auth plano se guarda solo, sin tocar el resto.

​

¿Qué pasa después?

• Cada mensaje que un visitante te escribe crea (o continúa) un chat en tu Inbox de MINDO, con Canal: Web.
• Si identificaste al visitante y esa misma persona te escribe desde otro dispositivo con el mismo sub, MINDO unifica el historial bajo un solo contacto.
• Si el JWT incluye phone y ese teléfono ya existe como contacto de WhatsApp, MINDO los unifica: queda un contacto con sus dos conversaciones (la del widget y la de WhatsApp), en vez de dos personas distintas.
• Si tenés un agente de IA asignado al canal, puede responder automáticamente; si no, el chat espera respuesta humana como cualquier otro canal.

​

Preguntas frecuentes

¿Necesito instalar algo en mi sitio además del script?

No. El <script> es autocontenido: crea su propia burbuja y su propio panel de chat (un iframe). No requiere CSS, dependencias ni build step.

¿Puedo tener el widget en varias páginas de mi sitio?

Sí, pegá el mismo snippet en todas las páginas donde quieras que aparezca. El visitante se identifica por un ID guardado en su navegador, así que si navega entre tus páginas mantiene la misma conversación.

¿Qué pasa si el visitante recarga la página en medio de una conversación?

No pierde nada: el widget recupera la conversación automáticamente al recargar y la muestra apenas abre el panel, sin necesidad de que escriba de nuevo.

¿El visitante se entera si le respondemos con el chat cerrado?

Mientras tenga tu página abierta, sí: la burbuja muestra un contador con los mensajes que llegaron con el panel cerrado, y se limpia cuando lo abre.

Si cerró la pestaña, hoy no hay aviso: la próxima vez que vuelva a tu sitio va a encontrar la respuesta al abrir el chat, pero no le llega ninguna notificación mientras tanto. Por eso conviene pedirle teléfono o email a través del JWT (phone / email): con esos datos podés retomar la conversación por otro canal.

¿El visitante puede mandar fotos o audios?

No. El composer del widget es solo texto, con un tope de 4.000 caracteres por mensaje. Del lado del operador sí se pueden enviar archivos, y el visitante los recibe en el panel.

¿Hay límites de uso en los endpoints públicos?

Sí, topes anti-abuso por IP, muy por encima del uso de una persona real: 30 por minuto para enviar mensajes, 20 por minuto para el conteo de no leídos y 10 por minuto para abrir sesión con identidad firmada.

¿Qué pasa si no configuro la identificación?

Nada se rompe: todos los visitantes quedan como anónimos, cada uno con su propio chat. Podés agregar la identificación más adelante sin cambiar nada de lo ya instalado.

¿Tengo que migrar del método de tres atributos al JWT?

No. El esquema anterior sigue soportado y no tiene fecha de baja. Migrá solo si querés mandar el nombre, el email o el teléfono del usuario — cosas que el formato viejo no admite.

¿Puedo restringir en qué sitios se puede usar mi token?

Sí. El canal tiene una lista de orígenes permitidos (allowed_origins): con la lista vacía —el valor por defecto— no hay restricción; con orígenes cargados, el header Origin de la página tiene que coincidir exacto con alguno o la API responde 403.Todavía no está expuesta en el formulario de Configuración: se carga por API (PATCH /web-widget/channels/<id>/ con allowed_origins) o desde el admin. Si la activás, incluí todos los dominios y subdominios desde los que se sirve tu sitio: uno que falte deja el chat sin funcionar en esas páginas.

¿Puedo pedirle teléfono o email al visitante antes de que escriba?

Hoy no lo actives. La configuración existe en el backend (config.prechat, con niveles off / optional / required para phone y email) pero el widget todavía no muestra ese formulario, así que nunca envía esos datos.

Con phone o email en required, el primer mensaje de un visitante nuevo recibe 422 {"error": "Faltan campos obligatorios"} y el visitante no puede iniciar la conversación. Dejalo en off hasta que exista la UI.

¿Tiene costo adicional?

El canal Web no tiene un costo de mensajería como WhatsApp (no depende de Meta). Consultá con tu plan de MINDO si aplica algún límite de uso.