Riferimento API
Crea integrazioni personalizzate con l'API REST di Asyntai
Piano a pagamento richiesto: L'accesso API è disponibile nei piani Starter, Standard e Pro. Visualizza i prezzi
Panoramica
L'API di Asyntai ti consente di integrare il supporto clienti basato sull'intelligenza artificiale in qualsiasi applicazione. Invia messaggi e ricevi risposte intelligenti addestrate sui contenuti del tuo sito web e sulla knowledge base.
Autenticazione
Tutte le richieste API richiedono l'autenticazione tramite la tua chiave API. Puoi ottenere la tua chiave API dalla pagina Impostazioni API.
Includi la tua chiave API nelle richieste utilizzando uno di questi metodi:
- Header Authorization (consigliato):
Authorization: Bearer YOUR_API_KEY - Header X-API-Key:
X-API-Key: YOUR_API_KEY
Mantieni segreta la tua chiave API. Chiunque abbia la tua chiave può accedere al tuo account tramite l'API. Non esporla mai nel codice lato client.
URL di base
https://asyntai.com/api/v1/
Endpoint
POST /chat/
Invia un messaggio e ricevi una risposta generata dall'IA.
Corpo della richiesta
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
message |
string | Sì | Il messaggio dell'utente da inviare all'IA |
session_id |
string | No | Identificativo univoco per la conversazione. Usa lo stesso session_id per mantenere la cronologia della conversazione. |
website_id |
integer | No | ID sito web specifico. Se non fornito, utilizza il tuo sito web principale. |
Risposta
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}
Esempio (cURL)
curl -X POST https://asyntai.com/api/v1/chat/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "What are your business hours?", "session_id": "user_123"}'
Esempio (Python)
import requests
response = requests.post(
"https://asyntai.com/api/v1/chat/",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"message": "What are your business hours?",
"session_id": "user_123"
}
)
data = response.json()
print(data["response"])
Esempio (JavaScript)
const response = await fetch("https://asyntai.com/api/v1/chat/", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
message: "What are your business hours?",
session_id: "user_123"
})
});
const data = await response.json();
console.log(data.response);
GET /websites/
Elenca tutti i siti web associati al tuo account.
Risposta
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}
Esempio (cURL)
curl https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY"
GET /conversations/
Recupera la cronologia della conversazione per una sessione specifica.
Parametri di query
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
session_id |
string | Sì | L'ID della sessione di cui recuperare la cronologia |
limit |
integer | No | Numero di messaggi da restituire (predefinito: 50, max: 100) |
Risposta
{
"success": true,
"session_id": "user_123",
"messages": [
{
"role": "user",
"content": "What are your business hours?",
"timestamp": "2024-01-15T10:30:00Z"
},
{
"role": "assistant",
"content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"timestamp": "2024-01-15T10:30:01Z"
}
]
}
Esempio (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
Elenca le tue sessioni di chat recenti. Usalo per scoprire gli ID delle sessioni, che puoi poi passare a /conversations/ per recuperare la cronologia completa dei messaggi.
Parametri di query
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
limit |
integer | No | Numero di sessioni recenti da restituire (predefinito: 20, max: 100) |
website_id |
string | No | Filtra le sessioni per un ID sito web specifico |
source |
string | No | Filtra per origine della sessione: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier |
Risposta
{
"success": true,
"sessions": [
{
"session_id": "session_abc123def",
"source": "widget",
"message_count": 5,
"first_message": "What are your business hours?",
"first_message_at": "2024-01-15T10:30:00Z",
"last_message_at": "2024-01-15T10:35:00Z",
"website_domain": "example.com"
}
]
}
Esempio (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
Recupera i lead raccolti — indirizzi email e numeri di telefono inviati dai visitatori durante le conversazioni in chat.
Parametri di query
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
limit |
integer | No | Numero di lead da restituire (predefinito: 50, max: 100) |
website_id |
string | No | Filtra i lead per un ID sito web specifico |
Risposta
{
"success": true,
"leads": [
{
"session_id": "session_abc123def",
"email": "visitor@example.com",
"phone": "+1234567890",
"page_url": "https://example.com/pricing",
"started_at": "2024-01-15T10:30:00Z"
}
]
}
| Campo | Tipo | Descrizione |
|---|---|---|
session_id |
string | L'ID della sessione di chat. Passalo a /conversations/ per vedere la cronologia completa della chat. |
email |
stringa o null | Indirizzo email fornito dal visitatore, o null se non raccolto |
phone |
stringa o null | Numero di telefono fornito dal visitatore, o null se non raccolto |
page_url |
stringa o null | L'URL della pagina in cui il visitatore stava chattando |
started_at |
string | Timestamp ISO 8601 dell'inizio della sessione di chat |
Esempio (cURL)
curl "https://asyntai.com/api/v1/leads/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Esempio (Python)
import requests
response = requests.get(
"https://asyntai.com/api/v1/leads/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"limit": 20}
)
leads = response.json()["leads"]
for lead in leads:
print(f"{lead['email'] or ''} | {lead['phone'] or ''}")
GET /account/
Ottieni le informazioni del tuo account e le statistiche di utilizzo.
Risposta
{
"success": true,
"account": {
"email": "you@example.com",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
Esempio (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
Più siti web? Gli endpoint della knowledge base utilizzano per impostazione predefinita il tuo sito web principale. Se hai più siti web, passa website_id per selezionarne uno specifico. Puoi trovare gli ID dei tuoi siti web utilizzando GET /websites/.
Limiti di caricamento giornalieri: I caricamenti nella knowledge base (testo, URL, fogli di calcolo) sono soggetti a un limite giornaliero di caratteri in base al tuo piano. Questo si applica al contenuto totale caricato su tutti gli endpoint della knowledge base al giorno.
| Piano | Caratteri/giorno |
|---|---|
| Starter | 100.000 |
| Standard | 500.000 |
| Pro | 2.000.000 |
GET /knowledge/
Elenca le voci della tua knowledge base. Queste sono le fonti di contenuto che il tuo chatbot IA utilizza per rispondere alle domande.
Parametri di query
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
limit |
integer | No | Numero di voci da restituire (predefinito: 50, massimo: 100) |
website_id |
string | No | Filtra per ID sito web (predefinito: il tuo sito web principale) |
Risposta
{
"success": true,
"entries": [
{
"id": "abc-123-def",
"type": "text",
"title": "Business Hours",
"description": "Manual text content (150 words)",
"created_at": "2024-01-15T10:30:00Z"
},
{
"id": "ghi-456-jkl",
"type": "url",
"title": "About Us - Example",
"description": "Content from https://example.com/about",
"created_at": "2024-01-14T09:00:00Z"
}
]
}
Esempio (cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /knowledge/text/
Aggiungi contenuto testuale personalizzato alla tua knowledge base. L'IA lo utilizzerà per rispondere alle domande dei visitatori.
Corpo della richiesta
{
"title": "Return Policy",
"content": "We offer a 30-day return policy on all items. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
"website_id": "123"
}
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
title |
string | Sì | Un titolo per questa voce della knowledge base |
content |
string | Sì | Il contenuto testuale (minimo 10 caratteri) |
website_id |
string | No | Sito web di destinazione (predefinito: il tuo sito web principale) |
Risposta
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}
Esempio (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/text/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Return Policy", "content": "We offer a 30-day return policy..."}'
POST /knowledge/url/
Aggiungi una pagina web alla tua knowledge base. Il contenuto verrà recuperato ed estratto automaticamente.
Corpo della richiesta
{
"url": "https://example.com/faq",
"website_id": "123"
}
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
url |
string | Sì | L'URL da cui recuperare il contenuto |
website_id |
string | No | Sito web di destinazione (predefinito: il tuo sito web principale) |
Risposta
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}
Esempio (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/url/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/faq"}'
POST /knowledge/spreadsheet/
Carica un foglio di calcolo CSV o Excel (.xlsx) nella tua knowledge base. Ogni riga diventa una voce separata, ideale per cataloghi prodotti, elenchi FAQ, tabelle prezzi e directory.
Richiesta
Invia come multipart/form-data (caricamento file), non JSON.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
file |
file | Sì | Un file .csv o .xlsx. La prima riga deve contenere le intestazioni delle colonne. Righe massime per caricamento: Starter 500, Standard 2.000, Pro 10.000. Le righe in eccesso vengono troncate. |
website_id |
string | No | Sito web di destinazione (predefinito: il tuo sito web principale) |
Risposta
{
"success": true,
"id": "abc-123-def",
"title": "products.csv",
"rows_processed": 15,
"chunks_created": 15
}
Esempio (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@products.csv"
DELETE /knowledge/{id}/
Elimina una voce della knowledge base. L'id può essere trovato nella risposta di GET /knowledge/.
Risposta
{
"success": true,
"message": "Knowledge base entry deleted"
}
Esempio (cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Suggerimento: Puoi anche gestire i webhook dalla Impostazioni API pagina senza scrivere codice.
GET /webhooks/
Elenca i tuoi webhook registrati.
Risposta
{
"success": true,
"webhooks": [
{
"id": "abc-123-def",
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"is_active": true,
"created_at": "2024-01-15T10:30:00Z"
}
]
}
Esempio (cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /webhooks/
Registra un nuovo webhook per ricevere notifiche sugli eventi in tempo reale.
Eventi disponibili
| Evento | Descrizione |
|---|---|
message.received |
Un visitatore ha inviato un messaggio e ha ricevuto una risposta |
conversation.started |
Una nuova sessione di chat è stata avviata |
escalation.requested |
L'IA ha attivato un'escalation verso un agente umano |
takeover.started |
Un agente umano ha preso il controllo di una sessione di chat |
Corpo della richiesta
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
url |
string | Sì | L'URL HTTPS per ricevere le richieste POST del webhook |
events |
array | Sì | Elenco degli eventi a cui iscriversi (vedi tabella sopra) |
website_id |
string | No | Sito web di destinazione (predefinito: il tuo sito web principale) |
Risposta
{
"success": true,
"webhook": {
"id": "abc-123-def",
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"secret": "whsec_abc123...",
"created_at": "2024-01-15T10:30:00Z"
}
}
Verifica dei webhook: Ogni webhook include un secret (mostrato solo alla creazione). Ogni POST al tuo URL include un X-Webhook-Signature header — un HMAC-SHA256 del corpo della richiesta firmato con il tuo segreto.
Esempio (cURL)
curl -X POST "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/webhook", "events": ["message.received"]}'
DELETE /webhooks/{id}/
Elimina un webhook. L'id può essere trovato nella risposta di GET /webhooks/.
Risposta
{
"success": true,
"message": "Webhook deleted"
}
Esempio (cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Risposte di errore
Tutte le risposte di errore seguono questo formato:
{
"success": false,
"error": "Error message describing what went wrong"
}
| Codice di stato | Descrizione |
|---|---|
400 |
Bad Request - Parametri non validi o campi obbligatori mancanti |
401 |
Unauthorized - Chiave API non valida o mancante |
429 |
Too Many Requests - Limite di messaggi raggiunto per il tuo piano |
503 |
Service Unavailable - Servizio IA temporaneamente non disponibile |
Limiti di frequenza
L'utilizzo dell'API è limitato dal tuo piano di abbonamento:
- Free: 100 messaggi/mese
- Starter ($39/mese): 2.500 messaggi/mese
- Standard ($139/mese): 15.000 messaggi/mese
- Pro ($449/mese): 50.000 messaggi/mese
Hai bisogno di aiuto?
Se hai domande o riscontri problemi, contattaci a hello@asyntai.com.