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

# Glossario

Questo glossario raccoglie i termini usati nella documentazione per sviluppatori — API REST, webhook, concetti di integrazione. È pensato come riferimento rapido: quando incontri un termine che non ricordi, torna qui.

Per i concetti di prodotto (Agente AI, Flusso, Knowledge Base) consulta anche il [Glossario Help Center](https://help.userbot.ai/introduzione-a-userbot/glossario-dei-termini), che copre la piattaforma Userbot dal lato configurazione e utilizzo.

## Termini API

| Termine                    | Definizione                                                                                                                                                                                                                      |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Access Token**           | Token Bearer che autentica le richieste REST. Generato dalla dashboard Userbot; va conservato lato server e non esposto in client-side.                                                                                          |
| **Secret Key** (`bot_key`) | Chiave dell'agente usata nel path REST (`/v1/bots/{bot_key}/...`). In dashboard si trova in **Integrazioni → API Keys**; nelle chiamate API compare come parametro `bot_key`. Indica quale agente deve gestire la conversazione. |
| **Session**                | Identificatore stringa di una conversazione. Restituito nella risposta REST al primo invio; va riutilizzato per mantenere il contesto tra i messaggi.                                                                            |
| **sessionId**              | Identificatore numerico della sessione, usato negli eventi webhook e in alcuni endpoint pipeline. Corrisponde alla stessa conversazione del `session` stringa.                                                                   |
| **profileName**            | Nome visualizzato dell'utente nella conversazione. Impostabile solo all'avvio di una nuova sessione.                                                                                                                             |
| **isTestChat**             | Flag booleano: se `true`, la conversazione è di test ed esclusa dalle statistiche di produzione.                                                                                                                                 |
| **webhookOnly**            | Modalità consigliata: la REST restituisce ack e `session`; le risposte dell'agente arrivano via evento `message.added` sul webhook in dashboard.                                                                                 |
| **webhookUrl**             | Callback HTTPS per-request — **solo per test locali**. In produzione usa il webhook registrato in dashboard.                                                                                                                     |
| **Webhook Secret**         | Chiave segreta per verificare la firma HMAC dei webhook in ingresso. Mostrata una sola volta alla creazione.                                                                                                                     |
| **eventId**                | Identificatore univoco di un evento webhook, usato per deduplicazione in caso di retry.                                                                                                                                          |
| **HMAC**                   | Hash-based Message Authentication Code. Userbot usa HMAC-SHA256 per firmare i webhook e garantirne autenticità e integrità.                                                                                                      |
| **Pipeline**               | Flusso di automazione Userbot avviabile tramite webhook trigger (`POST /webhook/{webhookToken}`).                                                                                                                                |
| **webhookToken**           | Token nel path dell'endpoint di trigger pipeline. Identifica quale flusso avviare.                                                                                                                                               |
| **jobId**                  | Identificatore dell'esecuzione di una pipeline, restituito nella risposta del trigger. Utile per tracciare lo stato dell'automazione.                                                                                            |
| **variables**              | Coppie chiave/valore passate a una pipeline o aggiornate sull'utente di una sessione. L'agente può usarle nelle risposte.                                                                                                        |
| **escalated**              | Stato conversazione assegnato a un operatore umano (REST API). Dopo l'escalation l'agente non risponde più automaticamente.                                                                                                      |
| **bot**                    | Stato conversazione gestito dall'Agente AI (REST API). Comportamento predefinito.                                                                                                                                                |
| **hbo**                    | Mittente del messaggio negli eventi webhook: `user` (utente finale), `bot` (agente AI), `operator` (operatore umano).                                                                                                            |
| **Rate limiting**          | Limite di frequenza delle richieste API per chiave. Risposta 429 se superato; header `x-ratelimit-*` indicano lo stato del budget.                                                                                               |

## Eventi webhook

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

## Termini di prodotto (Help Center)

Questi termini riguardano la piattaforma Userbot e la configurazione degli agenti — non le API direttamente. Se devi creare flussi, addestrare l'agente o configurare canali, l'Help Center è la risorsa giusta.

| Termine           | Link                                                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| Agente AI         | [Cos'è Userbot](https://help.userbot.ai/introduzione-a-userbot/cose-userbot)                                        |
| Flusso / Workflow | [Cos'è un Flusso](https://help.userbot.ai/automazione-avanzata-e-workflow/cose-un-flusso)                           |
| Knowledge Base    | [Tipi di Knowledge Base](https://help.userbot.ai/addestramento-dellintelligenza-artificiale/tipi-di-knowledge-base) |
| AI Agent Builder  | [Cos'è l'AI Agent Builder](https://help.userbot.ai/automazione-avanzata-e-workflow/cose-lai-agent-builder)          |

## Vedi anche

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

Spiegazione contestuale dei concetti principali con esempi d'uso

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

Flusso di integrazione e indice delle guide tecniche

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

Setup endpoint, handler e riferimento agli eventi