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

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

| Concetto                   | Descrizione                                                                                                                         | Approfondimento                       |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| **Secret Key** (`bot_key`) | Chiave dell'agente configurata in **Integrazioni → API Keys**; nelle richieste REST va inserita nel path (`/v1/bots/{bot_key}/...`) | [REST API](/api-reference)            |
| **Access Token**           | Token Bearer generato dalla dashboard Userbot; autentica ogni richiesta REST                                                        | [Autenticazione](/api-autenticazione) |

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

| Concetto        | Descrizione                                                                                                                  | Approfondimento            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| **Session**     | Identificatore della conversazione. Restituito nella risposta REST al primo invio; va riutilizzato per mantenere il contesto | [Quickstart](/quickstart)  |
| **profileName** | Nome visualizzato dell'utente. Ha effetto solo all'avvio di una nuova sessione                                               | [REST API](/api-reference) |
| **isTestChat**  | Se `true`, la conversazione è marcata come test ed esclusa dalle statistiche                                                 | [REST API](/api-reference) |

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](/api-reference).

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

| Parametro REST      | Uso                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| `webhookOnly: true` | Modalità consigliata: ack immediato + `session`, tutte le risposte via webhook in dashboard                |
| `webhookUrl`        | Callback per-request — **solo per test locali** (es. con ngrok). In produzione usa il webhook in dashboard |

In produzione registra il webhook sull'agente in [dashboard Userbot](https://my.userbot.ai), 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](/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](/api-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](/api-reference/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.

| Stato REST (`PATCH`) | Significato                                                                |
| -------------------- | -------------------------------------------------------------------------- |
| `bot`                | La conversazione è gestita dall'Agente AI                                  |
| `escalated`          | La conversazione è passata a un operatore umano (richiede `operatorEmail`) |

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](/api-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](/api-reference/userbot-webhook-events). Per la configurazione dell'endpoint e l'implementazione dell'handler vedi [Ricevere eventi webhook](/api-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.

| Concetto            | Descrizione                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| **Webhook trigger** | Endpoint `POST /webhook/{webhookToken}` per avviare un flusso di automazione da sistemi esterni |
| **jobId**           | Identificativo dell'esecuzione pipeline restituito nella risposta del trigger                   |
| **variables**       | Dati passati al flusso (JSON o multipart con upload file)                                       |

Vedi la sezione **Flussi** nella [REST API](/api-reference/tag/flussi) per endpoint, parametri e esempi.

## Prossimi passi

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

Scenari B2B concreti — come questi concetti si applicano a portali, CRM e automazioni

#### [Panoramica API](/api-overview)

Base URL, flusso di integrazione e indice delle guide tecniche