Concetti chiave
Prima di costruire un’integrazione completa, conviene familiarizzare con i concetti che compaiono in tutta la documentazione: identificatori, consegna delle risposte via webhook, stati conversazione ed eventi. Questa pagina li riassume in un unico posto, con collegamenti alle guide operative nella tab API Reference.
Pensa a questi concetti come al vocabolario condiviso tra la tua applicazione e Userbot: usarli correttamente evita errori comuni come conversazioni senza contesto, webhook non verificati o stati mappati in modo errato.
Identità e autenticazione
Ogni chiamata REST deve identificare chi sta chiamando (Access Token) e quale agente deve rispondere (Secret Key). I due elementi lavorano insieme: il token autorizza l’operazione, la Secret Key indirizza la richiesta all’agente giusto.
Conversazioni
Una conversazione Userbot è identificata da un session ID. Una volta avviata, tutti i messaggi, gli aggiornamenti di stato e gli eventi webhook fanno riferimento a quella sessione.
Il profileName è utile quando integri Userbot in un portale dove l’utente è già autenticato: puoi passare nome e cognome al primo messaggio, così l’operatore (in caso di escalation) vede subito chi sta parlando. Non ha effetto sui messaggi successivi: se serve aggiornare i dati utente, usa le variabili utente.
Ricevere le risposte via webhook
L’Agente AI può generare più messaggi in risposta a un singolo input — ad esempio un messaggio introduttivo seguito da un elenco puntato o da un pulsante. Dopo un’escalation, i messaggi dell’operatore umano devono comparire nella tua UI. Per tutto questo serve un unico modello: webhook in ingresso.
REST invia, webhook consegna
Userbot separa invio e consegna: con la REST invii i messaggi dell’utente e ricevi subito un ack con il session ID; le risposte dell’agente (e gli aggiornamenti di conversazione) le ricevi sul webhook configurato in dashboard — in particolare tramite message.added.
La generazione delle risposte è asincrona e può produrre più messaggi per ogni input. Dopo un’escalation arrivano anche i messaggi dell’operatore, e i cambi di stato sono notificati a parte. La tua UI si aggiorna solo dagli eventi webhook verificati (HMAC), non dal body della risposta REST.
Nelle chiamate REST imposta webhookOnly: true per ricevere subito un ack con il session ID e ottenere tutte le risposte dell’agente via webhook in dashboard. Senza questo parametro, la richiesta REST resta in attesa finché l’agente non ha generato i messaggi di risposta — comportamento sincrono che non copre l’intero flusso (risposte multiple, operatore, badge). Si consiglia di usare sempre webhookOnly: true in produzione.
In produzione registra il webhook sull’agente in dashboard Userbot, in Impostazioni → Webhook.
Non costruire la UI chat leggendo il campo message dalla risposta REST: copre al massimo il primo messaggio e non include risposte aggiuntive, messaggi operatore o aggiornamenti di stato. Vedi Ricevere eventi webhook.
Se vuoi solo vedere i dati che arrivano al webhook senza implementare un endpoint, usa RequestBin per ottenere un URL temporaneo e registralo in dashboard. Utile per esplorare la struttura degli eventi; per la produzione serve un endpoint tuo con verifica HMAC.
Contenuto dei messaggi e badge
Negli eventi message.added, il campo data.message è di solito testo semplice da mostrare all’utente. A volte, però, contiene una stringa JSON al posto del testo: sembra un messaggio normale, ma in realtà descrive elementi più evoluti. Sulla piattaforma Userbot li chiamiamo badge (pulsanti, elenchi, card e simili). Non mostrarli come testo grezzo — interpreta il JSON e renderizzali con i componenti appropriati nella tua UI. Per la struttura completa dei payload vedi Userbot Webhook Events.
Stati della conversazione
Una conversazione può essere gestita dall’agente AI o passata a un operatore umano. Lo stato si aggiorna via REST API e viene notificato anche tramite webhook.
Quando un operatore subentra, l’API REST non restituisce più risposte automatiche dall’agente — ha senso, perché la conversazione è ora in mano a una persona. I messaggi dell’operatore, però, continuano ad arrivare via webhook (message.added con hbo: "operator"), così la tua UI resta sincronizzata.
Negli eventi webhook gli stati usano nomenclatura diversa (agent_assigned, bot_assigned). Mappa correttamente i valori nella tua integrazione — vedi Ricevere eventi webhook.
Eventi webhook
Userbot notifica il tuo server via HTTP POST quando accadono eventi rilevanti. Non serve fare polling: il tuo backend riceve una push ogni volta che qualcosa cambia.
Per l’elenco completo degli eventi — tipi, campi data e payload di esempio — consulta Userbot Webhook Events. Per la configurazione dell’endpoint e l’implementazione dell’handler vedi Ricevere eventi webhook.
Deduplicazione
Ogni evento include un eventId univoco (eventId nel payload, oppure header x-userbot-event-id). Se il tuo server non risponde 200 entro 5 secondi, Userbot ritenta automaticamente la consegna: è una misura di affidabilità, ma significa che lo stesso evento può arrivare più volte. Prima di aggiornare la chat o salvare dati nel tuo sistema, controlla se quell’eventId è già stato elaborato. Se sì, rispondi 200 e non ripetere l’azione — così eviti messaggi duplicati in UI o record doppi (ad esempio nel CRM).
Pipeline e automazioni
Oltre alle conversazioni, Userbot permette di avviare flussi di automazione (pipeline) da sistemi esterni. Utile quando un evento nel tuo ERP, sistema di ticketing o e-commerce deve innescare un’azione Userbot — ad esempio inviare una notifica, aggiornare un record o eseguire un workflow multi-step.
Vedi la sezione Flussi nella REST API per endpoint, parametri e esempi.