Integrazione API per chatbot: REST, Zapier e webhook spiegati

Un'API per chatbot è un'interfaccia HTTP che ti permette di inviare messaggi a un chatbot AI e ricevere risposte in modo programmatico — senza usare un widget visuale. Invece di un utente che digita in una bolla di chat, è il tuo codice a inviare una richiesta, ottenere una risposta e farci qualcosa: renderizzare un'interfaccia personalizzata, registrare la risposta, attivare un'azione o instradare il risultato verso un altro sistema.

Questa guida copre cos'è un'API per chatbot, quando usarla al posto di un widget incorporato, i tre principali metodi di connessione (REST, Zapier e webhook) e pattern pratici per costruire integrazioni reali.

Cos'è un'API per chatbot?

Un'API per chatbot espone il tuo chatbot AI addestrato come servizio che qualsiasi codice può chiamare via HTTP. Invii il messaggio dell'utente nel corpo della richiesta e l'API restituisce la risposta del chatbot, attinta da qualunque fonte (contenuti del sito web, documenti, coppie di domande e risposte) tu abbia usato per addestrarlo.

La differenza chiave rispetto a un widget preconfezionato: l'API restituisce dati grezzi. È la tua applicazione a decidere come presentarli. Questo significa che puoi incorporare lo stesso chatbot in un'app mobile, un bot Slack, una dashboard interna e una pipeline di automazione backend — tutti usando la stessa knowledge base addestrata.

La maggior parte delle API per chatbot segue uno schema simile:

1. Autenticati — includi una chiave API nell'header Authorization.
2. Invia un messaggio con POST — invia il testo dell'utente, l'ID del chatbot e, facoltativamente, un ID di conversazione per il contesto multi-turno.
3. Gestisci la risposta — analizza la risposta, eventualmente esegui lo streaming dei token per un effetto in tempo reale, e memorizza il conversationId per il turno successivo.

Per i team che confrontano le opzioni di chatbot prima di scegliere una piattaforma, questa panoramica dei migliori chatbot AI per siti web copre cosa cercare tra i vari strumenti.

Quando usare l'API rispetto al widget

Il widget incorporato copre la maggior parte dei casi d'uso su sito web. L'API è la scelta giusta quando ti serve qualcosa che il widget non può offrire.

Se il tuo caso d'uso rientra nella colonna di destra, l'API è lo strumento giusto. Per tutte le opzioni di incorporamento — widget, componente React, iframe e plugin WordPress — consulta la guida all'integrazione del chatbot.

Metodi di connessione e disponibilità per piano

Ci sono tre modi per collegare il tuo chatbot a sistemi esterni. Servono scopi diversi e sono disponibili su piani diversi.

L'API REST ti dà il massimo controllo. Zapier è più veloce da configurare se non ti serve codice personalizzato. I webhook completano entrambi: ti inviano i dati invece di aspettare che tu vada a recuperarli.

Per un'analisi completa di cosa include ogni piano, consulta la guida ai prezzi e ai costi dei chatbot.

Requisiti dei piani

La fatturazione annuale riduce il prezzo di ogni piano di circa il 20%. I messaggi via API contano sulla tua quota mensile allo stesso modo dei messaggi via widget.

Autenticazione

Ogni richiesta API richiede un token Bearer. Generi le chiavi API dalle impostazioni del workspace nella tua dashboard Agentkit.

Generare una chiave API

1. Apri il tuo workspace Agentkit.
2. Vai su Impostazioni poi Chiavi API.
3. Clicca su Crea chiave API.
4. Dalle un nome descrittivo (ad es. "Slack Bot Production").
5. Copia subito la chiave. Non verrà mostrata di nuovo.

Usare la chiave nelle richieste

Includi la tua chiave API nell'header Authorization:

Authorization: Bearer ak_live_your_api_key_here

Tutte le richieste devono essere inviate su HTTPS. Le richieste senza un token valido restituiscono una risposta 401 Unauthorized.

Best practice per la gestione delle chiavi

• Memorizza le chiavi API nelle variabili d'ambiente, mai nel codice lato client.
• Ruota le chiavi periodicamente, soprattutto dopo cambi nel team.
• Crea chiavi separate per integrazioni separate, così puoi revocarne una senza influire sulle altre.
• Elimina le chiavi che non usi più.

Per i dettagli completi sull'autenticazione, consulta la documentazione sull'autenticazione.

L'endpoint di chat

Il nucleo dell'API è un singolo endpoint che invia un messaggio dell'utente al tuo chatbot e restituisce la risposta dell'AI.

Richiesta

POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer ak_live_your_api_key_here

Corpo della richiesta:

{
  "chatbotId": "your-chatbot-id",
  "message": "What are your shipping options?",
  "conversationId": "optional-conversation-id",
  "visitorId": "optional-visitor-id",
  "metadata": {
    "page": "/products/shoes",
    "userTier": "premium"
  }
}

Risposta

{
  "id": "msg_abc123",
  "conversationId": "conv_xyz789",
  "message": "We offer three shipping options: Standard (5-7 business days, free over $50), Express (2-3 business days, $9.99), and Overnight ($24.99). All orders include tracking.",
  "sources": [
    {
      "title": "Shipping Policy",
      "url": "https://example.com/shipping"
    }
  ],
  "createdAt": "2026-02-22T14:30:00Z"
}

Il conversationId nella risposta è importante. Memorizzalo e ripassalo nelle richieste successive per mantenere il contesto della conversazione. Senza di esso, ogni messaggio avvia una nuova conversazione e il chatbot perde il filo.

Risposte di errore

Per il riferimento completo degli endpoint, consulta la documentazione API.

Risposte in streaming

Per le applicazioni in tempo reale in cui vuoi mostrare la risposta mentre viene generata (l'effetto macchina da scrivere che gli utenti si aspettano da una chat AI), usa i Server-Sent Events (SSE).

Aggiungi il parametro stream: true alla tua richiesta:

{
  "chatbotId": "your-chatbot-id",
  "message": "Explain your return policy",
  "conversationId": "conv_xyz789",
  "stream": true
}

La risposta arriva come uno stream di eventi SSE:

data: {"type": "token", "content": "Our"}
data: {"type": "token", "content": " return"}
data: {"type": "token", "content": " policy"}
data: {"type": "token", "content": " allows"}
...
data: {"type": "sources", "sources": [{"title": "Return Policy", "url": "https://example.com/returns"}]}
data: {"type": "done", "conversationId": "conv_xyz789", "messageId": "msg_def456"}

Gestire lo stream in JavaScript

const response = await fetch('https://api.agentkit.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ak_live_your_api_key_here'
  },
  body: JSON.stringify({
    chatbotId: 'your-chatbot-id',
    message: 'Explain your return policy',
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const data = JSON.parse(line.slice(6));
    if (data.type === 'token') {
      appendToUI(data.content);
    }
  }
}

Lo streaming è consigliato per qualsiasi integrazione rivolta agli utenti. Fa sembrare il chatbot reattivo anche quando genera risposte lunghe.

Webhook

Mentre l'endpoint di chat ti permette di inviare messaggi al chatbot, i webhook permettono al chatbot di inviare dati a te. Quando si verificano eventi specifici, Agentkit invia una richiesta HTTP POST a un URL che configuri tu. I webhook sono disponibili dal piano Hobby in su.

Configurare i webhook

1. Vai su Impostazioni del tuo workspace, poi Webhook.
2. Inserisci l'URL del tuo endpoint (deve essere HTTPS).
3. Seleziona a quali eventi iscriverti.
4. Salva. Agentkit invia una richiesta di verifica per confermare che il tuo endpoint sia raggiungibile.

Eventi disponibili

Payload del webhook

Ogni POST del webhook include un corpo JSON con una struttura coerente:

{
  "event": "lead.captured",
  "timestamp": "2026-02-22T15:45:00Z",
  "chatbotId": "your-chatbot-id",
  "conversationId": "conv_xyz789",
  "data": {
    "name": "Alex Chen",
    "email": "[email protected]",
    "message": "Interested in the enterprise plan"
  },
  "signature": "sha256=abc123..."
}

Verifica sempre il campo signature rispetto al tuo webhook secret, per confermare che la richiesta provenga da Agentkit e non da terze parti.

Comportamento dei retry

Se il tuo endpoint restituisce un codice di stato diverso da 2xx, Agentkit riprova con backoff esponenziale: dopo 1 minuto, 5 minuti, 30 minuti, poi si ferma. Le consegne fallite sono visibili nei log dei webhook nella tua dashboard.

Pattern di integrazione comuni

Pattern 1: bot Slack

Inoltra le domande dei clienti dal chatbot del tuo sito web a un canale Slack, e lascia che il tuo team risponda quando l'AI non riesce a farlo.

1. Crea un'app Slack con i webhook in entrata abilitati.
2. Configura un webhook Agentkit per gli eventi conversation.completed.
3. Nel tuo gestore del webhook, verifica se la conversazione è stata risolta o ha richiesto l'intervento di un operatore.
4. In questo secondo caso, invia con POST un messaggio formattato all'URL del tuo webhook Slack con la trascrizione della conversazione.

Questo dà al tuo team di supporto visibilità senza richiedere che monitorino la dashboard di Agentkit.

Pattern 2: UI di chat personalizzata

Sostituisci il widget predefinito con un'esperienza di chat integrata nella tua applicazione.

1. Costruisci la tua interfaccia di chat con il framework che preferisci.
2. Quando viene inviato un messaggio, chiama l'endpoint di chat con stream: true.
3. Renderizza i token man mano che arrivano per un feedback in tempo reale.
4. Memorizza il conversationId nello stato locale per mantenere il contesto tra i messaggi.

Questo è l'approccio giusto per app mobile, applicazioni desktop o qualsiasi prodotto in cui il widget fluttuante non si adatta al design. Per i team che vogliono restare sul widget ma hanno bisogno di più controllo sul posizionamento, la guida per incorporare un chatbot sul tuo sito web copre tutte e quattro le opzioni di incorporamento.

Pattern 3: automazione backend

Usa il chatbot come livello AI in un flusso di lavoro più ampio, senza alcuna UI di chat coinvolta.

Esempio: elaborazione dei ticket di supporto.

1. Arriva un nuovo ticket nel tuo sistema di ticketing.
2. Il tuo backend invia il contenuto del ticket all'endpoint di chat.
3. Il chatbot genera una risposta suggerita in base alla tua knowledge base addestrata.
4. Il tuo sistema risponde automaticamente (se il livello di confidenza è alto) oppure mette in coda il suggerimento per la revisione umana.

Questo pattern funziona perché il chatbot è addestrato sulla stessa knowledge base che usa il tuo team di supporto. L'API ti dà accesso programmatico a quell'intelligenza. Per saperne di più su cosa puoi usare per addestrare un chatbot — scansioni del sito web, PDF, CSV, coppie di domande e risposte — leggi come addestrare un chatbot.

Pattern 4: pipeline di analytics

Cattura ogni conversazione per l'analisi.

1. Iscriviti agli eventi webhook message.received e message.sent.
2. Il tuo gestore del webhook scrive gli eventi nel tuo data warehouse (BigQuery, Snowflake, ecc.).
3. Costruisci dashboard che mostrano le domande più comuni, i tassi di risoluzione, gli orari di picco e i trend delle conversazioni.

Il campo metadata nell'endpoint di chat ti permette di allegare contesto (URL della pagina, segmento utente, variante del test A/B) che arricchisce i tuoi Analytics.

Limite di frequenza

L'API applica limiti di frequenza per garantire l'affidabilità a tutti gli utenti.

Quando raggiungi il limite, l'API restituisce un codice di stato 429 con un header Retry-After che indica quanti secondi aspettare. Costruisci una logica di retry nella tua integrazione:

async function sendMessage(payload, retries = 3) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
  });

  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return sendMessage(payload, retries - 1);
  }

  return response.json();
}

Considerazioni sulla sicurezza

Quando costruisci integrazioni API, tieni a mente queste pratiche:

• Non esporre mai le chiavi API nel codice lato client. Se stai costruendo una UI di chat personalizzata per una web app, fai passare le richieste attraverso il tuo backend con un proxy.
• Convalida le firme dei webhook. Verifica sempre la firma HMAC prima di elaborare i payload dei webhook.
• Usa le restrizioni di dominio. Nelle impostazioni del tuo chatbot, limita quali domini possono interagire con il tuo chatbot.
• Monitora l'utilizzo. Controlla regolarmente l'utilizzo della tua API nella dashboard per individuare picchi imprevisti che potrebbero indicare una chiave trapelata.
• Applica il principio del privilegio minimo. Se un'integrazione ha bisogno solo di inviare messaggi, non darle una chiave con permessi di amministratore.

Per i team che vogliono capire come le API dei chatbot AI si collegano a ecosistemi di strumenti più ampi, vale la pena approfondire MCP (Model Context Protocol) — uno standard emergente per dare ai modelli AI un accesso strutturato a strumenti e dati esterni.

Come iniziare

Il percorso più rapido da zero a un'integrazione funzionante:

1. Iscriviti per un account Agentkit e crea il tuo primo chatbot.
2. Addestra il chatbot sui tuoi contenuti (leggi come addestrare un chatbot).
3. Passa al piano Hobby ($29.99/mese) per abilitare l'accesso API.
4. Genera una chiave API nelle impostazioni del tuo workspace.
5. Invia la tua prima richiesta di test usando cURL o Postman.
6. Costruisci da lì in poi: UI personalizzata, bot Slack, automazione o qualunque cosa richieda il tuo caso d'uso.

Domande frequenti

Cos'è una chiave API per chatbot?

Una chiave API per chatbot è un token segreto che autentica la tua applicazione quando effettua richieste all'API del chatbot. La generi nelle impostazioni del tuo workspace, la includi nell'header Authorization: Bearer di ogni richiesta e la tratti come una password — la memorizzi nelle variabili d'ambiente, mai nel codice lato client, e la ruoti se sospetti che sia stata esposta. Ogni chiave può essere associata a un'integrazione specifica, così puoi revocarne una senza influire sulle altre.

Esiste un'API per chatbot gratuita?

Il piano Free di Agentkit ($0/mese) non include l'accesso all'API REST — per quello serve il piano Hobby a $29.99/mese. Il piano Free include il widget JS incorporabile, la raccolta lead e le restrizioni di dominio, che coprono la maggior parte dei casi d'uso su sito web senza scrivere codice. Se ti serve un accesso programmatico fin dal primo giorno, il piano Hobby è il punto di ingresso, e puoi testare l'intera piattaforma gratis prima di fare l'upgrade.

Devo saper programmare per usare un'API per chatbot?

Non sempre. Se ti serve l'accesso all'API REST per integrazioni personalizzate, dovrai scrivere codice — oppure usare uno strumento come Postman per testare le chiamate manualmente. Ma se il tuo obiettivo è collegare il chatbot ad altre app senza scrivere codice, l'integrazione Zapier (disponibile dal piano Hobby in su) si collega a oltre 7.000 app tramite un'interfaccia no-code. Per l'incorporamento sul sito web, non serve altro codice oltre a incollare un tag <script>.

Quali modelli AI supporta l'API del chatbot?

Il modello AI sottostante viene configurato per singolo chatbot nella dashboard. Agentkit supporta modelli di tre provider: OpenAI (GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna), Anthropic (Claude Opus 5, Claude Sonnet 5, Claude Haiku 4.5) e Google (Gemini 3.7 Flash, Gemini 3.1 Pro). Il modello predefinito è GPT-5.6 Luna. Le tue chiamate API usano qualunque modello sia selezionato per quel chatbot — non specifichi il modello a livello di chiamata API.

Posso usare l'API del chatbot per incorporare la chat sul mio sito web?

Sì, ma l'incorporamento del widget JS è di solito più semplice per i casi d'uso su sito web. Il widget si carica in modo asincrono tramite un singolo tag <script> e gestisce automaticamente UI, stato della conversazione e streaming. Usa l'API quando ti serve una UI completamente personalizzata, un'integrazione con app mobile o un'automazione backend. Per un confronto diretto di tutte le opzioni di incorporamento, consulta la guida per incorporare un chatbot sul tuo sito web.

Un'API per chatbot trasforma una knowledge base addestrata in un servizio richiamabile — le stesse risposte AI che appaiono nel widget sono disponibili per qualsiasi sistema in grado di fare una richiesta HTTP. Che tu stia costruendo un'interfaccia personalizzata, automatizzando un flusso di supporto o collegando il tuo chatbot a un ecosistema di strumenti più ampio, l'API ti dà il controllo che un widget preconfezionato non può offrire.

Crea il tuo chatbot gratis → Nessuna carta di credito richiesta.