SDK de Chatbot para JavaScript y TypeScript (npm)

JavaScript SDK

El paquete webchatagent es el cliente oficial de JavaScript y TypeScript para la REST API y la WebSocket API. Utilícelo cuando el Widget predeterminado no se ajuste a sus necesidades y desee su propia interfaz de chat: su propio diseño, una aplicación en React o Vue, un entorno nativo o una integración del lado del servidor. Se comunica con el mismo Chatbot, con el mismo Conocimiento, Herramientas y Configuración que el Widget.

• Funciones con tipos definidos para todo lo que hace el Widget: respuestas, streaming, preguntas de seguimiento sugeridas, fuentes, Carga de archivos, Comentarios, Formularios para clientes potenciales, transferencia a humanos y Chat en vivo
• Sin dependencias, tipos estrictos de TypeScript, se ejecuta en navegadores, Node.js 22.12+, Bun y Deno
• Código abierto bajo la licencia MIT: github.com/WebChatAgent/webchatagent-js

Instalar

npm install webchatagent

Necesita su ID del chatbot: en el Panel abra su Chatbot, luego Acciones del chatbot → Copiar ID del chatbot.

Primer mensaje

import { WebChatAgent } from 'webchatagent'

const chat = new WebChatAgent({ chatbotId: 'YOUR-CHATBOT-ID', storage: localStorage })

const reply = await chat.send('What are your opening hours?')
console.log(reply.text) // the answer as Markdown

storage: localStorage mantiene la conversación entre recargas de página. Cada send() posterior continúa la misma conversación.

En el Navegador, la API solo responde a páginas incluidas en los Sitios web permitidos de su Chatbot, en caso de haber configurado alguno. localhost siempre funciona para desarrollo.

Respuestas en streaming

for await (const event of chat.stream('Which plan fits a small shop?')) {
  if (event.type === 'text') bubble.innerHTML = render(event.text) // full answer so far
  if (event.type === 'done') showSuggestions(event.reply.suggestions)
}

event.text ya viene limpio, por lo que nunca aparecen enlaces a medio escribir o formatos incompletos. Las respuestas están en Markdown: procéselas con una biblioteca de Markdown y limpie el HTML (por ejemplo, con DOMPurify).

Qué cubre el SDK

getConfig().features le indica cuáles de estas funciones están disponibles para el Chatbot, de modo que su interfaz solo muestre lo que funciona.

Transferencia a humanos

Cuando el bot transfiere la conversación a su equipo, o el Visitante solicita una persona, la respuesta se devuelve con mode: 'human'. Abra el Chat en vivo y los mensajes del miembro del equipo llegarán en tiempo real:

if (reply.mode === 'human') {
  const live = chat.liveChat()
  live.on('message', (message) => showMessage(message))
  live.on('ended', () => backToBot())
  await live.send('Hello, I need help with order 1234.')
}

Su equipo responde en el Panel dentro de Chat en vivo, exactamente igual que con el Widget.

Lo que debe mostrar

Con una interfaz propia, tres tareas que el Widget realiza automáticamente pasan a ser su responsabilidad:

1. Aviso "Powered by": si config.branding.required es true, muestre config.branding.text enlazado a config.branding.url.
2. Etiqueta de IA: marque las respuestas con aiGenerated: true como generadas por IA.
3. Aviso de privacidad: muestre config.widget.privacyPolicyHtml.

Referencia completa

El README en GitHub contiene la referencia completa de la API, códigos de error, límites, ejemplos para React, Vue/Nuxt, JavaScript puro y Node.js, así como una sección para asistentes de codificación con IA como Claude Code, Cursor o Copilot. Dispone de una página de chat completa sin frameworks en examples/browser.html.