POST/api/public/widget/message

Invia un messaggio del visitatore al chatbot e restituisce la sua risposta — l'endpoint centrale del widget di chat.

Inviate `widget_code`, `message`, la `visitor_id` e — dal secondo messaggio in poi — la `session_id` della risposta precedente. Alla prima chiamata di una nuova conversazione, lasciate `session_id` vuoto o impostatelo su `null`. La risposta contiene, nell'oggetto `data`, la `session_id`, il testo di risposta `response` e, se applicabile, pulsanti (`buttons`), suggerimenti di prodotto (`products`) e lo stato della conversazione (`state`). 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 manca `visitor_id`, il server risponde 400 `VISITOR_ID_REQUIRED`. La chiamata non è idempotente: ogni invio crea un altro messaggio del visitatore e un'altra risposta. Bloccate l'input mentre una richiesta è in corso e non ripetetela automaticamente.

Panoramica

Chiamata: POST /api/public/widget/message. Questo endpoint appartiene al gruppo «Widget di chat» dell'API di Zentor App. Richiede un token di embed del widget valido. La chiamata non è idempotente: ogni chiamata riuscita attiva nuovamente l'azione. Parametri obbligatori: widget_code (body), message (body), visitor_id (body). Parametri facoltativi: session_id (body). Casi di errore documentati: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_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: No

Parametri

widget_code(body, string, obbligatorio)— Codice del widget dal vostro codice di incorporamento
message(body, string, obbligatorio)— Testo del messaggio del visitatore
visitor_id(body, string, obbligatorio)— ID visitatore generato dal widget e memorizzato nel browser
session_id(body, string)— ID sessione dalla risposta precedente; vuoto o `null` alla prima chiamata di una nuova conversazione

Richiesta di esempio

{"widget_code":"...","message":"Ciao, cosa può fare Zentor App?","visitor_id":"<UUID o ID generata dal client>"}

Risposta di esempio

{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}

Codici di errore

401 WIDGET_TOKEN_MISSING — L'header `X-Widget-Token` è mancante.
401 WIDGET_TOKEN_INVALID — Il token di incorporamento non corrisponde al codice del widget.
400 VISITOR_ID_REQUIRED — Il campo `visitor_id` è mancante.

Comportamento verificato

Un messaggio valido restituisce 200 con la risposta del chatbot; un token mancante o non valido e una `visitor_id` mancante restituiscono i codici di errore documentati.

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.GET /api/public/widget/historyCarica la cronologia dei messaggi precedente di una conversazione del widget, ad esempio dopo il ricaricamento della pagina.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.

Articoli correlati

← Widget di chat