Glossario | Userbot | Documentazione per sviluppatori

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, 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. Per la configurazione dell’endpoint e l’implementazione dell’handler vedi 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
Flusso / Workflow	Cos’è un Flusso
Knowledge Base	Tipi di Knowledge Base
AI Agent Builder	Cos’è l’AI Agent Builder

Vedi anche

Concetti chiave

Spiegazione contestuale dei concetti principali con esempi d’uso

Panoramica API

Flusso di integrazione e indice delle guide tecniche

Ricevere eventi webhook

Setup endpoint, handler e riferimento agli eventi