SDK Chatbot JavaScript e TypeScript (npm)

SDK JavaScript

Il pacchetto webchatagent è il client ufficiale JavaScript e TypeScript per la REST API e la WebSocket API. Usalo quando il Widget predefinito non è adatto e desideri un'interfaccia di chat personalizzata: un design su misura, un'applicazione React o Vue, una shell nativa o un'integrazione lato server. Comunica con lo stesso Chatbot, condividendone le stesse Conoscenze, gli stessi Strumenti e le stesse Impostazioni del Widget.

• Funzioni tipizzate per tutte le operazioni svolte dal Widget: risposte, streaming, domande di approfondimento suggerite, fonti, Caricamento file, feedback, Moduli per i lead, trasferimento a un operatore umano e Chat dal vivo
• Nessuna dipendenza, tipi TypeScript rigorosi, compatibile con browser, Node.js 22.12+, Bun e Deno
• Open source con licenza MIT: github.com/WebChatAgent/webchatagent-js

Installazione

npm install webchatagent

È necessario l'ID del chatbot: nella dashboard apri il tuo Chatbot, quindi seleziona Azioni del chatbot → Copia l’ID del chatbot.

Primo messaggio

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 conversazione attiva tra i caricamenti di pagina. Ogni successiva chiamata a send() prosegue la stessa conversazione.

Nel browser, l'API risponde solo alle pagine incluse nell'elenco Siti web autorizzati del tuo Chatbot, se ne hai configurati. localhost funziona sempre per le attività di sviluppo.

Risposte in 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 viene ripulito in automatico, evitando che vengano mostrati link o elementi di formattazione incompleti. Le risposte sono in formato Markdown: visualizzale tramite una libreria Markdown ed esegui la sanitizzazione dell'HTML (ad esempio con DOMPurify).

Funzionalità coperte dall'SDK

getConfig().features indica quali tra queste opzioni risultano disponibili per il Chatbot, permettendo all'interfaccia utente di mostrare solo gli elementi supportati.

Trasferimento a un operatore umano

Quando il bot trasferisce la conversazione al team, o il Visitatore richiede una persona, la risposta restituita include mode: 'human'. Apri la Chat dal vivo e i messaggi del membro del team arriveranno in tempo reale:

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.')
}

Il team risponde dalla dashboard all'interno della sezione Chat dal vivo, esattamente come avviene con il Widget.

Elementi da mostrare obbligatoriamente

Quando utilizzi un'interfaccia personalizzata, tre aspetti gestiti in automatico dal Widget diventano di tua responsabilità:

1. Dicitura "Powered by": se config.branding.required ha valore true, mostra config.branding.text con collegamento a config.branding.url.
2. Etichetta IA: contrassegna le risposte con aiGenerated: true come generate dall'intelligenza artificiale.
3. Informativa sulla privacy: mostra config.widget.privacyPolicyHtml.

Riferimento completo

Il README su GitHub contiene il riferimento completo per l'API, i codici di errore, i limiti, esempi di implementazione per React, Vue/Nuxt, JavaScript nativo e Node.js, oltre a una sezione dedicata agli assistenti di codifica IA quali Claude Code, Cursor o Copilot. Una pagina di chat completa priva di framework è disponibile in examples/browser.html.