GET/api/public/widget/history
Carica la cronologia dei messaggi precedente di una conversazione del widget, ad esempio dopo il ricaricamento della pagina.
Passate `widget_code`, `session_id` e `visitor_id` come parametri di query. La risposta contiene, nell'oggetto `data`, l'elenco `messages` con `role` (`user` o `assistant`), `text` e `created_at` nell'ordine della conversazione. La chiamata è di sola lettura e idempotente. L'header `X-Widget-Token` con il token di incorporamento e `widget_code` sono obbligatori. Se il token manca, il server risponde 401 `WIDGET_TOKEN_MISSING`; se non è valido, 401 `WIDGET_TOKEN_INVALID`; le chiamate da domini non autorizzati ricevono 403 `WIDGET_ORIGIN_DENIED`, un widget disattivato 404 `WIDGET_DISABLED`. Se mancano `session_id` o `visitor_id`, il server risponde 400 `PARAMS_REQUIRED`. Se la sessione non è più conosciuta, avviate una nuova conversazione.
Panoramica
Chiamata: GET /api/public/widget/history. Questo endpoint appartiene al gruppo «Widget di chat» dell'API di Zentor App. Richiede un token di embed del widget valido. La chiamata è idempotente: chiamate ripetute con gli stessi dati restituiscono lo stesso risultato. Parametri obbligatori: widget_code (query), session_id (query), visitor_id (query). Casi di errore documentati: 400 PARAMS_REQUIRED. La risposta di esempio riportata di seguito mostra la struttura di una risposta riuscita in formato JSON.
Autenticazione e sicurezza
Token di incorporamento del widget (header X-Widget-Token) + elenco delle origini consentite
Idempotente: Sì
Parametri
widget_code(query, string, obbligatorio)— Codice del widget dal vostro codice di incorporamentosession_id(query, string, obbligatorio)— ID sessione della conversazione dalla risposta di `message`visitor_id(query, string, obbligatorio)— ID visitatore generato dal widget e memorizzato nel browserRisposta di esempio
{"ok":true,"data":{"messages":[{"role":"user","text":"Ciao...","created_at":"..."},{"role":"assistant","text":"...","created_at":"..."}]}}Codici di errore
400 PARAMS_REQUIRED — `session_id` o `visitor_id` è mancante.Comportamento verificato
Una sessione esistente restituisce 200 con la cronologia dei messaggi; parametri mancanti restituiscono 400 `PARAMS_REQUIRED`.
Widget di chat
GET /api/public/widget/healthSemplice controllo di disponibilità del servizio widget.GET /api/public/widget/config/:widget_codeRestituisce la configurazione pubblica di un widget (nome visualizzato, messaggio di benvenuto, design, lingua, funzione vocale) per l'inizializzazione nel browser.POST /api/public/widget/messageInvia un messaggio del visitatore al chatbot e restituisce la sua risposta — l'endpoint centrale del widget di chat.POST /api/public/widget/pollRecupera i messaggi ricevuti dopo un determinato momento — ad esempio la risposta di un collaboratore che ha preso in carico la conversazione.POST /api/public/widget/ratingSalva la valutazione del visitatore su una conversazione (utile o non utile).POST /api/public/widget/trackRegistra un evento anonimo di utilizzo del widget (ad es. «widget aperto») per le analisi nella dashboard.POST /api/public/widget/voice-transcribeConvertisce una registrazione vocale del visitatore in testo (input vocale), se la funzione vocale è attivata per il widget.POST /api/public/widget/voice-speakConvertisce il testo in voce parlata (output vocale nel widget), se la funzione vocale è attivata.