Guida all'integrazione per sviluppatori
Panoramica per gli sviluppatori
WebChatAgent offre tre modi per mettere un chatbot a disposizione dei tuoi utenti. Scegline uno in base al livello di controllo desiderato sull'interfaccia.
| Integrazione | Cosa ottieni | Ideale per |
|---|---|---|
| Widget Embed | Una UI di chat predefinita tramite un solo tag script | Siti web e applicazioni web |
| REST API | Invia un messaggio, ricevi una risposta (richiesta/risposta) | UI personalizzate, app mobili, script server |
| WebSocket API | Flusso di messaggi in tempo reale con digitazione e presenza | Dashboard di chat dal vivo, strumenti per operatori |
| JavaScript SDK | Pacchetto npm tipizzato per le REST e WebSocket API | UI di chat personalizzate in JavaScript o TypeScript |
| Webhook | Nuovi lead e appuntamenti come richiesta JSON firmata al tuo server | Sincronizzazione CRM, automazioni |
Tutte e tre le soluzioni comunicano con lo stesso chatbot, condividono la stessa Base di conoscenza e scalano la stessa quota di messaggi. Puoi combinarle, ad esempio incorporando il widget sul tuo sito e creando una dashboard interna per operatori basata sulle WebSocket API.
Widget Embed (il più veloce)
Aggiungi il chatbot a qualsiasi sito web con un singolo tag script e un elemento HTML personalizzato (<web-chat-agent chatbot-id="...">). Nessun framework, nessun passaggio di compilazione. Tutti i colori, i testi e gli strumenti vengono configurati nella dashboard e applicati automaticamente. Questa è la scelta adatta per il 90% dei siti web.
- Guida al Widget Embed: tag script, elemento personalizzato, tutti gli attributi HTML, CSS personalizzato, modalità Chat integrata e utilizzo con SPA
REST API
Quando hai bisogno di un'interfaccia di chat proprietaria, come un'app mobile, un web component personalizzato o un'automazione backend, chiama direttamente l'endpoint di chat. Invia un message con il tuo chatbotId e ricevi una reply generata dall'IA insieme alle relative origini. Un ID Sessione restituito in un'intestazione di risposta mantiene coerenti le conversazioni con più passaggi.
- Riferimento REST API: endpoint, autenticazione tramite dominio, campi di richiesta/risposta, codici di errore ed esempi di codice in cURL, JavaScript, Python e PHP
JavaScript SDK
Stai creando una UI di chat personalizzata in JavaScript o TypeScript? Il pacchetto npm webchatagent racchiude le REST e WebSocket API: risposte in streaming, Caricamento file, feedback, Moduli per lead e chat dal vivo con il tuo team, con tipi TypeScript completi e senza dipendenze.
- JavaScript SDK: installazione, primo messaggio, streaming, trasferimento a un operatore umano. Pacchetto su npm, codice sorgente su GitHub
WebSocket API
Per la chat dal vivo, dove i messaggi devono arrivare all'istante e vuoi indicatori di digitazione, presenza e traduzione automatica. Lo stesso socket alimenta i widget per i visitatori e la dashboard degli operatori. Usalo per creare una console operatore personalizzata o per gestire la chat dal vivo dal tuo backend.
- Riferimento WebSocket API: connessione, ruoli, eventi inviati e ricevuti ed esempio funzionante di client
Quale dovrei usare?
| Caso d'uso | Consigliato |
|---|---|
| Aggiungere un chatbot a un sito web | Widget Embed |
| Mostrare la chat all'interno del layout della tua pagina | Chat integrata (widget embed) |
| UI di chat personalizzata in JavaScript o TypeScript | JavaScript SDK |
| UI di chat personalizzata o app mobile | REST API |
| Automazione server-to-server (senza UI) | REST API |
| Dashboard di chat dal vivo in tempo reale per operatori umani | WebSocket API |
Consulta Casi d'uso per scenari concreti resi possibili da queste integrazioni.
