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

# Panoramica API

Le API Userbot consentono di integrare conversazioni chatbot con sistemi esterni in modo programmatico: inviare messaggi, gestire sessioni, eseguire pipeline di automazione e ricevere eventi in tempo reale. Sono pensate per partner B2B che vogliono incorporare l'intelligenza conversazionale Userbot nei propri prodotti — CRM, portali, app — mantenendo controllo su UX e flussi di business.

L'integrazione si articola su **due superfici** complementari e obbligatorie: la REST API per inviare messaggi e gestire le sessioni, e i **webhook in dashboard** per ricevere le risposte dell'agente e tutti gli aggiornamenti di conversazione.

## Base URL

Tutte le richieste REST vanno inviate a:

`https://api.userbot.ai`

Le chiamate usano **HTTPS** obbligatorio e payload **JSON** (`Content-Type: application/json`), salvo gli endpoint con upload file che accettano `multipart/form-data`. Non esiste un ambiente sandbox separato: usa `isTestChat: true` per conversazioni di prova senza impattare le statistiche.

## Come funziona l'integrazione

Il flusso di integrazione corretto separa invio e consegna:

1. **Autenticazione** — ogni richiesta REST include un Access Token Bearer nell'header `Authorization`. Il token si genera dalla dashboard ([Autenticazione](/api-autenticazione)).
2. **Invio messaggi (REST)** — il backend partner invia i messaggi utente con `webhookOnly: true`. La risposta REST restituisce ack e `session` ID, non il contenuto chat da mostrare in UI ([REST API](/api-reference)).
3. **Ricezione risposte (webhook)** — registra un endpoint HTTPS in dashboard. Userbot consegna lì tutti i messaggi (`message.added`), i cambi di stato e le variabili aggiornate ([Ricevere eventi webhook](/api-ricevere-eventi-webhook)).

Salva sempre il **session ID** restituito dalla REST API: serve per continuare una conversazione e correlare gli eventi webhook. Aggiorna la UI chat **solo** dagli eventi `message.added`, non dal body della risposta REST.

## Guide

Le guide sotto approfondiscono ogni aspetto dell'integrazione. Parti da [Autenticazione](/api-autenticazione) e [Quickstart](/quickstart) se è la prima volta; usa le altre come riferimento durante lo sviluppo.

#### [Autenticazione](/api-autenticazione)

Access Token, Secret Key e header Authorization — come ottenere e usare le credenziali

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

Setup endpoint, tipi di evento, struttura payload ed esempio server

#### [Verifica firma HMAC](/api-verifica-hmac)

Autenticità e integrità dei webhook in ingresso — obbligatoria in produzione

#### [Rate limiting](/api-rate-limiting)

Limiti di frequenza, header informativi e gestione risposta 429

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

Tabella degli status HTTP e come interpretarli

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

Reference interattiva di tutti gli endpoint con esempi di request e response

## Buone pratiche

Prima di andare in produzione, verifica di aver coperto questi punti:

 **UI chat da webhook** — Popola la chat solo con eventi `message.added` verificati HMAC, non dalla risposta REST

 **Verifica firma HMAC** — Su ogni webhook in ingresso — vedi [Verifica firma HMAC](/api-verifica-hmac)

 **Deduplicazione** — Per `eventId` (e/o `data.messageId` per `message.added`) per evitare elaborazioni duplicate

 **Risposta 200 entro 5 secondi** — Ai webhook; elaborazioni pesanti in modo asincrono dopo la conferma

 **Retry con backoff** — In caso di risposta 429, rispettando `Retry-After` — vedi [Rate limiting](/api-rate-limiting)

 **Access Token solo lato server** — Mai esposto in client-side (browser, app mobile)

Per una checklist completa su credenziali, ambienti e privacy: [Sicurezza e best practice](/sicurezza-best-practice).