Riferimento REST API del Chatbot
REST API
Invia un messaggio al tuo chatbot e ricevi una risposta generata dall'IA tramite semplice HTTP. Usalo per creare una chat UI personalizzata, un'app mobile o un'automazione backend. Ogni endpoint è servito dalla stessa origine dello script del widget (https://webchatagent.com).
Usi JavaScript o TypeScript? L'SDK JavaScript (
npm install webchatagent) incapsula questi endpoint con funzioni tipizzate, streaming e live chat.
Come funziona una conversazione
- Esegui una POST con il
messagedell'utente e il tuochatbotIdverso/api/chat. - Leggi il campo
replydal corpo JSON. Leggi l'header di rispostaX-Chat-Session-Id: quello è il tuo ID sessione. - Per il messaggio successivo, invia lo stesso ID sessione nell'header di richiesta
X-Chat-Session-Id. Il server ora dispone del contesto della conversazione: cronologia dei messaggi, contesto di conoscenza basato sulle origini (Retrieval-Augmented Generation, RAG) e stato della live chat. - Ripeti. Ometti l'header ogni volta che desideri avviare una nuova conversazione.
Il server tiene traccia della cronologia per sessione, quindi invii sempre e solo l'ultimo messaggio, mai la trascrizione completa.
Autenticazione
L'API utilizza l'autenticazione basata sul dominio: non è presente alcuna chiave API. Ogni richiesta viene verificata rispetto ai Domini consentiti configurati per il chatbot utilizzando l'header Origin/Referer della richiesta. Una richiesta proveniente da un dominio non consentito riceve un errore 403.
Per i chatbot AI Team Wiki con accesso protetto, invia anche l'header X-Wiki-Auth con il token di autenticazione del wiki (il valore è wiki_auth_<subdomain>). Senza questo token, i wiki protetti restituiscono 403.
Inviare un messaggio
POST https://webchatagent.com/api/chat
Header
| Header | Obbligatorio | Descrizione |
|---|---|---|
Content-Type | Sì | Deve essere application/json. |
X-Chat-Session-Id | No | ID sessione (un UUID) per la continuità della conversazione. Omettilo alla prima richiesta; l'header di risposta ne restituisce uno nuovo. Puoi anche creare autonomamente un UUID casuale. Qualsiasi valore diverso da un UUID viene sostituito con una nuova sessione. |
Accept | No | text/event-stream per ricevere la risposta come stream (vedi Streaming). |
Accept-Language | No | Lingua preferita per la risposta, ad es. de. |
Corpo Richiesta
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
message | string | Sì | Il messaggio dell'utente. Massimo 700 caratteri. Non può essere vuoto. |
chatbotId | string (UUID) | Sì | L'ID del tuo chatbot, reperibile nelle impostazioni del chatbot. |
pageUrl | string | No | L'URL completo della pagina in cui si trova il visitatore (window.location.href). Utilizzato per il recupero contestuale alla pagina; convalidato rispetto ai tuoi domini consentiti. |
contextData | object | No | Contesto chiave-valore semplice sulla sessione del visitatore (massimo 20 chiavi, chiavi di 64 caratteri, valori stringa/numero/booleano di 500 caratteri). Iniettato nel prompt dell'IA solo per questa richiesta, non viene mai memorizzato come record autonomo; l'IA tratta i valori come dati, non come istruzioni, e può usarli negli argomenti di tool e connettori API. Vedi Dati di contesto della sessione. |
Esempio di richiesta
{
"message": "What are your business hours?",
"chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Risposta
L'ID sessione viene restituito nell'header di risposta X-Chat-Session-Id, non nel corpo.
| Campo | Tipo | Descrizione |
|---|---|---|
reply | string | La risposta in formato Markdown. Può terminare con un commento HTML nascosto <!-- SUGGESTED_BUTTONS: [{"label": "...", "text": "..."}] --> contenente domande di follow-up suggerite: mostra label su un pulsante, invia text al clic e rimuovi il commento prima del rendering. |
sources | array | Origini su cui è stata basata la risposta (vedi sotto). Vuoto se non ne è stata usata nessuna. |
mode | string | Modalità di conversazione: bot (l'IA sta rispondendo) o human (un operatore umano ha preso il controllo). Presente quando pertinente. |
status | string | Stato della live chat: waiting, open o closed. Presente solo quando la live chat è attiva per la sessione. |
aiGenerated | boolean | true quando l'IA ha scritto la risposta. Assente mentre un operatore umano gestisce la conversazione. |
conversationTooLong | boolean | La conversazione ha raggiunto il limite di lunghezza. Avvia una nuova sessione. |
Quando un operatore umano ha preso il controllo (mode: "human", status: "open"), il campo reply potrebbe essere vuoto, poiché l'operatore risponde separatamente. Mentre un passaggio di consegne è in stato waiting, la risposta è un breve avviso come "A team member will join shortly."
Array delle origini
Ogni oggetto sorgente:
| Campo | Tipo | Descrizione |
|---|---|---|
type | string | web (una pagina web), product (dati di prodotto strutturati) o fileSource (un documento dall'archivio file connesso). |
source | string | Per web: l'URL della pagina. Per product: l'identificatore del prodotto. Per fileSource: l'ID del documento. |
data | object | Solo per product. Contiene id, dataType, format, data e sourceUrl. |
Esempio di risposta
{
"reply": "Our business hours are Monday to Friday, 9 AM to 5 PM CET.",
"sources": [
{
"type": "web",
"source": "https://example.com/contact"
}
],
"mode": "bot"
}
Streaming
Invia Accept: text/event-stream per ricevere la risposta mentre viene generata. Se il chatbot ha lo streaming abilitato, la risposta è un flusso di Server-Sent Events, ciascuno composto da una singola riga data: con un oggetto JSON, separati da una riga vuota:
data: {"type":"token","data":"Our business hours "}
data: {"type":"token","data":"are Monday to Friday."}
data: {"type":"done","reply":"Our business hours are Monday to Friday.","sources":[],"conversationTooLong":false,"aiGenerated":true}
type | Campi | Significato |
|---|---|---|
token | data | Frammento successivo della risposta. Aggiungilo. Il testo può contenere Markdown incompleto e l'inizio del commento dei suggerimenti. |
tool_call | name | Il bot sta utilizzando un tool, ad es. una ricerca di prodotti. |
error | data | Un problema. Di solito segue un done; se lo stream termina senza done, tratta data come errore. |
done | stessi campi della risposta JSON | La risposta finale. Sostituisci il testo ricevuto in streaming con reply. |
Il server risponde con semplice JSON anziché con uno stream quando lo streaming è disattivato per il chatbot, quando un operatore umano gestisce la conversazione e in caso di errori. Verifica il Content-Type della risposta. Chiudere la connessione interrompe la generazione.
Cronologia chat
Recupera i messaggi archiviati per una sessione (ad esempio per ripristinare una conversazione dopo un ricaricamento della pagina). La cronologia antecedente a 30 giorni viene rimossa per conformità al GDPR; una sessione scaduta restituisce 410.
GET https://webchatagent.com/api/chat/history
Parametri di query
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
chatbotId | string (UUID) | Sì | L'ID del tuo chatbot. |
sessionId | string (UUID) | Sì | La sessione di cui desideri la cronologia. |
Risposta
messages è ordinato dal più vecchio al più recente. sender è bot o user (è un valore visualizzato, non il ruolo non elaborato). role è il ruolo sottostante user / assistant / system, e isAgent è true quando un messaggio di tipo assistant proviene da un operatore umano anziché dall'IA.
{
"messages": [
{
"id": 123,
"sender": "user",
"role": "user",
"isAgent": false,
"text": "What are your hours?",
"createdAt": "2025-01-15T10:30:00Z"
},
{
"id": 124,
"sender": "bot",
"role": "assistant",
"isAgent": false,
"text": "Our hours are Monday to Friday, 9 AM to 5 PM.",
"sources": [{ "type": "web", "source": "https://example.com/contact" }],
"createdAt": "2025-01-15T10:30:01Z"
}
]
}
sources è presente solo quando un messaggio ne contiene.
Informazioni sulla sessione
Ottieni il conteggio dei messaggi e l'ultima attività per le sessioni note a questo browser. Per evitare la diffusione delle chat di altri visitatori, devi passare gli ID sessione già in tuo possesso (ad es. dal local storage). Le sessioni senza alcuna attività negli ultimi 30 giorni non vengono restituite.
GET https://webchatagent.com/api/chat/sessions
Parametri di query
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
chatbotId | string (UUID) | Sì | L'ID del tuo chatbot. |
sessionIds | string | Sì | UUID di sessione separati da virgola (massimo 5; quelli in eccesso vengono ignorati). |
Risposta
{
"sessions": [
{
"sessionId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"messageCount": 12,
"lastActivity": "2025-01-15T10:35:00Z"
}
]
}
Reset Session History
Cancella il contesto di conversazione in memoria per una sessione, in modo che il messaggio successivo riavvii l'IA da zero (senza passaggi precedenti). Questa operazione non elimina i messaggi memorizzati, in quanto conversation_messages sono dati aziendali e rimangono nel database (e in /api/chat/history).
DELETE https://webchatagent.com/api/chat/session
Headers
| Header | Required | Description |
|---|---|---|
X-Chat-Session-Id | Sì | La sessione di cui cancellare la cronologia in memoria. |
Response
{ "success": true, "message": "Chat session cleared." }
Error Handling
La maggior parte degli errori provenienti da /api/chat restituisce la stessa struttura di una risposta normale: un messaggio HTML intuitivo in reply e un array sources vuoto. Il codice di stato HTTP indica il tipo di errore effettivo.
| Status | Meaning |
|---|---|
400 | Corpo non valido, campo mancante, messaggio vuoto o messaggio superiore a 700 caratteri. |
403 | Dominio non consentito, autenticazione wiki non riuscita o applicazione di una restrizione del piano. |
404 | Chatbot non trovato. |
429 | Limite di richieste raggiunto o quota mensile di messaggi esaurita. |
502 | Il provider IA (LLM) ha restituito un errore. |
Error Response Body
{
"reply": "<p>I'm getting a lot of requests right now. Please try again in a few moments.</p>",
"sources": []
}
Le richieste non valide (400), il superamento del limite di frequenza (429) e gli indirizzi IP bloccati (403) restituiscono invece un corpo diverso: { "error": true, "statusCode": 429, "message": "..." }. Esegui prima una diramazione in base al codice di stato HTTP, quindi mostra reply o message all'utente.
Rate Limiting
| Scope | Limit |
|---|---|
| Per sessione | 10 richieste al minuto |
| Per indirizzo IP | 15 richieste al minuto |
| Per sessione e per indirizzo IP | almeno 1 secondo tra due richieste |
Il superamento di uno qualsiasi di questi limiti restituisce 429. Separatamente, anche il raggiungimento della quota mensile di messaggi del piano restituisce 429 (con un messaggio di temporanea indisponibilità).
Code Examples
cURL
# Send a message (capture the session id from the response header)
curl -i -X POST https://webchatagent.com/api/chat \
-H "Content-Type: application/json" \
-d '{
"message": "What products do you offer?",
"chatbotId": "YOUR_CHATBOT_ID"
}'
# Continue the conversation (reuse the session id from above)
curl -X POST https://webchatagent.com/api/chat \
-H "Content-Type: application/json" \
-H "X-Chat-Session-Id: SESSION_ID_FROM_FIRST_RESPONSE" \
-d '{
"message": "Tell me more about the premium plan",
"chatbotId": "YOUR_CHATBOT_ID"
}'
JavaScript / TypeScript
async function chat(message, chatbotId, sessionId = null) {
const headers = { 'Content-Type': 'application/json' };
if (sessionId) headers['X-Chat-Session-Id'] = sessionId;
const response = await fetch('https://webchatagent.com/api/chat', {
method: 'POST',
headers,
body: JSON.stringify({ message, chatbotId })
});
const data = await response.json();
// The session id lives in the response header — keep it for follow-up messages.
const newSessionId = response.headers.get('X-Chat-Session-Id');
return { ...data, sessionId: newSessionId || sessionId };
}
// First message
const result = await chat('Hello!', 'YOUR_CHATBOT_ID');
console.log(result.reply);
// Follow-up in the same conversation
const followUp = await chat('Tell me more', 'YOUR_CHATBOT_ID', result.sessionId);
console.log(followUp.reply);
Python
import requests
CHATBOT_ID = "YOUR_CHATBOT_ID"
URL = "https://webchatagent.com/api/chat"
# First message
response = requests.post(URL, json={
"message": "What are your business hours?",
"chatbotId": CHATBOT_ID,
})
data = response.json()
session_id = response.headers.get("X-Chat-Session-Id")
print("Reply:", data["reply"])
print("Sources:", data["sources"])
# Continue the conversation
response = requests.post(
URL,
json={"message": "And on weekends?", "chatbotId": CHATBOT_ID},
headers={"X-Chat-Session-Id": session_id},
)
print("Reply:", response.json()["reply"])
PHP
<?php
$chatbotId = 'YOUR_CHATBOT_ID';
$url = 'https://webchatagent.com/api/chat';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'message' => 'What are your business hours?',
'chatbotId' => $chatbotId,
]),
CURLOPT_HEADER => true, // include headers so we can read the session id
]);
$response = curl_exec($ch);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers = substr($response, 0, $headerSize);
$body = json_decode(substr($response, $headerSize), true);
echo 'Reply: ' . $body['reply'] . PHP_EOL;
// Pull the session id from the response headers for follow-up messages
preg_match('/X-Chat-Session-Id:\s*(.+)/i', $headers, $matches);
$sessionId = trim($matches[1] ?? '');
curl_close($ch);
Conversations Export API
Esporta le conversazioni del tuo chatbot in formato CSV o JSON tramite HTTP, filtrate per intervallo di date. Usa questa funzione per automatizzare la reportistica periodica: estrai tutte le conversazioni di un chatbot per un determinato mese, inviale ai tuoi strumenti di analisi o archiviale.
A differenza degli endpoint di chat descritti sopra, questa funzione fa parte delle API della dashboard. L'autenticazione non è basata sul dominio. È necessario accedere con le credenziali del proprio account e riutilizzare il cookie di sessione per la richiesta di esportazione.
Authentication
POST https://webchatagent.com/api/auth/login
Invia l'indirizzo email e la password della dashboard come JSON. La risposta imposta un cookie di sessione, da includere in ogni richiesta successiva. Non è prevista una chiave API separata.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Sì | L'indirizzo email di accesso alla dashboard. |
password | string | Sì | La password della dashboard. |
Requisiti:
- Disponibile per tutti i piani.
- I membri del team devono disporre del permesso Conversazioni.
Export Conversations
GET https://webchatagent.com/api/conversations/export
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
chatbotId | string (UUID) | No | Limita l'esportazione a un singolo chatbot. Ometti il parametro per esportare tutti i chatbot a cui hai accesso. |
from | string (YYYY-MM-DD) | No | Inizio dell'intervallo di date, inclusivo (limite del giorno UTC). |
to | string (YYYY-MM-DD) | No | Fine dell'intervallo di date, inclusivo (limite del giorno UTC). |
q | string | No | Filtro di ricerca. Confronta l'ID sessione, l'IP del client o il contenuto del messaggio. |
format | string | No | csv (predefinito) o json. |
Una conversazione è considerata "nell'intervallo" se contiene almeno un messaggio all'interno delle date specificate. Le conversazioni corrispondenti vengono esportate integralmente, inclusi i messaggi esterni all'intervallo, in modo che una trascrizione a cavallo tra due mesi non venga mai troncata.
Formato CSV: una riga per messaggio, con i metadati della conversazione (nome chatbot, ID sessione, conteggio messaggi, ultima attività) ripetuti su ogni riga. Viene restituito come allegato di file con BOM UTF-8, garantendo una corretta visualizzazione in Excel.
Formato JSON: un oggetto per conversazione con i relativi messaggi nidificati:
{
"range": { "from": "2026-06-01T00:00:00.000Z", "to": "2026-06-30T23:59:59.000Z" },
"sessionsCount": 42,
"messagesCount": 314,
"sessions": [
{
"chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"chatbotName": "Support Bot",
"sessionId": "sess_abc123",
"messagesCount": 6,
"lastActivity": "2026-06-12T09:41:22.000Z",
"lastLanguage": "de",
"lastIp": "203.0.113.* (anon)",
"messages": [
{
"role": "user",
"content": "What are your business hours?",
"sources": null,
"browserLanguage": "de",
"clientIp": "203.0.113.* (anon)",
"referer": "https://example.com/contact",
"createdAt": "2026-06-12T09:40:01.000Z"
}
]
}
]
}
Limiti: l'esportazione è limitata a un massimo di 50.000 messaggi. Le richieste che superano tale soglia restituiscono 413; riduci l'intervallo di date o seleziona un singolo chatbot. Gli IP dei client vengono resi anonimi in entrambi i formati.
Tool Data Endpoints
Gli altri strumenti della dashboard sono accessibili tramite la medesima autenticazione basata su cookie di sessione e supportano lo stesso filtro di date from / to (applicato alla data di creazione di ciascun record, limiti del giorno UTC, entrambi inclusivi). Restituiscono esclusivamente JSON; tutti accettano anche l'assenza di parametri di data per restituire l'intero set di dati.
| Endpoint | Returns | Team permission |
|---|---|---|
GET /api/questions | { success, questions: [...] } | Domande |
GET /api/feedback | { success, data: [...], count } | Feedback |
GET /api/leads | { success, leads: [...] } | Lead |
GET /api/bookings | [...] (array semplice), accetta anche chatbotId | Prenotazioni |
Nel piano gratuito, questi endpoint oscurano i campi di contenuto (***) anziché restituire 403.
# All leads collected in June
curl -b cookies.txt \
"https://webchatagent.com/api/leads?from=2026-06-01&to=2026-06-30"
Example: Monthly Export with cURL
# 1. Log in once and store the session cookie
curl -c cookies.txt -X POST https://webchatagent.com/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"YOUR_PASSWORD"}'
# 2. Download all June conversations of one chatbot as CSV
curl -b cookies.txt -o conversations_june.csv \
"https://webchatagent.com/api/conversations/export?chatbotId=YOUR_CHATBOT_ID&from=2026-06-01&to=2026-06-30"
# Or as JSON for automated processing
curl -b cookies.txt \
"https://webchatagent.com/api/conversations/export?chatbotId=YOUR_CHATBOT_ID&from=2026-06-01&to=2026-06-30&format=json"
Error codes
| Status | Meaning |
|---|---|
401 | Accesso non effettuato o sessione scaduta. Esegui nuovamente l'accesso. |
403 | Piano gratuito, permesso Conversazioni mancante o nessun accesso al chatbot. |
404 | Il parametro chatbotId specificato non esiste nel tuo account. |
413 | Corrispondenza con oltre 50.000 messaggi. Riduci l'intervallo o seleziona un solo chatbot. |
