Quickstart

Registra il webhook in dashboard

Userbot separa invio e consegna: con la REST invii i messaggi dell’utente (con webhookOnly: true) e ricevi subito un ack con il session ID; le risposte dell’agente le ricevi invece sul webhook configurato in dashboard.

La generazione delle risposte è asincrona e può produrre più messaggi per ogni input (testo, elenchi, pulsanti). Dopo un’escalation arrivano anche i messaggi dell’operatore umano, e i cambi di stato della conversazione sono notificati a parte. Un singolo body HTTP della risposta REST non può rappresentare l’intero flusso — al massimo restituisce ack e session, non il contenuto completo da mostrare in chat. Per una UI affidabile aggiorna la chat solo dagli eventi webhook, in particolare message.added.

Per questo il primo passo è registrare il webhook in dashboard:

1. Espone un endpoint POST HTTPS, ad esempio https://api.tuodominio.it/webhooks/userbot
2. Accedi alla dashboard Userbot, apri l’agente da integrare e registra l’URL del webhook in Impostazioni → Webhook
3. Salva il Webhook Secret mostrato alla creazione — visibile una sola volta
4. Implementa la verifica HMAC su ogni richiesta in ingresso

L’endpoint deve rispondere 200 entro 5 secondi. Per i dettagli completi vedi Ricevere eventi webhook.

Invia il primo messaggio

Invia un messaggio con webhookOnly: true. La REST API restituisce subito un ack e il session ID — non il testo da mostrare in chat. Le risposte dell’agente arriveranno come eventi message.added sul webhook del passo 1.

Senza webhookOnly, la richiesta REST resta in attesa finché l’agente non ha generato i messaggi di risposta e li inserisce nel body HTTP — comportamento sincrono che non copre risposte multiple, messaggi operatore o badge. Si consiglia di usare sempre webhookOnly: true in produzione.

Sostituisci YOUR_ACCESS_TOKEN e YOUR_BOT_KEY con le credenziali dalla dashboard.

$
curl -X POST https://api.userbot.ai/v1/bots/YOUR_BOT_KEY/messages/ \
>
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "message": "Ciao, ho bisogno di assistenza",
>
    "profileName": "Mario Rossi",
>
    "isTestChat": true,
>
    "webhookOnly": true
>
  }'

Risposta REST attesa

1
{
2
  "session": "abc123-session-id"
3
}

Con webhookOnly: true la risposta REST non contiene il messaggio dell’agente. Conserva il session — serve per i messaggi successivi e per correlare gli eventi webhook.

Ricevi le risposte via webhook

Quando l’agente risponde, Userbot invia un evento message.added al tuo endpoint. Struttura tipica:

1
{
2
  "event": "message.added",
3
  "eventId": "evt_abc123",
4
  "sessionId": 48291,
5
  "data": {
6
    "messageId": "msg_xyz",
7
    "message": "Ciao! Mi occupo di assistenza clienti automatizzata.",
8
    "hbo": "bot"
9
  }
10
}

Nel tuo handler:

1. Verifica la firma HMAC (Verifica firma HMAC)
2. Deduplica per eventId — ogni evento ha un identificativo univoco (eventId nel payload, oppure header x-userbot-event-id). Se il tuo server non risponde 200 entro 5 secondi, Userbot ritenta automaticamente l’invio: è una misura di affidabilità, ma significa che lo stesso messaggio può arrivare due volte. Prima di aggiornare la chat o salvare dati nel tuo sistema, controlla se quell’eventId l’hai già elaborato. Se sì, rispondi 200 e non ripetere l’azione — così eviti messaggi duplicati in UI o record doppi (ad esempio nel CRM).
3. Aggiorna la UI chat con data.message — nella maggior parte dei casi è testo semplice da mostrare all’utente. A volte, però, quel campo 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 giusti nella tua UI. Per la struttura completa dei payload vedi Userbot Webhook Events.
4. Rispondi con HTTP 200 entro 5 secondi

Il campo hbo indica il mittente: bot (agente AI), user (utente finale), operator (operatore umano dopo escalation).

Continua la conversazione

Invia messaggi successivi con lo stesso session e sempre webhookOnly: true. Le nuove risposte dell’agente arriveranno di nuovo via message.added:

$
curl -X POST https://api.userbot.ai/v1/bots/YOUR_BOT_KEY/messages/ \
>
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "message": "Vorrei informazioni sul mio ordine",
>
    "session": "abc123-session-id",
>
    "webhookOnly": true
>
  }'

L’Agente AI mantiene il contesto — non devi reinviare lo storico messaggi.

Test senza impattare le statistiche

Durante sviluppo e staging, imposta isTestChat: true al primo messaggio di una sessione. La chat apparirà con badge “Test” in dashboard ed è esclusa dalle statistiche di produzione.