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

  1. Esegui una POST con il message dell'utente e il tuo chatbotId verso /api/chat.
  2. Leggi il campo reply dal corpo JSON. Leggi l'header di risposta X-Chat-Session-Id: quello è il tuo ID sessione.
  3. 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.
  4. 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

HeaderObbligatorioDescrizione
Content-TypeSìDeve essere application/json.
X-Chat-Session-IdNoID 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.
AcceptNotext/event-stream per ricevere la risposta come stream (vedi Streaming).
Accept-LanguageNoLingua preferita per la risposta, ad es. de.

Corpo Richiesta

CampoTipoObbligatorioDescrizione
messagestringSìIl messaggio dell'utente. Massimo 700 caratteri. Non può essere vuoto.
chatbotIdstring (UUID)SìL'ID del tuo chatbot, reperibile nelle impostazioni del chatbot.
pageUrlstringNoL'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.
contextDataobjectNoContesto 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.

CampoTipoDescrizione
replystringLa 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.
sourcesarrayOrigini su cui è stata basata la risposta (vedi sotto). Vuoto se non ne è stata usata nessuna.
modestringModalità di conversazione: bot (l'IA sta rispondendo) o human (un operatore umano ha preso il controllo). Presente quando pertinente.
statusstringStato della live chat: waiting, open o closed. Presente solo quando la live chat è attiva per la sessione.
aiGeneratedbooleantrue quando l'IA ha scritto la risposta. Assente mentre un operatore umano gestisce la conversazione.
conversationTooLongbooleanLa 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:

CampoTipoDescrizione
typestringweb (una pagina web), product (dati di prodotto strutturati) o fileSource (un documento dall'archivio file connesso).
sourcestringPer web: l'URL della pagina. Per product: l'identificatore del prodotto. Per fileSource: l'ID del documento.
dataobjectSolo 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}
typeCampiSignificato
tokendataFrammento successivo della risposta. Aggiungilo. Il testo può contenere Markdown incompleto e l'inizio del commento dei suggerimenti.
tool_callnameIl bot sta utilizzando un tool, ad es. una ricerca di prodotti.
errordataUn problema. Di solito segue un done; se lo stream termina senza done, tratta data come errore.
donestessi campi della risposta JSONLa 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

ParametroTipoObbligatorioDescrizione
chatbotIdstring (UUID)SìL'ID del tuo chatbot.
sessionIdstring (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

ParametroTipoObbligatorioDescrizione
chatbotIdstring (UUID)SìL'ID del tuo chatbot.
sessionIdsstringSì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

HeaderRequiredDescription
X-Chat-Session-IdSì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.

StatusMeaning
400Corpo non valido, campo mancante, messaggio vuoto o messaggio superiore a 700 caratteri.
403Dominio non consentito, autenticazione wiki non riuscita o applicazione di una restrizione del piano.
404Chatbot non trovato.
429Limite di richieste raggiunto o quota mensile di messaggi esaurita.
502Il 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

ScopeLimit
Per sessione10 richieste al minuto
Per indirizzo IP15 richieste al minuto
Per sessione e per indirizzo IPalmeno 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.

FieldTypeRequiredDescription
emailstringSìL'indirizzo email di accesso alla dashboard.
passwordstringSì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

ParameterTypeRequiredDescription
chatbotIdstring (UUID)NoLimita l'esportazione a un singolo chatbot. Ometti il parametro per esportare tutti i chatbot a cui hai accesso.
fromstring (YYYY-MM-DD)NoInizio dell'intervallo di date, inclusivo (limite del giorno UTC).
tostring (YYYY-MM-DD)NoFine dell'intervallo di date, inclusivo (limite del giorno UTC).
qstringNoFiltro di ricerca. Confronta l'ID sessione, l'IP del client o il contenuto del messaggio.
formatstringNocsv (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.

EndpointReturnsTeam 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 chatbotIdPrenotazioni

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

StatusMeaning
401Accesso non effettuato o sessione scaduta. Esegui nuovamente l'accesso.
403Piano gratuito, permesso Conversazioni mancante o nessun accesso al chatbot.
404Il parametro chatbotId specificato non esiste nel tuo account.
413Corrispondenza con oltre 50.000 messaggi. Riduci l'intervallo o seleziona un solo chatbot.