Guide

Autenticazione

Access Token e credenziali
View as Markdown

Tutte le richieste alle API REST richiedono autenticazione tramite un Access Token Bearer. Il token identifica il partner che sta chiamando e autorizza l’accesso alle API associate all’account.

L’header da includere in ogni chiamata è:

1Authorization: Bearer <ACCESS_TOKEN>

L’Access Token si genera in autonomia dalla dashboard Userbot. Non ha scadenza obbligatoria (puoi impostarla opzionalmente), ma va trattato come una password: chi lo possiede può inviare messaggi e accedere alle conversazioni associate all’account.

Tratta l’Access Token come una password: non esporlo in client-side (browser, app mobile) né in repository di codice. Memorizzalo in un secret manager o variabili d’ambiente lato server.

Ottenere un Access Token

La procedura richiede pochi minuti e si fa interamente dalla dashboard, senza coinvolgere il supporto (salvo che la tab non sia visibile — vedi nota sotto).

Per creare un nuovo Access Token Bearer:

  1. Accedi alla dashboard su my.userbot.ai
  2. Clicca sul tuo profilo (menu utente in alto a destra)
  3. Apri Impostazioni account
  4. Seleziona la tab Access Token
  5. Clicca per creare un nuovo token
  6. Inserisci un nome descrittivo (es. “Integrazione CRM produzione”, “Staging webhook test”) — ti aiuterà a identificarlo in futuro
  7. Scegli una data di scadenza oppure Nessuna scadenza se il token è per un’integrazione server-to-server stabile
  8. Conferma con Create token
Modal per creare un nuovo Access Token con campo nome e scadenza
Creazione di un nuovo Access Token: nome e scadenza
  1. Copia la chiave generata e conservala subito in un secret manager — non verrà più mostrata dopo la chiusura del modal
Modal con la chiave generata e pulsante per confermare il salvataggio
La chiave generata è visibile una sola volta

Per motivi di sicurezza la chiave è mostrata una sola volta. Dopo aver cliccato “I have saved the key” o chiuso il modal non sarà più possibile recuperarla: dovrai crearne uno nuovo e aggiornare le integrazioni che lo usavano.

Se la tab Access Token non è visibile nelle impostazioni account, contatta il tuo referente Userbot per l’abilitazione API. L’accesso alle API potrebbe richiedere un piano o un’attivazione manuale.

Secret Key dell’agente

Oltre all’Access Token, le chiamate REST che inviano messaggi richiedono la Secret Key dell’Agente AI da integrare. In dashboard la trovi in Integrazioni → API Keys.

Nelle richieste API la Secret Key compare come parametro di path bot_key — ad esempio POST /v1/bots/{bot_key}/messages/. Copia il valore dalla dashboard e sostituiscilo nel path al posto del placeholder YOUR_BOT_KEY negli esempi di questa documentazione.

La Secret Key identifica quale agente deve gestire la conversazione. Trattala come credenziale sensibile: conservala lato server insieme all’Access Token, non in client-side né in repository pubblici.

Esempio

Una chiamata tipica con Access Token, Secret Key e consegna risposte via webhook:

$curl -X POST https://api.userbot.ai/v1/bots/YOUR_BOT_KEY/messages/ \
>  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "message": "Ciao",
>    "webhookOnly": true
>  }'

La risposta REST restituisce ack e session ID. Le risposte dell’agente arrivano come eventi message.added sul webhook registrato in dashboard — vedi Ricevere eventi webhook. Se il token non è valido, vedi la sezione errori sotto.

Errori di autenticazione

StatusCausaCosa fare
401Token mancante, scaduto o non validoVerifica che l’header Authorization sia presente e corretto; rigenera il token se scaduto
403Token valido ma operazione non consentita per l’accountContatta il tuo referente Userbot per verificare l’accesso alle API

Per la tabella completa degli status HTTP e altri errori comuni, vedi Codici di errore.