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 UI di chat personalizzata, un'app mobile o un'automazione backend. Ogni endpoint viene servito dalla stessa origine dello script del tuo widget (https://webchatagent.com).

Come funziona una conversazione

1. Esegui un POST del message dell'utente e del tuo chatbotId a /api/chat.
2. Leggi il valore reply dal corpo JSON. Leggi l'header di risposta X-Chat-Session-Id, corrisponde al 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 chat dal vivo.
4. Ripeti l'operazione. Ometti l'header ogni volta che desideri avviare una nuova conversazione.

Il server tiene traccia della cronologia per ogni sessione, quindi invii sempre e solo l'ultimo messaggio, mai l'intera trascrizione.

Autenticazione

L'API utilizza un'autenticazione basata su dominio: non esiste 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 di esso, i wiki protetti restituiscono 403.

Inviare un messaggio

POST https://webchatagent.com/api/chat

Header

Corpo Richiesta

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.

Quando un operatore umano ha preso il controllo (mode: "human", status: "open"), reply potrebbe essere vuoto, in quanto l'operatore risponde separatamente. Mentre il passaggio di consegne è waiting, la risposta è un breve avviso come "Un membro del team si unirà a breve."

Array Sources

Ogni oggetto source:

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: se un chatbot ha lo streaming abilitato, il widget riceve la risposta token per token tramite Server-Sent Events. La risposta JSON standard documentata qui è ciò che si ottiene per una richiesta normale ed è il modello appropriato per integrazioni server-to-server e per la maggior parte delle UI personalizzate.

Cronologia chat

Recupera i messaggi archiviati per una sessione (ad esempio per ripristinare una conversazione dopo aver ricaricato la pagina). La cronologia più vecchia di 30 giorni viene rimossa per conformità al GDPR; una sessione scaduta restituisce 410.

GET https://webchatagent.com/api/chat/history

Parametri di query

Risposta

messages è ordinato a partire dal più vecchio. sender è bot o user (è un valore di visualizzazione, non il ruolo non elaborato). role è il ruolo sottostante user / assistant / system, e isAgent è true quando un messaggio 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 fuga di informazioni sulle 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

Risposta

{
  "sessions": [
    {
      "sessionId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "messageCount": 12,
      "lastActivity": "2025-01-15T10:35:00Z"
    }
  ]
}

Ripristinare la cronologia della sessione

Cancella il contesto di conversazione in memoria per una sessione, in modo che il messaggio successivo faccia ripartire l'IA da capo (senza i passaggi precedenti). Questo non elimina i messaggi archiviati: conversation_messages sono dati aziendali e rimangono nel database (e in /api/chat/history).

DELETE https://webchatagent.com/api/chat/session

Header

Risposta

{ "success": true, "message": "Chat session cleared." }

Gestione degli errori

Gli errori provenienti da /api/chat restituiscono 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 effettivo di errore.

Corpo della risposta di errore

{
  "reply": "<p>I'm getting a lot of requests right now. Please try again in a few moments.</p>",
  "sources": []
}

Il corpo è sempre { reply, sources }, non è presente un involucro di errore separato. Gestisci la logica in base al codice di stato HTTP e mostra reply all'utente se desideri utilizzare un messaggio predefinito.

Limiti di frequenza

Il superamento di uno dei due limiti restituisce 429. Separatamente, il raggiungimento della quota mensile di messaggi del piano restituisce a sua volta 429 (con un messaggio di "temporaneamente non disponibile").

Esempi di codice

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);

API di esportazione delle conversazioni

Esporta le conversazioni del tuo chatbot in formato CSV o JSON tramite HTTP, filtrate per intervallo di date. Usalo per automatizzare i report periodici: estrai tutte le conversazioni di un chatbot per un determinato mese, inseriscile nelle tue analisi o archiviale.

A differenza degli endpoint di chat sopra indicati, questo fa parte dell'API della dashboard. Non è autenticato tramite dominio. Accedi con le credenziali del tuo account e riutilizzi il cookie di sessione per la richiesta di esportazione.

Autenticazione

POST https://webchatagent.com/api/auth/login

Invia l'email e la password della dashboard in formato JSON. La risposta imposta un cookie di sessione; includilo in ogni richiesta successiva. Non esiste una chiave API separata.

Requisiti:

• Un piano a pagamento. L'endpoint di esportazione restituisce 403 con il piano gratuito.
• I membri del team necessitano dell'autorizzazione Conversazioni.

Esportazione delle conversazioni

GET https://webchatagent.com/api/conversations/export

Parametri di query

Una conversazione è "nell'intervallo" quando contiene almeno un messaggio all'interno dell'intervallo. Le conversazioni corrispondenti vengono esportate per intero, 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. Restituito come allegato di file con un BOM UTF-8, in modo da aprirsi correttamente 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: un'esportazione ha un limite massimo di 50.000 messaggi. Le richieste più ampie restituiscono 413; restringi l'intervallo di date o seleziona un singolo chatbot. Gli IP dei client vengono resi anonimi in entrambi i formati.

Endpoint dei dati degli strumenti

Gli altri strumenti della dashboard sono accessibili tramite la stessa autenticazione basata su cookie di sessione e supportano lo stesso filtro di date from / to (sulla data di creazione di ciascun record, limiti del giorno UTC, entrambi inclusivi). Restituiscono solo JSON; tutti accettano anche l'assenza di parametri di data per restituire l'intero contenuto.

Nel piano gratuito questi endpoint oscurano i campi di contenuto (***) invece di restituire 403.

# All leads collected in June
curl -b cookies.txt \
  "https://webchatagent.com/api/leads?from=2026-06-01&to=2026-06-30"

Esempio: Esportazione mensile con 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"

Codici di errore