- Home
- API chatbot IA
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
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:
- Apri un account gratuito e aggiungi il sito: il crawler legge le pagine.
- Attiva Starter, Standard o Pro e crea la chiave nelle impostazioni API.
- 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.
- 01
Contenuti pronti
Prima di toccare il codice, controlla nella dashboard che il chatbot risponda bene alle domande più comuni.
- 02
Chiave sul server
Crea la chiave nelle impostazioni API e salvala come variabile d'ambiente, mai nel codice del browser.
- 03
Una sessione per utente
Usa come
session_idun identificativo stabile, per esempio l'ID cliente o l'ID della camera. - 04
Controlla l'esito
Se
successè true mostraresponse, altrimenti leggierrore lo stato HTTP.
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.
{
"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.
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 ProTono, 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.
Il cliente chiede dall'area riservata. La risposta viene dal listino servizi caricato come foglio Excel.
Il totem invia la domanda con un session_id per ogni visita. Fonte: la mappa in PDF.
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.