@supcoflow/chat

El chat de intake de Supcoflow, embebible en cualquier sitio. Conversa con un asistente que orienta sobre el producto y, cuando hay un bug de verdad, abre un reporte en Supcoflow.

Instalación

Con npm (React, Vue, Svelte, vanilla)

npm i @supcoflow/chat

En React:

import { ChatDeIntake } from "@supcoflow/chat";

<ChatDeIntake tenantId="tnt_xxx" projectId="proj_xxx" />

Sin React:

import { montarChat } from "@supcoflow/chat";

const chat = montarChat(document.body, { tenantId: "tnt_xxx", projectId: "proj_xxx" });
// chat.desmontar() cuando haga falta

Con una línea de <script> (WordPress, Webflow, HTML plano)

<script src="https://chat.supcoflow.dev/widget.js" data-tenant="tnt_xxx" data-project="proj_xxx" defer></script>

Opciones por atributo: data-backend, data-posicion (derecha|izquierda), data-abierto="true", data-titulo, data-saludo, data-acento (color), data-version-app, data-contexto-automatico="false", data-usuario-id, data-usuario-rol, data-usuario-nombre. También queda window.SupcoflowChat.montar(opciones) / .desmontar().

Los identificadores son públicos (modelo DSN). La contención es la lista de Origins admitidos del proyecto más el tope de mensajes, los dos del lado de Supcoflow.

Opciones

| opción | default | qué | |---|---|---| | backendUrl | https://chat.supcoflow.dev | el backend del chat | | modo | "burbuja" | "burbuja" (botón flotante + panel) o "inline" (el panel donde lo montes) | | posicion | "derecha" | lado de la burbuja | | abierto | false | el panel arranca abierto | | titulo | "Ayuda" | cabecera del panel | | saludo | — | la segunda línea de la pantalla de inicio; gana sobre la consola | | tema | neutro | { acento, fondo, texto, textoSuave, radio, fuente }, cualquier subconjunto | | contexto | {} | { versionApp } — viaja con el primer mensaje | | contextoAutomatico | true | manda la URL (sin query) y el navegador. Errores de consola: nunca | | onDiagnostico | — | ({ visible, status, motivo }) => void, ver abajo | | usuario | — | { id, rol, atributos, nombre } — quién es el usuario según tu app, para el diagnóstico; nombre sólo para el saludo, nunca viaja. Ver abajo | | previewToken / onEvento | — | interna: las usa la consola de Supcoflow para el preview; en tu sitio no hacen nada útil |

Quién es el usuario

<ChatDeIntake tenantId="tnt_xxx" projectId="proj_xxx" usuario={{ id: "u_123", rol: "admin", atributos: { plan: "pro" } }} />

Todo opcional. id (hasta 100 caracteres), rol (60) y hasta 8 atributos (claves de 40, valores de 200) viajan con el primer mensaje al asistente y, si se abre un reporte, al reporte: el rol es el dato de diagnóstico más barato que hay (la mitad de los «no me aparece el botón» son permisos). Es declarado, no verificado: no da permisos a nada, es contexto. Lo que se pasa de largo se recorta; lo que no sea id, rol o atributos se descarta.

nombre (hasta 80) aparece en «Hola {nombre} 👋» de la pantalla de inicio y nunca viaja al asistente ni al reporte.

La pantalla de inicio

• Antes del primer mensaje, el panel arranca con «Hola {nombre} 👋» (o «Hola 👋» sin usuario.nombre).
• Debajo, dos arranques: «Reportar un error» y «Tengo una duda de uso».
• El saludo lo manda saludo (o la consola, si no hay código) y cada arranque entra como si el usuario lo hubiera escrito: el primer mensaje de la conversación.

La marca desde la consola

El logo, el título y los colores del chat se editan desde /proyectos/<slug>/sdk en Supcoflow y el widget los aplica solo, antes del primer dibujo. Lo que pases por código (titulo, tema) gana sobre lo guardado en la consola, campo a campo.

Qué pasa cuando algo falla

Al cargar, si el chat del proyecto está apagado, el tope del día se agotó, el origen del sitio no está admitido o el backend no contesta, el widget no se dibuja: quien está del otro lado es un usuario final del producto, y no tiene nada que hacer con «el proyecto tiene el tope agotado». Para saber por qué no aparece, pasá onDiagnostico o mirá la consola en localhost:

| status | motivo | qué hacer | |---|---|---| | 403 | chat_deshabilitado | activar el chat en /proyectos/<slug>/sdk | | 403 | origen_no_admitido | agregar el origen del sitio en esa misma pantalla | | 404 | proyecto_desconocido | revisar tenantId / projectId | | 429 | tope_de_mensajes | esperar: el tope vuelve a abrir solo | | 502 | motor_inalcanzable | es del lado de Supcoflow | | 0 | sin_respuesta | red, CSP o backendUrl mal escrita |

A mitad de conversación, un error se muestra debajo del último mensaje con un botón de reintentar, y lo que el usuario escribió se conserva. onDiagnostico lo recibe también, con el código del error en motivo.

Lo que el widget hace y no hace

• La conversación sobrevive a una recarga de la misma pestaña.
• El asistente escribe con formato (negrita, listas, código, links) y pide la confirmación del reporte con botones.
• El navegador habla sólo con el backend del chat, en un formato propio y chico; el motor de agentes queda del lado del servidor.
• No le da seguimiento del reporte al que reportó. Es a propósito.
• No recolecta errores de consola ni nada que no esté en la tabla de opciones.
• Señalar, capturar y adjuntar son acciones del usuario: el widget no captura nada solo.

Señalar y adjuntar

El usuario final puede señalar el elemento de tu página que le falla, capturar la pantalla y adjuntar una imagen. Eso viaja al reporte (y al agente que lo arregla), nunca al modelo del chat, que sólo recibe una descripción corta («señaló el botón Guardar del formulario»).

Qué se recolecta al señalar, y qué no:

• Sí: la etiqueta, un selector CSS, la ruta en el DOM, el texto visible, los atributos id class name type role href src alt title placeholder for action method y aria-*, dieciséis propiedades de estilo, el texto de los elementos vecinos, y el HTML del elemento acotado a 4 KB.
• No: el valor de ningún input, textarea o select, ningún <script>, ninguna query ni hash de URL; y cualquier atributo o clase con pinta de secreto (access_token, csrf, password…) se reemplaza por [redacted].

La captura la toma el usuario con el diálogo del navegador (getDisplayMedia) y la ve como miniatura antes de que suba; puede quitarla. Algunos navegadores y iOS no soportan getDisplayMedia: ahí sólo queda «Adjuntar imagen», que funciona en todos lados. Las imágenes se re-codifican (WebP o PNG, hasta 1,5 MB) y no conservan metadatos del archivo original. Hasta 4 adjuntos por conversación.

Quien señala ve un resaltado sobre tu página: es un overlay nuestro, a pantalla completa, que se desmonta al elegir o al apretar Esc. El código del selector es de Orca (MIT), trasladado a TypeScript; la licencia va en LICENSES/orca.txt.

Si tu sitio tiene CSP

connect-src tiene que admitir el backendUrl (por defecto https://chat.supcoflow.dev). El widget no carga fuentes ni scripts de terceros. Las miniaturas de las capturas son data: URLs generadas en el navegador: si tu img-src no admite data:, no se ven las miniaturas (la subida funciona igual).

Tamaño y requisitos

Un solo archivo por salida, sin dependencias que instalar. React es opcional (sólo para ChatDeIntake). Sin webfonts. Funciona en navegadores con ES2022 y Shadow DOM.

Licencias

MIT. Ver LICENSES/ por el código de terceros incluido.