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

# Benvenuto

Userbot mette a disposizione dei partner B2B un set di API pensate per collegare agenti AI conversazionali a CRM, ERP, portali clienti e sistemi interni — senza dover replicare la logica conversazionale nel proprio stack.

In pratica, la tua applicazione **invia messaggi** tramite la REST API e **riceve tutte le risposte e gli aggiornamenti** (messaggi bot e operatore, cambi di stato, variabili utente) tramite webhook in ingresso registrati in dashboard. Il modello è bidirezionale: tu controlli il flusso lato partner, Userbot si occupa dell'intelligenza conversazionale.

#### [Inizia con il Quickstart](/quickstart)

Prima integrazione end-to-end — webhook in dashboard, invio REST e ricezione risposte via `message.added`

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

Base URL, flusso REST + webhook e indice delle guide tecniche nella tab API Reference

## Cosa puoi integrare

Le API coprono l'intero ciclo di vita di una conversazione: dall'avvio della chat alla chiusura, passando per l'escalation a un operatore umano e l'automazione di processi back-office.

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

Invia messaggi, leggi lo storico, aggiorna stato e variabili utente, archivia conversazioni — le risposte in UI arrivano via webhook

#### [Webhook in ingresso](/api-ricevere-eventi-webhook)

Ricevi notifiche push quando accadono eventi rilevanti: nuovi messaggi, sessioni create, cambi di stato e aggiornamenti variabili

#### [Pipeline](/api-reference/tag/flussi)

Avvia flussi di automazione Userbot da sistemi esterni (ERP, ticketing, e-commerce) tramite webhook trigger

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

Bearer token, verifica HMAC sui webhook e linee guida per integrazioni enterprise production-ready

## Come funziona l'integrazione

Il flusso tipico alterna chiamate REST (iniziate dal partner) e webhook (inviati da Userbot). Comprenderlo aiuta a progettare correttamente backend e UI.

```mermaid
sequenceDiagram
  participant UI as AppPartner
  participant BE as BackendPartner
  participant API as api.userbot.ai
  participant WH as WebhookPartner
  UI->>BE: Messaggio utente
  BE->>API: POST /v1/bots/{bot_key}/messages (webhookOnly)
  API-->>BE: Ack + session
  API->>WH: message.added (risposte agente)
  WH-->>API: 200 OK entro 5s
  BE-->>UI: Aggiorna chat da webhook
```

1. **Invio messaggio** — il backend partner chiama la REST API con Access Token, Secret Key (`bot_key` nel path). Il messaggio dell'utente viene inoltrato all'Agente AI.
2. **Ack REST** — la risposta HTTP conferma l'accettazione e restituisce il `session` ID. Non usarla per popolare la UI chat.
3. **Risposte via webhook** — tutti i messaggi dell'agente (e, dopo escalation, dell'operatore) arrivano come eventi `message.added` sul webhook registrato in dashboard.
4. **Verifica e conferma** — il server verifica la firma HMAC di ogni webhook e risponde con status **200 entro 5 secondi**.

Per un esempio concreto end-to-end, segui il [Quickstart](/quickstart) o il [Tutorial: prima integrazione](/tutorial-prima-integrazione).

## Prima di iniziare

Per integrare le API serve un account Userbot con almeno un Agente AI configurato. Se non hai ancora accesso, consulta la pagina [Supporto partner](/supporto-partner).

Prima di scrivere codice, assicurati di avere questi elementi a disposizione:

* **Account e Agente AI** — segui la guida [Setup e accesso a Userbot](https://help.userbot.ai/guida-allinizio/setup-e-accesso-a-userbot) nell'Help Center per creare l'account e configurare il primo agente
* **Access Token e Secret Key** — il token si genera dalla dashboard ([Autenticazione](/api-autenticazione)); la Secret Key si trova in **Integrazioni → API Keys** (parametro `bot_key` nel path REST)
* **Webhook in dashboard** — endpoint HTTPS pubblico registrato in piattaforma ([Ricevere eventi webhook](/api-ricevere-eventi-webhook))
* **Base URL** — tutte le chiamate REST vanno inviate a `https://api.userbot.ai` (HTTPS obbligatorio, payload JSON)

## Dove trovare cosa

La documentazione Userbot è organizzata per pubblico e obiettivo. Se cerchi dettagli su endpoint e payload, resta qui; se devi configurare flussi o canali in piattaforma, vai all'Help Center.

| Documentazione                          | Pubblico                 | Link                                         |
| --------------------------------------- | ------------------------ | -------------------------------------------- |
| **developers.userbot.ai** (qui)         | Partner B2B, integratori | API REST, webhook, quickstart, sicurezza     |
| [Help Center](https://help.userbot.ai/) | Utenti piattaforma       | Setup agenti, flussi, canali, knowledge base |
| [userbot.ai](https://userbot.ai)        | Business                 | Panoramica prodotto e casi d'uso             |

## Prossimi passi

Scegli il percorso in base a quanto conosci già Userbot e al tipo di integrazione che vuoi costruire.

#### [Quickstart](/quickstart)

Integrazione completa con webhook — il percorso consigliato per la prima implementazione

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

Session, webhook, stati conversazione e eventi — da leggere prima del go-live

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

Pattern concreti per portali clienti, CRM, escalation e automazioni back-office