Il tuo chatbot Chatbotty risponde già alle domande sul tuo sito web tramite il suo widget. Ma cosa succede se volessi che il tuo chatbot AI vivesse anche altrove — all'interno della tua app mobile, di un portale clienti o di uno strumento interno che il tuo team usa ogni giorno? È proprio a questo che serve un **API**. Questa guida spiega cos'è un'API in termini semplici, come funziona l'API di Chatbotty, cosa puoi costruire con essa e come creare la tua prima chiave API. Non serve una laurea in informatica — solo un'idea chiara di come si incastrano i pezzi. Questo è il primo articolo di una serie. Qui copriamo la visione d'insieme; gli articoli successivi approfondiranno ogni parte dell'API nel dettaglio. ## Cos'è esattamente un'API? API sta per *Application Programming Interface*. Suona tecnico, ma l'idea è semplice: un'API è un modo per due software di comunicare direttamente tra loro, senza che un umano debba cliccare pulsanti nel mezzo. Pensalo come ordinare in un ristorante. Non entri in cucina a cucinare il tuo pasto. Dici al cameriere cosa vuoi, il cameriere passa l'ordine in cucina e il cibo torna al tuo tavolo. Il cameriere è l'API — un messaggero che prende la tua richiesta, la consegna al sistema che fa il lavoro e riporta la risposta. Con Chatbotty, la "cucina" è il tuo chatbot AI e la sua base di conoscenza. L'API è il messaggero con cui parla il tuo software. La tua app invia una domanda, il chatbot trova la risposta e l'API invia quella risposta direttamente alla tua app — tutto in una frazione di secondo. ## Perché collegare il tuo chatbot a un'API? Il widget di chat è perfetto per il tuo sito web. Ma un'API apre tutte le altre possibilità: - **Costruisci un chatbot nella tua app.** Inserisci il tuo assistente AI in un'app mobile o in un'app web personalizzata, con il tuo design. - **Collega il tuo chatbot ad altri strumenti.** Invia risposte a un help desk, a un canale Slack o a un cruscotto interno. - **Automatizza la tua base di conoscenza.** Carica nuovi documenti al tuo chatbot automaticamente ogni volta che le informazioni sul prodotto cambiano. - **Estrai i tuoi report.** Leggi la cronologia delle conversazioni e le analisi nei tuoi sistemi invece di controllare manualmente la dashboard. In breve: il widget è la porta d'ingresso pronta all'uso, e l'API è il mazzo di chiavi che ti permette di costruire le tue porte dove ti servono. ## Cosa puoi fare con l'API di Chatbotty L'API di Chatbotty è organizzata in cinque aree. Troverai esempi di codice pronti da copiare per ciascuna direttamente nella tua dashboard, sotto **API Integration**. - **Chat API** — invia un messaggio al tuo chatbot e ricevi la risposta AI, lo stesso cervello che alimenta il tuo widget. - **Documents API** — carica, elenca e rimuovi i documenti che compongono la base di conoscenza del tuo chatbot. - **Conversations API** — leggi le conversazioni passate e i loro messaggi. - **Analytics API** — estrai statistiche aggregate come il totale delle domande e il tasso di successo. - **Tickets API** — elenca i ticket di supporto, cambia il loro stato e aggiungi note interne. Non preoccuparti ancora dei dettagli. Ognuna di queste aree avrà un articolo dedicato. Per ora, sappi solo che quasi tutto ciò che vedi nella dashboard, puoi anche raggiungerlo tramite l'API. ## Come le chiavi API mantengono sicuro il tuo chatbot Il software non può accedere con email e password come fai tu. Invece, dimostra chi è con una **chiave API** — una lunga stringa segreta di caratteri. Ogni richiesta che la tua app invia include questa chiave così Chatbotty sa che la richiesta arriva davvero da te e a quale chatbot appartiene. La chiave viene inviata in una parte della richiesta chiamata *Authorization header*, come qualcosa chiamato **Bearer token**. Non devi memorizzare questi termini — gli esempi di codice nella tua dashboard li includono già. Basta sostituire il segnaposto `YOUR_API_KEY` con la tua chiave reale e il gioco è fatto. Una chiave è legata a un chatbot specifico. Non devi mai inviare un ID chatbot — Chatbotty capisce quale chatbot intendi dalla chiave stessa. Una chiave API è come una password per il tuo chatbot. Chiunque la possieda può parlare con il tuo chatbot e leggere i suoi dati. Non incollarla mai in codice pubblico, nel front-end di un sito web o in un documento condiviso — conservala sul tuo server sicuro. ## Come creare la tua prima chiave API Creare una chiave richiede circa dieci secondi. Ecco tutto il processo. 1. Apri la tua dashboard e vai su **API Integration** nel menu a sinistra. 2. Trova il chatbot che vuoi collegare. Ogni chatbot ha la sua sezione **API Keys**. 3. Clicca su **Create new API key**. 4. Dai alla chiave un nome che riconoscerai in seguito, come *Sito web di produzione* o *App mobile*. Il nome è solo per te — ti aiuta a ricordare dove viene usata ogni chiave. 5. Clicca su **Create**. La tua nuova chiave appare subito. Copia la tua chiave ora e conservala in un posto sicuro. Per sicurezza, la chiave completa viene mostrata solo una volta. Dopo aver chiuso questa finestra, la dashboard mostra solo i primi caratteri. Se la perdi, elimina la chiave vecchia e creane una nuova. Puoi creare diverse chiavi per ogni chatbot — un modo comodo per dare a ogni app la sua chiave. Puoi disattivare una chiave in qualsiasi momento senza eliminarla, o rimuoverla definitivamente quando non serve più. ## La tua prima richiesta API Una volta che hai una chiave, parlare con il tuo chatbot è una richiesta semplice. Ecco l'esempio più piccolo possibile usando cURL, uno strumento da linea di comando: ```bash curl -X POST "https://www.chatbotty.ai/api/v1/chat" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "Quali sono i tuoi orari di apertura?"}' ``` Il tuo chatbot legge il messaggio, cerca nella sua base di conoscenza e risponde — esattamente come farebbe nel widget. La prima richiesta di chat crea anche una *conversazione*, e puoi passare il suo ID nella richiesta successiva per continuare la conversazione con tutto il contesto. Preferisci JavaScript, Python o Node.js? Ogni esempio nella dashboard è disponibile anche in questi linguaggi, pronto da copiare. ## Chi può usare l'API? L'API di Chatbotty è disponibile nei piani **Evaluation**, **Elite** e **Enterprise**. Se il tuo piano attuale non include ancora l'accesso API, la pagina API Integration ti mostrerà le opzioni di upgrade. Le richieste di chat inviate tramite API contano nel tuo limite mensile di messaggi, proprio come le chat dal widget — le altre aree, come analytics e conversations, non consumano messaggi. ## Pronto per iniziare a costruire? Questo è il quadro completo: un'API permette al tuo software di parlare direttamente con il tuo chatbot, una chiave API mantiene sicura quella connessione e la dashboard ti offre codice funzionante per ogni parte. Apri la pagina API Integration, crea la tua prima chiave e prova una singola richiesta di chat — una volta che vedi il tuo chatbot rispondere tramite l'API, tutto il resto si metterà a posto. Tieniti pronto per i prossimi articoli di questa serie, in cui esploreremo una per una le API Chat, Documents, Conversations, Analytics e Tickets.