Tutorial: prima integrazione

Questo tutorial guida passo passo alla prima integrazione completa con Userbot: invio messaggi via REST, ricezione eventi webhook con verifica HMAC e lettura dello storico conversazione. È il percorso consigliato dopo il Quickstart, quando vuoi capire come REST e webhook lavorano insieme in un flusso realistico.

Tempo stimato: 30–45 minuti.

Cosa costruirai

Al termine avrai un backend partner che:

1. Invia messaggi all’Agente AI Userbot con webhookOnly: true (REST restituisce ack + session)
2. Riceve tutte le risposte via eventi message.added sul webhook registrato in dashboard
3. Verifica l’autenticità di ogni richiesta in ingresso tramite firma HMAC
4. Recupera lo storico messaggi di una sessione per audit o sincronizzazione UI

Non è un esempio toy: segue le stesse best practice che userai in produzione.

Prerequisiti

Assicurati di avere tutto pronto prima di iniziare:

• Access Token — genera un token dalla dashboard
• Secret Key — in dashboard: Integrazioni → API Keys (Supporto partner)
• Server con endpoint HTTPS pubblico (in sviluppo locale puoi usare ngrok o simili per esporre localhost)
• curl o il tuo stack backend preferito (Node.js, Python, ecc.)

Passo 1 — Prepara l’endpoint webhook

Userbot consegna gli eventi tramite HTTP POST al tuo server. Devi quindi esporre un endpoint raggiungibile da internet — Userbot non può chiamare http://localhost.

Crea un endpoint POST, ad esempio https://api.tuodominio.it/webhooks/userbot, che rispetti questi requisiti:

• Risponde con HTTP 200 entro 5 secondi — altrimenti Userbot ritenta e potresti ricevere duplicati
• Accetta body JSON
• Legge gli header x-userbot-signature, x-userbot-timestamp, x-userbot-event-id

Passo 2 — Registra il webhook in Userbot

Con l’endpoint pronto, collegalo alla piattaforma Userbot:

1. Accedi alla dashboard Userbot
2. Configura il webhook URL del tuo endpoint
3. Salva il Webhook Secret mostrato alla creazione — visibile una sola volta, come l’Access Token

Il secret serve per verificare che ogni richiesta in ingresso provenga davvero da Userbot e non sia stata manomessa. Conservalo in un secret manager, non in codice o repository.

Per i dettagli sulla configurazione in piattaforma, consulta anche l’Help Center — Integrazione sistemi esterni.

Passo 3 — Invia il primo messaggio

Invia un messaggio con webhookOnly: true. La REST API restituisce ack e session — le risposte dell’agente arriveranno come message.added sul webhook del passo 2:

$
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, vorrei assistenza",
>
    "profileName": "Mario Rossi",
>
    "isTestChat": true,
>
    "webhookOnly": true
>
  }'

Salva il session dalla risposta. Non usare il body REST per popolare la UI chat — attendi l’evento message.added.

Il profileName viene mostrato nella dashboard e negli eventi webhook, così sai subito con chi stai parlando.

Passo 4 — Verifica la firma HMAC

Quando arriva un evento webhook, non processarlo subito: verifica prima che la richiesta sia autentica. Ogni payload è firmato con HMAC-SHA256 usando il Webhook Secret.

Passi da implementare:

1. Leggi x-userbot-timestamp e x-userbot-signature dagli header
2. Verifica che il timestamp sia entro ±5 minuti (protezione anti-replay)
3. Costruisci la stringa {timestamp}.{raw_body} — usa il body HTTP grezzo, senza normalizzazioni JSON
4. Calcola HMAC-SHA256 con il Webhook Secret
5. Confronta il risultato (hex) con x-userbot-signature usando un confronto timing-safe

Implementazione completa e snippet in più linguaggi: Verifica firma HMAC.

Passo 5 — Gestisci l’evento message.added

Dopo la verifica HMAC, elabora il payload. Ecco un esempio di ciò che riceverai per un nuovo messaggio:

1
{
2
  "event": "message.added",
3
  "eventId": "evt_abc123",
4
  "sessionId": 48291,
5
  "createdAt": 1715500800,
6
  "data": {
7
    "messageId": 1001,
8
    "message": "I tempi di consegna sono 3-5 giorni lavorativi.",
9
    "hbo": "bot",
10
    "userId": 42,
11
    "username": "Mario Rossi"
12
  }
13
}

Nel tuo handler, segui queste pratiche:

• Deduplica per eventId — Userbot ritenta in caso di timeout; lo stesso evento può arrivare più volte
• Associa il messaggio al sessionId nel tuo database per mantenere la UI sincronizzata
• Rispondi con 200 immediatamente — se l’elaborazione è pesante (es. scrittura CRM), falla in modo asincrono dopo aver confermato la ricezione

Passo 6 — Leggi lo storico conversazione

Per audit, replay o sincronizzazione UI puoi recuperare tutti i messaggi di una sessione:

$
curl -X GET "https://api.userbot.ai/v1/conversations/YOUR_SESSION_ID/messages?limit=20&offset=0" \
>
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Usa limit e offset per paginare conversazioni lunghe. Utile anche quando un utente riapre una chat e vuoi mostrare lo storico precedente.

Passo 7 — Aggiorna variabili utente (opzionale)

Puoi passare dati strutturati all’agente aggiornando le variabili della sessione — ad esempio email, piano abbonamento o ID cliente dal tuo CRM:

$
curl -X PATCH https://api.userbot.ai/v1/conversations/YOUR_SESSION_ID/user \
>
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{"email": "mario@esempio.it", "piano": "premium"}'

L’agente può usare queste variabili nelle risposte e nei flussi. Se hai configurato i webhook, riceverai user.variables.updated sul tuo endpoint.

Checklist integrazione completa

Prima di andare in produzione, verifica di aver coperto tutti questi punti:

• Endpoint webhook HTTPS pubblico e risponde 200 entro 5s
• Webhook registrato in dashboard con secret salvato in modo sicuro
• Verifica HMAC implementata su ogni richiesta in ingresso
• Deduplicazione eventi per eventId
• Tutte le risposte in UI da eventi message.added, non dalla risposta REST
• Ogni chiamata REST con webhookOnly: true
• session persistito e riutilizzato tra le chiamate
• Access Token solo lato server (Sicurezza)
• Gestione errori 401/403/429 con retry e backoff (Rate limiting)

Prossimi passi