# Usare l'API

Il bot si usa tramite API REST (FastAPI). Questa guida mostra una conversazione completa.

Avvio

uvicorn main:app --reload

L'API è su http://localhost:8000. Le credenziali dell'amministratore vanno in .env (AUTH_ADMIN_USERNAME, AUTH_ADMIN_PASSWORD): senza, il servizio non parte.

1. Ottieni il token

curl -X POST http://localhost:8000/auth/token \
  -d "username=&password="

La risposta contiene access_token. /auth/refresh lo rinnova senza richiedere di nuovo le credenziali, /auth/me restituisce l'utente corrente.

2. Invia un messaggio

curl -X POST http://localhost:8000/chatbot/message \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"message": "quanto sono 100 euro in dollari"}'

Risposta (campi principali):

{
  "response": "...",
  "session_id": "uuid",
  "intent": "ask_currency_conversion",
  "confidence": 0.93,
  "entities": [],
  "options": null,
  "waiting_for_slot": false
}

3. Continua la conversazione

Passa sempre lo stesso session_id per mantenere il contesto:

{"message": "e in sterline?", "session_id": "uuid"}

Se la sessione è scaduta, il server ne crea una nuova e ne restituisce l'id: usa sempre quello dell'ultima risposta.

Gestire gli slot

Quando waiting_for_slot è true il bot sta aspettando un valore (per esempio la città). Nel tuo client puoi:

• mostrare un modo per annullare, invece di far indovinare lo stato dall'assenza di altri segnali;
• inviare il valore richiesto come normale messaggio.

Se l'utente cambia argomento, il bot esce dalla raccolta da solo (vedi [Slot](/guides/slot)).

Opzioni

Quando il bot attende uno slot con valori predefiniti (options nella regola, oppure options_source per opzioni calcolate da una operation), il campo options contiene le scelte come {value, label}, da mostrare come pulsanti. Quando l'utente ne sceglie una, invia il suo valore come messaggio.

Streaming

POST /chatbot/message/stream risponde in SSE e POST /chatbot/cancel interrompe un turno in corso. L'endpoint è spento di default: avvia il server con COGNITOR_STREAMING_ENABLED=true.

Errori

• 401: token mancante o scaduto, rinnovalo.
• 500: errore interno, controlla i log del server.

Vedi anche la [Documentazione API](/api).