> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.userbot.ai/_mcp/server.

# 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](/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](/api-autenticazione#ottenere-un-access-token)
* **Secret Key** — in dashboard: **Integrazioni → API Keys** ([Supporto partner](/supporto-partner))
* Server con endpoint HTTPS pubblico (in sviluppo locale puoi usare [ngrok](https://ngrok.com/) 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`

In sviluppo locale, esponi il server con un tunnel HTTPS (ngrok, Cloudflare Tunnel, ecc.). Userbot non consegna webhook a URL `http://localhost` o senza certificato valido.

***

## Passo 2 — Registra il webhook in Userbot

Con l'endpoint pronto, collegalo alla piattaforma Userbot:

1. Accedi alla [dashboard Userbot](https://my.userbot.ai)
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](https://help.userbot.ai/integrazione-con-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:

```bash
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](/api-verifica-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:

```json
{
  "event": "message.added",
  "eventId": "evt_abc123",
  "sessionId": 48291,
  "createdAt": 1715500800,
  "data": {
    "messageId": 1001,
    "message": "I tempi di consegna sono 3-5 giorni lavorativi.",
    "hbo": "bot",
    "userId": 42,
    "username": "Mario Rossi"
  }
}
```

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:

```bash
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:

```bash
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](/sicurezza-best-practice))
* [ ] Gestione errori 401/403/429 con retry e backoff ([Rate limiting](/api-rate-limiting))

## Prossimi passi

#### [Casi d'uso](/casi-d-uso)

Pattern avanzati: CRM, escalation, pipeline — come estendere questa base

#### [Codici di errore](/api-codici-errore)

Tabella completa degli status HTTP e come gestirli