> 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.

# Quickstart

Questa guida ti accompagna alla **prima integrazione corretta** con Userbot: invii messaggi via REST e ricevi **tutte le risposte dell'agente** via webhook `message.added` registrato in dashboard. È il modello da usare in produzione.

Al termine avrai un backend che invia messaggi con `webhookOnly: true`, salva il `session` ID e aggiorna la UI chat dagli eventi webhook verificati — non dalla risposta REST.

## Prerequisiti

Prima di iniziare, prepara:

* **Access Token** Bearer — [genera un token dalla dashboard](/api-autenticazione#ottenere-un-access-token)
* **Secret Key** dell'Agente AI — in dashboard: **Integrazioni → API Keys** (parametro `bot_key` nel path REST)
* **Endpoint HTTPS pubblico** per i webhook — in sviluppo locale usa un tunnel ([ngrok](https://ngrok.com/), Cloudflare Tunnel, ecc.)
* Un client HTTP e un handler webhook (`curl`, Node.js, Python, ecc.)

Esegui tutte le chiamate REST **dal backend**. Non esporre mai l'Access Token in client-side (browser, app mobile).

#### 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](https://my.userbot.ai), 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](/api-verifica-hmac) su ogni richiesta in ingresso

L'endpoint deve rispondere **200 entro 5 secondi**. Per i dettagli completi vedi [Ricevere eventi webhook](/api-ricevere-eventi-webhook).

Se vuoi solo **vedere i dati** che arrivano al webhook senza implementare un endpoint, usa [RequestBin](https://requestbin.net/) 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.

#### 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

```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, ho bisogno di assistenza",
    "profileName": "Mario Rossi",
    "isTestChat": true,
    "webhookOnly": true
  }'
```

#### Node.js

```javascript
const response = await fetch(
  "https://api.userbot.ai/v1/bots/YOUR_BOT_KEY/messages/",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "Ciao, ho bisogno di assistenza",
      profileName: "Mario Rossi",
      isTestChat: true,
      webhookOnly: true,
    }),
  }
);
const data = await response.json();
console.log(data.session); // salva per i messaggi successivi
```

#### Python

```python
import requests

response = requests.post(
    "https://api.userbot.ai/v1/bots/YOUR_BOT_KEY/messages/",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "message": "Ciao, ho bisogno di assistenza",
        "profileName": "Mario Rossi",
        "isTestChat": True,
        "webhookOnly": True,
    },
)
print(response.json()["session"])
```

### Risposta REST attesa

```json
{
  "session": "abc123-session-id"
}
```

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:

```json
{
  "event": "message.added",
  "eventId": "evt_abc123",
  "sessionId": 48291,
  "data": {
    "messageId": "msg_xyz",
    "message": "Ciao! Mi occupo di assistenza clienti automatizzata.",
    "hbo": "bot"
  }
}
```

Nel tuo handler:

1. Verifica la firma HMAC ([Verifica firma HMAC](/api-verifica-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](/api-reference/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`:

```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": "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.

Il parametro `webhookUrl` nel body REST è pensato **solo per test locali** (callback per-request). In produzione usa sempre il webhook registrato in dashboard.

## Prossimi passi

Hai un'integrazione con il modello corretto: REST per inviare, webhook per ricevere.

#### [Concetti chiave](/concetti-chiave)

Session, webhook, stati conversazione ed eventi — approfondisci prima del go-live

#### [Ricevere eventi webhook](/api-ricevere-eventi-webhook)

Setup completo, tipi di evento e handler di produzione

#### [Tutorial completo](/tutorial-prima-integrazione)

HMAC, deduplicazione, storico messaggi e variabili utente

#### [REST API](/api-reference)

Reference interattiva di tutti gli endpoint