Integrazione: riferimento tecnico per sviluppatori

Questo riferimento è rivolto agli sviluppatori che integrano reactive.chat in un sito web, un’app o un backend. Descrive interfacce e flussi così come sono implementati nel codice, con nomi, tipi, valori predefiniti e casi di errore.

La configurazione di aspetto, testi, schermata iniziale, regole, tour, test A/B e personalità dell’IA è descritta in Personalizzazione. L’utilizzo dell’account e del pannello operatori è descritto nel Manuale.

A colpo d’occhio

Your visitors' browser                      reactive.chat                         your server
----------------------                      -------------                         -----------
loader.js  --(trigger)-->   core.<hash>.js  cdn.reactive.chat
   window.ReactiveChat (API, events)
   WebSocket rc.v1  <------------------->   ws.reactive.chat/rc_wss/
   HTTP fallback (SSE/Poll) <----------->   ws.reactive.chat/rc_wss/h/
                                            chat server  --- POST (signed) ---->  customer data endpoint
                                                         --- POST (signed) ---->  webhook receiver
                                            reactive.chat/v1  <--- Bearer -----  REST API / MCP
identify(userHash)  <-------------------------------------- HMAC-SHA256 ------  identity secret

Lato client, incorpori un tag script e, se desidera, controlli il widget tramite window.ReactiveChat. Lato server, firmi l’identità degli utenti che hanno effettuato l’accesso, risponda alle richieste di dati dei clienti se necessario, riceva i webhook e usi l’API REST.

Capitoli

Nozioni di base

• Architettura e flusso – componenti, funzionamento congiunto, versioni e distribuzione
• Avvio rapido – incorporamento, inserimento del dominio, CSP e verifica

Nel browser

• Riferimento del tag script – tutti gli attributi data-rc-* e le fonti di configurazione
• API JavaScript – tutti i comandi di ReactiveChat(…)
• Eventi – on/off ed eventi DOM
• Identificare i visitatori e trasmettere il contesto – identify, userHash, exp, track
• App a pagina singola e cambi di pagina
• Sicurezza e Content Security Policy

Connessione e distribuzione

• Dominio personalizzato e proxy first-party – nginx, Apache, Caddy
• Trasporto: WebSocket, fallback HTTP e riconnessione – protocollo, codici di errore e di chiusura

Sul Suo server

• Endpoint per i dati dei clienti – consultazione e importazione degli ordini
• Webhook – eventi, firma, nuovi tentativi e hook REST
• API server (REST v1) e MCP
• Integrazioni e canali – WhatsApp, Messenger, Instagram, Telegram, SMS, e-mail

Altre possibilità di integrazione

• App mobili – la chat in una WebView
• Smart Answer – risposta IA nella ricerca del Suo sito web

Gestione operativa

• Integrazione della protezione dei dati – consenso, memorizzazione e testo sulla protezione dei dati
• Limiti e quote
• Risoluzione dei problemi e lista di controllo

Altre pagine sull’argomento

• Incorporare il widget – la versione breve
• Dettagli tecnici – misurazioni di dimensioni, accessibilità e contrasto
• Aprire la chat da un link o pulsante proprio
• La scheda promozionale nella chat
• Dati dei clienti nella chat
• Dominio personalizzato (first-party)
• Fallback HTTP
• Inserire automaticamente il testo sulla protezione dei dati

Termini

• Chiave del sito – la chiave pubblica di un progetto (24 caratteri), inclusa nel codice di incorporamento. Non è un segreto.
• Progetto – un sito web o un’app con impostazioni proprie; più progetti formano uno spazio di lavoro.
• Pannello operatori – l’interfaccia in cui il Suo team risponde.
• Utente confermato – un visitatore la cui identità è stata firmata dal Suo server tramite userHash.
• Caricatore / nucleo – il piccolo componente di caricamento loader.js e il componente principale core.<hash>.js caricato successivamente.

Tutte le parti della documentazione a colpo d’occhio: Documentazione.