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

# Casi d'uso

Questi scenari illustrano come i partner collegano Userbot a CRM, portali clienti e sistemi interni nella pratica. Ogni caso descrive il **problema di business**, il **flusso consigliato** e le **API coinvolte** — così puoi identificare rapidamente il pattern più vicino al tuo progetto e partire da lì.

Non sono mutuamente esclusivi: molte integrazioni reali combinano più pattern (es. assistente embedded + notifiche CRM + handoff operatore).

## 1. Assistente embedded in portale cliente

**Problema:** il partner vuole offrire assistenza AI direttamente nel portale web o nell'app del cliente, con un'interfaccia chat completamente custom — senza usare il widget Userbot predefinito.

**Approccio:** la UI del portale invia i messaggi dell'utente al backend partner, che chiama la REST API con `webhookOnly: true`. Le risposte dell'agente arrivano via `message.added` sul webhook in dashboard e la UI si aggiorna di conseguenza.

**Flusso:**

```mermaid
sequenceDiagram
  participant UI as PortaleCliente
  participant BE as BackendPartner
  participant API as api.userbot.ai
  participant WH as WebhookPartner
  UI->>BE: Messaggio utente
  BE->>API: POST /messages (webhookOnly)
  API-->>BE: Ack + session
  API->>WH: message.added
  WH-->>API: 200 OK
  BE-->>UI: Aggiorna chat da webhook
```

| Fase                | API / azione                                               |
| ------------------- | ---------------------------------------------------------- |
| Avvio chat          | `POST /v1/bots/{bot_key}/messages` con `webhookOnly: true` |
| Messaggi successivi | Stessa endpoint con `session` + `webhookOnly: true`        |
| Risposte in UI      | Evento `message.added` sul webhook in dashboard            |
| Storico             | `GET /v1/conversations/{session_id}/messages`              |

**Quando sceglierlo:** hai già un portale o un'app con autenticazione utente e vuoi integrare la chat come componente nativo, mantenendo pieno controllo su UX e branding.

**Guide:** [Quickstart](/quickstart) · [REST API](/api-reference)

***

## 2. Notifiche CRM su nuova conversazione

**Problema:** ogni volta che un utente avvia una conversazione con l'agente, il team commerciale o l'assistenza deve sapere subito — e il CRM deve avere un record aggiornato con i dati raccolti durante la chat.

**Approccio:** configura un webhook in ingresso sul backend partner. Userbot invia eventi push quando accadono cose rilevanti; il tuo codice crea o aggiorna i record CRM di conseguenza.

**Flusso:**

1. L'utente invia il primo messaggio via API o canale Userbot (web chat, WhatsApp, ecc.)
2. Userbot emette `conversation.created` sul webhook del partner
3. Il backend partner crea il record CRM e salva il `sessionId`
4. Eventuali variabili utente (`email`, `nome`, `piano`) arrivano con `user.variables.created` / `user.variables.updated`

| Evento                   | Azione partner                              |
| ------------------------ | ------------------------------------------- |
| `conversation.created`   | Crea record CRM, associa `sessionId`        |
| `user.variables.updated` | Aggiorna campi CRM con `name` / `value`     |
| `message.added`          | Log messaggi per audit o sentiment analysis |

**Quando sceglierlo:** la conversazione AI è un touchpoint commerciale o di supporto e vuoi che CRM e team interni restino allineati senza intervento manuale.

**Guide:** [Ricevere eventi webhook](/api-ricevere-eventi-webhook) · [Verifica firma HMAC](/api-verifica-hmac)

***

## 3. Handoff a operatore umano

**Problema:** l'AI risolve la maggior parte dei casi, ma quando serve un intervento umano la transizione deve essere fluida — senza perdere il contesto e senza che l'utente debba ripetere tutto.

**Approccio:** la logica partner (o l'agente stesso) rileva la necessità di escalation e chiama l'endpoint REST per cambiare stato. Da quel momento i messaggi dell'operatore arrivano via webhook e la tua UI li mostra come messaggi umani.

**Flusso:**

1. L'agente o la logica partner rileva la necessità di escalation
2. Il backend chiama `PATCH /v1/conversations/{session_id}` con `state: "escalated"` e `operatorEmail`
3. Userbot notifica `conversation.state_changed` con il nuovo stato
4. L'operatore risponde dalla dashboard Userbot; i messaggi arrivano via `message.added`

Dopo l'escalation l'API REST non restituisce più risposte automatiche dall'agente. Continua a ricevere aggiornamenti via webhook — inclusi i messaggi dell'operatore.

| API / evento                           | Uso                                 |
| -------------------------------------- | ----------------------------------- |
| `PATCH .../conversations/{session_id}` | Scala a operatore                   |
| `conversation.state_changed`           | Aggiorna UI partner / notifica team |
| `message.added`                        | Sincronizza messaggi operatore      |

**Quando sceglierlo:** hai un team di operatori che gestisce casi complessi e vuoi un handoff trasparente tra AI e umano.

**Guide:** [Concetti chiave](/concetti-chiave) · [REST API](/api-reference)

***

## 4. Automazione back-office con pipeline

**Problema:** un evento nel sistema partner — nuovo ordine, ticket IT, richiesta di preventivo — deve innescare automaticamente un flusso Userbot (notifica, aggiornamento record, workflow multi-step).

**Approccio:** il sistema partner chiama l'endpoint webhook trigger con i dati dell'evento. Userbot esegue la pipeline configurata in piattaforma e restituisce un `jobId` per tracciare l'esecuzione.

**Flusso:**

1. Il sistema partner (ERP, ticketing) rileva l'evento
2. Chiama `POST /webhook/{webhookToken}` con `variables` e opzionalmente file allegati
3. Userbot esegue la pipeline e restituisce `jobId`
4. Il risultato è visibile nella dashboard Userbot

```bash
curl -X POST https://api.userbot.ai/webhook/TOKEN \
  -F 'variables={"orderId":"ORD-2025-001"}' \
  -F 'files=@documento.pdf'
```

**Quando sceglierlo:** vuoi automatizzare processi che non passano necessariamente da una chat utente — ad esempio elaborare un ordine, generare un documento o inviare una sequenza di notifiche.

**Guide:** [REST API — Flussi](/api-reference/tag/flussi)

***

## 5. Archivio e analytics esterni

**Problema:** le conversazioni concluse devono finire in un data warehouse, in un sistema di reporting o in un archivio a norma — con tutto lo storico messaggi e i metadati associati.

**Approccio:** usa l'evento `conversation.archived` come trigger per l'export, poi recupera lo storico completo via REST API con paginazione.

**Flusso:**

1. Alla chiusura, Userbot emette `conversation.archived`
2. Il partner recupera lo storico con `GET /v1/conversations/{session_id}/messages` (paginazione con `limit` / `offset`)
3. I dati vengono normalizzati e caricati nel sistema analytics

| API / evento                                     | Uso                         |
| ------------------------------------------------ | --------------------------- |
| `conversation.archived`                          | Trigger export              |
| `GET .../messages`                               | Storico completo paginato   |
| `PATCH .../conversations/{session_id}` (archive) | Archiviazione programmatica |

**Quando sceglierlo:** hai requisiti di compliance, audit o business intelligence che richiedono l'export sistematico delle conversazioni.

**Guide:** [REST API](/api-reference) · [Tutorial](/tutorial-prima-integrazione)

***

## Scegli il punto di partenza

#### [Quickstart](/quickstart)

Integrazione completa con webhook in dashboard — ideale per il caso 1

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

REST + webhook + HMAC end-to-end — copre i casi 2 e 3

#### [Sicurezza](/sicurezza-best-practice)

Best practice per integrazioni production-ready

#### [Supporto partner](/supporto-partner)

Richiedi credenziali e assistenza tecnica