Inserción del widget

Inserte el widget de chat web de HelpStack en cualquier sitio web con una única etiqueta de script.

Datos rápidos#

El loader obtiene su baseUrl de su propio origen <script src>, por lo que el widget.js servido desde helpstack.eu se comunica automáticamente con HelpStack — no hay nada más que configurar.

Fragmento de inserción#

<script src="https://helpstack.eu/widget.js?id=CHANNEL_ID" async></script>

CHANNEL_ID es el id de su canal WEBSITE_CHAT. El loader se inicializa automáticamente desde el parámetro de consulta ?id= — no se requiere JavaScript adicional.

Cómo obtener el CHANNEL_ID#

En el panel de control, vaya a Settings → Channels, abra (o cree) un canal Website Chat y copie su id usando el botón de copia que aparece junto al canal. Ese id es el que se pasa como ?id=CHANNEL_ID.

Cómo funciona el loader#

1. El script lee su propio <script src> para determinar:
   • baseUrl — el origen del script (p. ej. https://helpstack.eu)
   • channelId — el parámetro de consulta ?id=
2. Inyecta una burbuja de chat flotante y un <iframe> que apunta a:

   {baseUrl}/widget/{channelId}?visitorId={visitorId}
   

3. El iframe abre una conexión Socket.IO para mensajería en tiempo real, con un fallback HTTP cuando WebSocket no está disponible.

Identidad del visitante#

El loader genera un id de visitante persistente almacenado en localStorage:

El mismo visitorId se reutiliza en cargas de página y sesiones en ese navegador, de modo que un visitante que regresa se reconecta a su conversación existente. Limpiar localStorage (o usar un navegador/dispositivo diferente) genera un nuevo visitante y un nuevo hilo de conversación.

API programática#

El loader expone un objeto global window.ChatWidget:

window.ChatWidget.init('CHANNEL_ID'); // inicializar manualmente (si no se usa ?id=)
window.ChatWidget.open();             // abrir el panel de chat
window.ChatWidget.close();            // cerrar el panel de chat
window.ChatWidget.toggle();           // alternar entre abierto/cerrado

También está disponible un asistente de cola de comandos para la forma diferida usada en el comentario del fragmento:

window.chat('init', 'CHANNEL_ID');

No existe una API de registro de herramientas en el cliente. El loader no expone ningún registerTool() ni manejador de herramientas del lado del cliente. Las herramientas de agente del lado del cliente están mediadas por el servidor a través del socket del iframe (consulte Herramientas de agente personalizadas), no se registran desde el JavaScript de su página.

Configuración de apariencia#

La apariencia se configura en el panel de control, no mediante el fragmento de inserción. El widget la obtiene del servidor (GET /api/widget/[channelId]/config) y la aplica mediante variables CSS. Campos configurables verificados:

Endpoints públicos del widget#

Todos los endpoints son públicos (sin autenticación) y están limitados por IP/visitante.

Respuesta de subida (POST /api/widget/[channelId]/upload):

{
  "storagePath": "...",
  "publicUrl": "...",
  "fileName": "...",
  "fileSize": 12345,
  "contentType": "image/png",
  "width": 800,
  "height": 600
}

width y height solo están presentes para imágenes.

Fallback de mensajes (POST /api/widget/message) — cuerpo:

{
  "channelId": "CHANNEL_ID",
  "visitorId": "visitor_<uuid>",
  "content": "Hello, I need help",
  "visitorInfo": {
    "userAgent": "...",
    "currentUrl": "https://example.com/pricing",
    "referrer": "https://google.com"
  }
}

visitorInfo es opcional. El canal debe ser de tipo WEBSITE_CHAT o la solicitud se rechaza. En caso de éxito, el campo data del envoltorio de respuesta contiene { messageId, conversationId, createdAt }.

Eventos en tiempo real (Socket.IO)#

El iframe se comunica con el servidor a través de Socket.IO.

Widget → servidor

Servidor → widget

Lista de dominios permitidos#

Un canal puede restringir qué orígenes pueden cargar el widget. Cuando se configura una lista y el origen solicitante no está en ella, el servidor responde con 403. Configure la lista en la configuración del canal en el panel de control. Déjela vacía para permitir cualquier origen.

Página de ejemplo mínima#

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>HelpStack Widget Demo</title>
  </head>
  <body>
    <h1>My website</h1>
    <button onclick="window.ChatWidget.open()">Need help?</button>

    <!-- HelpStack widget -->
    <script
      src="https://helpstack.eu/widget.js?id=CHANNEL_ID"
      async
    ></script>
  </body>
</html>

Relacionado#

• Referencia de la API
• Herramientas de agente personalizadas
• Guía de canales
• Glosario