1. Home
  2. API chatbot IA
Guida Aggiornata a novembre 2026

API chatbot IA: le risposte del tuo assistente dentro il tuo software

Il widget copre il sito. Per un'app, un gestionale o un totem serve l'API REST: il tuo codice invia la domanda e riceve una risposta costruita sui contenuti che hai caricato. In questa guida trovi un esempio in Python, gli endpoint e come gestire più siti.

  • 50 risposte IA al mese gratis
  • Webhook firmati
  • Nessuna carta di credito
In breve

Come si usa l'API chatbot IA di Asyntai?

Carichi i tuoi contenuti una volta sola, poi il tuo backend chiama https://asyntai.com/api/v1/chat/ con la chiave nell'header X-API-Key. Ogni risposta arriva in JSON nel campo response. Ecco i passaggi:

  1. Apri un account gratuito e aggiungi il sito: il crawler legge le pagine.
  2. Attiva Starter, Standard o Pro e crea la chiave nelle impostazioni API.
  3. Invia il campo message dal server e mostra la risposta nella tua interfaccia.

API REST, Make e Zapier o webhook: quale strada scegliere?

Asyntai si collega ad altri sistemi in tre modi. Non si escludono: molti team usano l'API per la chat e i webhook per avvisare il CRM. La tabella aiuta a capire da dove partire.

Make o Zapierscenari senza codice Webhookeventi in uscita API RESTchiamate dal tuo codice
Chi inizia Un trigger in un'altra app, per esempio un messaggio nuovo. Asyntai, quando succede qualcosa in una chat. Il tuo software, quando vuole.
Serve programmare? No, si configura a blocchi. Un endpoint che riceve un POST. Una richiesta HTTP in qualsiasi linguaggio.
Usi tipici Rispondere su canali che hanno un'app in Make o Zapier. Avvisare un CRM o un helpdesk di una richiesta. Chat in app e gestionali, report, gestione dei contenuti.
Cosa puoi fare Inviare un messaggio, leggere lo storico, chiamate libere. Ricevere quattro tipi di evento. Chat, lead, ticket, knowledge base, siti e istruzioni.
Piani Starter, Standard, Pro. Starter, Standard, Pro. Starter, Standard, Pro.

Make o Zapier

Chi inizia
Un trigger in un'altra app, per esempio un messaggio nuovo.
Serve programmare?
No, si configura a blocchi.
Usi tipici
Rispondere su canali che hanno un'app in Make o Zapier.
Cosa puoi fare
Inviare un messaggio, leggere lo storico, chiamate libere.
Piani
Starter, Standard, Pro.

Webhook

Chi inizia
Asyntai, quando succede qualcosa in una chat.
Serve programmare?
Un endpoint che riceve un POST.
Usi tipici
Avvisare un CRM o un helpdesk di una richiesta.
Cosa puoi fare
Ricevere quattro tipi di evento.
Piani
Starter, Standard, Pro.

API REST

Chi inizia
Il tuo software, quando vuole.
Serve programmare?
Una richiesta HTTP in qualsiasi linguaggio.
Usi tipici
Chat in app e gestionali, report, gestione dei contenuti.
Cosa puoi fare
Chat, lead, ticket, knowledge base, siti e istruzioni.
Piani
Starter, Standard, Pro.

Le guide di Make e Zapier spiegano la strada senza codice passo per passo.

Un esempio di richiesta in Python

Il corpo della richiesta è un oggetto JSON. Solo message è obbligatorio; session_id tiene insieme la conversazione e website_id sceglie il sito.

  1. 01

    Contenuti pronti

    Prima di toccare il codice, controlla nella dashboard che il chatbot risponda bene alle domande più comuni.

  2. 02

    Chiave sul server

    Crea la chiave nelle impostazioni API e salvala come variabile d'ambiente, mai nel codice del browser.

  3. 03

    Una sessione per utente

    Usa come session_id un identificativo stabile, per esempio l'ID cliente o l'ID della camera.

  4. 04

    Controlla l'esito

    Se success è true mostra response, altrimenti leggi error e lo stato HTTP.

Python con requests
import os, requests

r = requests.post(
    "https://asyntai.com/api/v1/chat/",
    headers={"X-API-Key": os.environ["ASYNTAI_API_KEY"]},
    json={"message": "Posso portare il cane?", "session_id": "camera_214"},
    timeout=30,
)
data = r.json()
print(data["response"] if data["success"] else data["error"])

In alternativa all'header X-API-Key puoi usare Authorization: Bearer LA_TUA_CHIAVE.

Cosa torna indietro
{
  "success": true,
  "response": "Sì, accettiamo cani di taglia piccola e media con un supplemento di 15 € a notte.",
  "session_id": "camera_214",
  "ai_disclosure": "..."
}

ai_disclosure contiene una frase che dice all'utente che sta parlando con un'IA, nella lingua della risposta: mostrala insieme alla prima risposta. Tutti i dettagli sono nella documentazione dell'API.

Gli endpoint dell'API REST

Tutti partono da https://asyntai.com/api/v1/ e usano la stessa chiave. Le risposte sono sempre JSON con un campo success.

Chat

Invia un messaggio e ricevi la risposta dell'IA.

POST /chat/

Sessioni

Le chat recenti, filtrabili per sito, canale e data.

GET /sessions/

Conversazioni

Tutti i messaggi di una sessione, con i tempi di risposta.

GET /conversations/

Lead

Email e telefoni lasciati dai visitatori in chat.

GET /leads/

Ticket

I ticket aperti dal chatbot, con stato e orari.

GET /tickets/

Knowledge base

Aggiungi testo, URL o fogli di calcolo, leggi ed elimina voci.

/knowledge/

Siti e impostazioni

Crea agenti, controlla lo stato, cambia widget e istruzioni.

/websites/

Webhook

Registra un URL che riceve gli eventi delle chat.

/webhooks/

Per la paginazione di sessioni e ticket si usa il parametro before: ogni chiamata restituisce al massimo 100 elementi, dal più recente.

Da dove arrivano le risposte che ricevi

Non devi mandare il contesto a ogni chiamata. Asyntai cerca nella knowledge base dell'account i passaggi utili alla domanda e scrive la risposta partendo da quelli.

Scansione del sito

Le pagine raggiunte seguendo i link del sito.

Singoli URL

Una pagina alla volta, dalla dashboard o via API.

PDF

Listini, manuali e regolamenti, anche scansionati.

Fogli di calcolo

CSV o Excel: ogni riga diventa una voce.

Testo libero

Informazioni che sul sito non ci sono.

File HTML

Pagine salvate o esportate da un altro sistema.

Video

Le risposte si basano sulla trascrizione.

Real-Time Data Feed

Un URL con dati che cambiano, come prezzi o disponibilità.

Standard e Pro

Tono, argomenti e regole si impostano nelle istruzioni dell'IA e valgono per widget e API allo stesso modo. Ogni fonte è spiegata nella guida alla knowledge base.

Casi d'uso dell'API chatbot

Tre progetti diversi con la stessa chiamata alla base. Cambia solo il punto in cui compare la risposta.

Gestionale di un'officina
Ogni quanti chilometri va fatto il tagliando?
Per le auto a benzina consigliamo il tagliando ogni 15.000 km o una volta l'anno, quello che arriva prima.

Il cliente chiede dall'area riservata. La risposta viene dal listino servizi caricato come foglio Excel.

Totem in un museo
Dov'è la sala con i dipinti del Seicento?
La sala del Seicento è al primo piano, sala 7. Dall'ingresso prendi le scale a destra della biglietteria.

Il totem invia la domanda con un session_id per ogni visita. Fonte: la mappa in PDF.

Bot Telegram del tuo team
Qual è il reso massimo per gli ordini B2B?
Per gli ordini B2B il reso è possibile entro 14 giorni, con il documento di trasporto originale.

Il tuo bot passa il messaggio all'API e rimanda la risposta. Fonte: testo libero con le condizioni.

Gestire più siti e istruzioni tramite API

Agenzie e software house possono configurare i chatbot dei clienti direttamente dal proprio sistema. Sono le stesse operazioni della dashboard, eseguite con una richiesta.

Creare un agente

POST /websites/

Invii il dominio e ottieni l'ID del widget e il codice da inserire nel sito. La scansione e la prima bozza delle istruzioni partono in background. Se il piano non ha più siti liberi, l'API risponde 403.

Controllare lo stato

GET /websites/{id}/

Il campo ready diventa true quando la scansione è finita e le istruzioni sono scritte. Il blocco crawl dice quante pagine sono state lette.

Impostazioni del widget

PATCH /websites/{id}/settings/

Cambi solo i campi che invii, come colore o nome dell'assistente. La lista locked indica quali impostazioni richiedono un piano superiore; se ne mandi una, la richiesta intera viene rifiutata e nulla cambia a metà.

Istruzioni dell'IA

PUT /websites/{id}/instructions/

Sostituisci tutto il testo delle istruzioni. Passa il numero version letto prima: se qualcuno le ha cambiate nel frattempo ricevi 409, se qualcuno le sta modificando nella dashboard ricevi 423. Un testo molto più corto del precedente viene fermato con 400.

Piani e prezzi con accesso API

L'accesso API parte dal piano Starter. Il limite che conta è quello delle risposte IA del mese, condiviso tra widget, canali e API.

Free

0 USD /mese
  • 50 risposte IA al mese
  • 1 sito
  • Prova del chatbot in dashboard

Starter

39 USD /mese
  • 800 risposte IA al mese
  • 2 siti
  • API REST, webhook, Make, Zapier

Standard

139 USD /mese
  • 15.000 risposte IA al mese
  • 3 siti
  • Ticket, escalation, Custom tools

Pro

449 USD /mese
  • 50.000 risposte IA al mese
  • 20 siti
  • Marchio rimosso, SSO

Il confronto completo è nella pagina dei prezzi.

Domande frequenti sull'API chatbot IA

Serve un piano a pagamento per usare l'API?

Sì. L'API REST è inclusa nei piani Starter, Standard e Pro. Con il piano gratuito puoi preparare i contenuti e provare il chatbot nella dashboard, poi passi a un piano a pagamento per generare la chiave.

Qual è l'indirizzo dell'API?

L'URL base è https://asyntai.com/api/v1/ e l'endpoint per la chat è POST https://asyntai.com/api/v1/chat/. Ogni richiesta porta la chiave nell'header X-API-Key oppure in Authorization: Bearer.

Come gestisco tanti utenti nello stesso momento?

Dai a ogni utente un session_id diverso, per esempio l'ID cliente del tuo sistema. Così ogni conversazione ha il suo storico e le domande di un utente non si mescolano con quelle di un altro.

Ho più siti nello stesso account. Quale risponde?

Senza website_id risponde il sito principale dell'account. Per usarne un altro, leggi gli ID con GET /api/v1/websites/ e passa website_id nella richiesta.

Posso mettere la chiave dentro un'app mobile?

No, è meglio di no. Una chiave dentro un'app o una pagina web si può estrarre, e con essa si accede al tuo account. L'app chiama il tuo backend, e il backend chiama Asyntai.

Cosa restituisce l'API in caso di errore?

Un JSON con success a false e un campo error. I codici principali sono 400 per dati mancanti, 401 per una chiave assente o non valida, 403 per un piano senza accesso API, 429 quando le risposte IA del mese sono finite e 503 se il servizio IA non risponde.

Posso ricevere notifiche invece di interrogare l'API?

Sì, con i webhook. Asyntai invia un POST firmato con HMAC-SHA256 al tuo URL per quattro eventi: message.received, conversation.started, escalation.requested e takeover.started.

Le risposte via API contano nel limite del piano?

Sì. Ogni risposta generata tramite API conta come una risposta IA del piano, come quelle del widget sul sito.

Porta il tuo assistente IA dove lavorano i tuoi utenti

Parti gratis con 50 risposte IA al mese, carica i contenuti e verifica le risposte. Poi attiva Starter e collega la tua applicazione.