API & MCP
Controlli il Suo chatbot dal Suo codice o dagli assistenti IA.
Panoramica#
Chatbotty può essere usato e gestito dall'esterno della dashboard in due modi: l'API REST per il proprio codice e il connettore MCP per gli assistenti IA come Claude. Entrambi lavorano con un chatbot alla volta e usano le stesse chiavi API. Iniziare da Autenticazione.
Nozioni di base
| Elemento | Valore |
|---|---|
| URL di base REST | https://www.chatbotty.ai/api/v1 |
| URL del server MCP | https://www.chatbotty.ai/api/mcp |
| Formato | JSON su HTTPS |
| Autenticazione | Authorization: Bearer YOUR_API_KEY |
| Ambito di una chiave | Una chiave appartiene esattamente a un chatbot; il chatbot non viene mai inviato nella richiesta, ma ricavato dalla chiave |
Quale usare
- API REST - si scrive codice che invia messaggi di chat o gestisce documenti, conversazioni, ticket e azioni webhook. Vedere Chatbot e le sezioni degli endpoint che seguono.
- Connettore MCP - si collega un assistente IA e lo si lascia lavorare con il chatbot senza scrivere codice. Vedere Connettore MCP e Client MCP.
Piani
Le chiavi API, l'API REST e il connettore MCP sono disponibili in ogni piano: Free, Evaluation, Support e Automate. Le singole funzionalità dipendono dal piano.
| Funzionalità | Free | Evaluation | Support | Automate |
|---|---|---|---|---|
| Chat, documenti, conversazioni, analisi | Sì | Sì | Sì | Sì |
| Ticket | No | Sì | Sì | Sì |
| Azioni webhook | No | Sì | No | Sì |
| Importazione di documenti da URL web | No | Sì | Sì | Sì |
Una chiamata a una funzionalità non inclusa nel piano restituisce 403 FORBIDDEN. Il connettore MCP non offre affatto tali strumenti. Un cambio di piano si applica alla richiesta successiva.
Quota
- Solo i messaggi inviati tramite la chat (REST
POST /chato lo strumento MCPsend_message) contano per la quota mensile di messaggi, esattamente come i messaggi del widget. - Le altre chiamate (documenti, conversazioni, analisi, ticket, azioni webhook) non usano la quota.
- Quando la quota è esaurita, la chiamata di chat restituisce
403 QUOTA_EXCEEDED. Verificare la quota residua conGET /chatbot. - Le chiavi funzionano indipendentemente dai domini consentiti del chatbot e anche quando il chatbot è inattivo per il widget (tranne l'invio di messaggi di chat, che un chatbot inattivo rifiuta con
404 NOT_FOUND).
Formato delle risposte
Ogni risposta REST usa lo stesso involucro. Gli errori sono descritti in Errori.
{ "success": true, "data": { }, "timestamp": "2026-01-01T10:00:00.000Z" }
Autenticazione#
Ogni richiesta deve includere una chiave API del chatbot come token Bearer. La stessa chiave funziona per l'API REST e per il connettore MCP.
curl -H "Authorization: Bearer YOUR_API_KEY" https://www.chatbotty.ai/api/v1/chatbot
Chiavi API
| Elemento | Valore |
|---|---|
| Formato | Una stringa esadecimale casuale di 64 caratteri |
| Ambito | Un chatbot per chiave |
| Limite | Fino a 50 chiavi per chatbot (contano anche le chiavi inattive) |
| Archiviazione | Viene memorizzato solo un hash; la chiave completa viene mostrata una sola volta, subito dopo la creazione |
Trattare le chiavi come password: non condividerle mai e non inserirle mai nel codice lato client.
Gestione delle chiavi nella dashboard
- Aprire API e MCP nella barra laterale.
- Nella scheda del proprio chatbot fare clic su Crea nuova chiave API, inserire un nome (ad esempio "Production app") e fare clic su Crea.
- Copiare subito la chiave. Non può essere mostrata di nuovo ("Copia questa chiave ora. Non potrai più vederla.").
In seguito l'elenco mostra il nome della chiave, i suoi primi 12 caratteri e Ultimo utilizzo.
| Azione | Effetto |
|---|---|
| Disattiva | La chiave smette subito di funzionare; Attiva la riattiva |
| Elimina | La chiave viene rimossa definitivamente; le app che la usano smettono subito di funzionare |
Le chiavi create collegando un assistente IA sono etichettate Connettore MCP. Eliminare una tale chiave scollega l'assistente. Collegando di nuovo lo stesso assistente allo stesso chatbot, la vecchia chiave viene sostituita.
Errori di autenticazione
| Situazione | Risposta |
|---|---|
| Header mancante o malformato | 401 UNAUTHORIZED "Missing or invalid Authorization header" |
| Chiave sconosciuta o disattivata | 401 UNAUTHORIZED "Invalid or inactive API key" |
Vedere Errori per tutti i codici e Limiti di frequenza per i limiti di richieste.
Limiti di frequenza#
I limiti si applicano per chiave API e per minuto. Ogni classe di endpoint ha un proprio contatore, quindi molte scritture non esauriscono il budget delle letture.
API REST
| Classe | Endpoint | Limite al minuto |
|---|---|---|
| Chat | POST /chat | 60 |
| Lettura | Tutti gli altri endpoint GET tranne le analisi (compreso GET /chatbot) | 120 |
| Scrittura | Endpoint POST, PATCH, DELETE | 60 |
| Analisi | GET /analytics/summary, /analytics/timeseries, /analytics/top-queries | 60 |
| Test webhook | POST /webhooks/{id}/test | 20 |
Limite aggiuntivo: POST /documents/upload-url emette al massimo 50 URL di caricamento per chatbot entro 2 ore.
Connettore MCP
L'endpoint MCP consente 300 richieste al minuto per chiave. Ogni chiamata a uno strumento è poi soggetta anche al limite REST dell'endpoint che utilizza, e send_message usa la quota di messaggi.
Quando si supera un limite
L'API restituisce 429 RATE_LIMITED con un messaggio come "Rate limit exceeded. Maximum 60 requests per minute per API key." Attendere il minuto successivo e riprovare, idealmente con un ritardo crescente.
I limiti di frequenza sono separati dalla quota mensile di messaggi; vedere Panoramica e Errori.
Chatbot#
Identificare il chatbot a cui appartiene la chiave API e verificarne il piano e la quota prima di iniziare a lavorarci.
GET /chatbot
| Elemento | Valore |
|---|---|
| Metodo e percorso | GET https://www.chatbotty.ai/api/v1/chatbot |
| Parametri | Nessuno |
| Limite di frequenza | Classe lettura (vedere Limiti di frequenza) |
| Quota | Non utilizzata |
| Strumento MCP | get_chatbot_info |
Risposta
{
"success": true,
"data": {
"id": "uuid",
"name": "CycleZone",
"description": "Customer care chatbot",
"is_active": true,
"language": "auto",
"timezone": "America/New_York",
"handoff_contact": "info@example.com",
"created_at": "2026-01-01T10:00:00.000Z",
"dashboard_url": "https://www.chatbotty.ai/dashboard/chatbots/uuid",
"plan": "Automate",
"message_quota": { "used": 622, "monthly_limit": 9000, "extra_messages": 0 },
"features": { "tickets": true, "upload_from_url": true, "webhook_actions": true },
"knowledge_base": {
"documents_total": 1,
"documents_by_status": { "pending": 0, "processing": 0, "completed": 1, "failed": 0 },
"last_updated_at": "2026-01-01T10:00:00.000Z"
}
}
}
Note
planemessage_quotaappartengono al proprietario dell'account; la quota è condivisa da tutti i chatbot dell'account.featuresindica quali funzionalità dipendenti dal piano questa chiave può usare.handoff_contactè il contatto che il chatbot fornisce quando non conosce la risposta (qui in sola lettura;nullse non impostato).last_updated_atè l'ora del documento caricato più di recente.
Chat#
Inviare un messaggio al chatbot e ricevere la sua risposta, esattamente come un visitatore nel widget.
POST /chat
| Elemento | Valore |
|---|---|
| Metodo e percorso | POST https://www.chatbotty.ai/api/v1/chat |
| Limite di frequenza | Classe chat: 60 al minuto |
| Quota | Un messaggio per chiamata; oltre la quota la chiamata restituisce 403 QUOTA_EXCEEDED |
| Strumento MCP | send_message |
Corpo della richiesta
| Campo | Obbligatorio | Descrizione |
|---|---|---|
message | Sì | La domanda del visitatore (testo non vuoto) |
conversation_id | No | Prosegue una conversazione esistente; ometterlo per avviarne una nuova |
options | No | Oggetto opzionale; non necessario nell'uso normale |
Se conversation_id non esiste o appartiene a un altro chatbot, la chiamata restituisce 400 CONVERSATION_NOT_FOUND. Un chatbot non attivo restituisce 404 NOT_FOUND.
Risposta
{
"success": true,
"data": {
"message": "Our warranty is two years.",
"conversation_id": "uuid",
"sources": [{ "content": "...", "similarity": 0.87 }],
"metadata": {
"tokensUsed": 312,
"cached": false,
"responseTime": 1240,
"searchResults": 3,
"quality": "answered",
"confidence": 0.87,
"tools_executed": [{ "name": "get_weather", "ok": true }]
}
}
}
Contesto della conversazione
La prima chiamata crea una conversazione e restituisce il suo conversation_id. Inviare quell'id con ogni messaggio successivo per mantenere il contesto. Le conversazioni create tramite l'API compaiono nella dashboard con la fonte api.
tools_executed
metadata.tools_executed elenca gli strumenti che il chatbot ha chiamato mentre rispondeva (azioni webhook, creazione di ticket di supporto). Ogni elemento ha name, ok e, in caso di errore, un breve code come webhook_timeout, webhook_redirect, webhook_blocked o invalid_args. Un elenco vuoto significa che nessuno strumento è stato chiamato. Usarlo per verificare che un'azione webhook sia stata realmente eseguita.
Documenti#
Gestire la base di conoscenza del chatbot: caricare, leggere, modificare, elencare ed eliminare documenti. Queste chiamate non usano la quota di messaggi.
Endpoint
| Metodo e percorso | Descrizione | Parametri principali | Strumento MCP |
|---|---|---|---|
GET /documents | Elenca i documenti | limit (predefinito 20, max 100), offset, status | list_documents |
POST /documents | Carica un documento; restituisce 202 | Vedere sotto | upload_document |
POST /documents/upload-url | Ottiene un URL firmato per un file grande o locale | filename | create_upload_url |
GET /documents/{id} | Stato e dettagli di un documento | - | get_document |
DELETE /documents/{id} | Elimina un documento | - | delete_document |
GET /documents/{id}/content | Legge il testo, a pagine | offset, limit (predefinito 20000, max 50000) | read_document |
PATCH /documents/{id}/content | Modifica un documento .md o .txt | edits, append, expected_hash | edit_document, append_to_document |
Limiti: le chiamate GET usano il limite di lettura, le altre quello di scrittura (vedere Limiti di frequenza).
Caricamento
Tipi consentiti: .pdf, .docx, .txt, .md, fino a 10 MB. Inviare multipart/form-data oppure JSON.
| Campo | Descrizione |
|---|---|
file | Il file (solo multipart) |
content | Testo di un documento .md o .txt (JSON; filename obbligatorio) |
content_base64 | File binario in base64 (JSON; da usare fino a circa 3 MB) |
url | URL pubblico del file che il server scarica (JSON; solo piani con importazione da URL web) |
upload_id | Id da POST /documents/upload-url dopo aver caricato il file |
filename | Nome del file con estensione |
description | Descrizione opzionale |
replace_existing | Predefinito true: un file con lo stesso nome viene sostituito dalla nuova versione |
In JSON, inviare esattamente uno tra content, content_base64, url, upload_id.
{ "filename": "faq.md", "content": "# FAQ\n\n## Opening hours\n..." }
File grandi o locali
POST /documents/upload-urlcon{ "filename": "price-list.pdf" }. La risposta contieneupload_id,upload_urle gli header; l'URL è valido per 2 ore e funziona una sola volta.- Inviare il file grezzo con
PUTaupload_url. POST /documentscon{ "upload_id": "...", "filename": "price-list.pdf" }.
Elaborazione e stato
L'elaborazione è asincrona. Lo stato passa da pending a processing fino a completed, oppure termina come failed con un error_message. Un documento fallito resta nell'elenco; eliminarlo o caricarlo di nuovo. Interrogare GET /documents/{id} finché non è completed.
Modifica e sostituzione
PATCH /documents/{id}/contentinvia solo la modifica:edits(elenco diold_textenew_text, ogniold_textdeve comparire esattamente una volta, fino a 100) e/oappend(text,after_headingopzionale).expected_hash(daGET .../content) protegge dalla sovrascrittura di una versione più recente (409 CONFLICT).- Possono essere modificati solo documenti
.mde.txtin UTF-8 (altrimenti400 NOT_EDITABLE). - Ogni modifica o sostituzione crea un nuovo
document_id; la vecchia versione continua a rispondere finché la nuova non ècompleted. - Una seconda modifica mentre il documento è ancora in elaborazione restituisce
409 REPLACE_IN_PROGRESS.
Conversazioni#
Leggere la cronologia delle conversazioni del chatbot, comprese quelle create nel widget. Queste chiamate sono di sola lettura e non usano la quota di messaggi.
Endpoint
| Metodo e percorso | Descrizione | Parametri principali | Strumento MCP |
|---|---|---|---|
GET /conversations | Elenca le conversazioni | Vedere sotto | list_conversations |
GET /conversations/{id} | Una conversazione | - | get_conversation |
GET /conversations/{id}/messages | Messaggi in ordine cronologico | limit (predefinito 50, max 200), offset | get_conversation_messages |
Tutti e tre usano il limite di lettura di 120 richieste al minuto (vedere Limiti di frequenza). Una conversazione di un altro chatbot restituisce 404 NOT_FOUND.
Filtri dell'elenco
| Parametro | Descrizione |
|---|---|
limit, offset | Paginazione (predefinito 20, max 100) |
status | active, completed o ticket_created |
source | widget o api |
from, to | Date ISO 8601; filtrano sull'inizio della conversazione |
quality | Conversazioni con almeno una domanda di questo tipo: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
q | Ricerca full-text nel testo dei messaggi (da 2 a 200 caratteri) |
Risposta
{
"success": true,
"data": {
"conversations": [
{
"id": "uuid",
"started_at": "2026-01-01T10:00:00Z",
"last_activity_at": "2026-01-01T10:15:00Z",
"message_count": 5,
"status": "active",
"source": "widget",
"email": "visitor@example.com",
"phone": null
}
],
"pagination": { "limit": 20, "offset": 0, "total": 42 }
}
}
Nei piani con ticket, il dettaglio di una conversazione contiene anche i tickets creati al suo interno. I messaggi hanno id, role (user o assistant), content e created_at.
Suggerimento
Per trovare le domande a cui il chatbot non ha saputo rispondere, usare GET /analytics/top-queries?quality=not_answered (vedere Analisi) e aprire le conversazioni correlate tramite conversation_ids.
Analisi#
Statistiche aggregate del chatbot. Le analisi sono disponibili in ogni piano, Free compreso. Queste chiamate non usano la quota di messaggi.
Endpoint
| Metodo e percorso | Descrizione | Strumento MCP |
|---|---|---|
GET /analytics/summary | Totali del periodo | get_analytics_summary |
GET /analytics/timeseries | Conteggi per ora, giorno o settimana | get_analytics_timeseries |
GET /analytics/top-queries | Domande più frequenti | get_top_queries, list_knowledge_gaps |
Tutti e tre usano il limite delle analisi di 60 richieste al minuto (vedere Limiti di frequenza).
Parametri comuni
| Parametro | Descrizione |
|---|---|
period | today (predefinito), week, month o quarter, valutato nel fuso orario del chatbot |
from, to | Date ISO 8601; sostituiscono period; l'intervallo è al massimo di 366 giorni |
source | widget o api |
Parametri aggiuntivi
| Endpoint | Parametro | Descrizione |
|---|---|---|
timeseries | granularity | auto (predefinito), hour, day o week; hour con quarter viene rifiutato |
top-queries | limit, offset | Paginazione (predefinito 20, max 100) |
top-queries | quality | answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
Risposta di summary
{
"period": "week",
"total_queries": 7,
"answered_queries": 5,
"not_answered_queries": 1,
"conversation_queries": 1,
"off_topic_queries": 0,
"ticket_created_queries": 0,
"tool_call_queries": 0,
"success_rate": 83.3,
"widget_queries": 6,
"api_queries": 1
}
success_rate è il numero di risposte divise per la somma di risposte e non risposte, in percentuale.
Domande senza risposta
GET /analytics/top-queries?quality=not_answered&period=month restituisce le domande a cui il chatbot non ha saputo rispondere, dalla più frequente. Ogni elemento ha content, count, last_asked e fino a 5 conversation_ids che si possono aprire tramite le conversazioni. Aggiungere i fatti mancanti alla base di conoscenza e verificare il risultato con la chat.
Ticket#
Leggere i ticket di supporto, cambiarne lo stato e aggiungere note interne. I ticket sono disponibili nei piani Evaluation, Support e Automate; Free restituisce 403 FORBIDDEN. I ticket non possono essere creati tramite l'API: li crea il chatbot durante una conversazione.
Endpoint
| Metodo e percorso | Descrizione | Parametri principali | Strumento MCP |
|---|---|---|---|
GET /tickets | Elenca i ticket, dal più recente | limit (predefinito 20, max 100), offset, status, conversation_id, from, to | list_tickets |
GET /tickets/{id} | Un ticket | - | get_ticket |
PATCH /tickets/{id} | Cambia lo stato | status nel corpo | update_ticket_status |
GET /tickets/{id}/notes | Note interne, dalla più vecchia | - | list_ticket_notes |
POST /tickets/{id}/notes | Aggiunge una nota; restituisce 201 | content nel corpo | add_ticket_note |
Le chiamate GET usano il limite di lettura (120 al minuto), PATCH e POST il limite di scrittura (60 al minuto); vedere Limiti di frequenza.
Valori
| Elemento | Valore |
|---|---|
| Stato | open, in_progress, resolved, closed |
| Nota | Testo non vuoto, fino a 5000 caratteri |
Uno stato non valido restituisce 400 INVALID_REQUEST. Un ticket di un altro chatbot restituisce 404 NOT_FOUND.
Oggetto ticket
{
"id": "uuid",
"ticket_number": "TKT-000015",
"conversation_id": "uuid",
"email": "visitor@example.com",
"phone": null,
"summary": "The visitor asked to speak with a person.",
"status": "open",
"created_at": "2026-01-01T10:00:00Z",
"updated_at": "2026-01-01T10:00:00Z"
}
Esempio
curl -X PATCH https://www.chatbotty.ai/api/v1/tickets/TICKET_ID \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "resolved"}'
Azioni webhook#
Gestire le azioni webhook del chatbot: API esterne o webhook di automazione (ad esempio n8n) che il chatbot chiama come strumenti mentre risponde. Disponibili nel piano Automate (10 webhook e 10 strumenti per chatbot) e nella prova Evaluation (5 webhook e 5 strumenti per chatbot). Gli altri piani ricevono 403 FORBIDDEN; il superamento dei limiti restituisce 403 LIMIT_EXCEEDED. Le chiamate non usano la quota di messaggi.
Endpoint
| Metodo e percorso | Descrizione | Strumento MCP |
|---|---|---|
GET /webhooks | Elenca i webhook e l'utilizzo dei limiti | list_webhook_actions |
POST /webhooks | Crea un webhook, facoltativamente con strumenti; restituisce 201 | create_webhook_action |
GET /webhooks/{id} | Un webhook con i suoi strumenti | get_webhook_action |
PATCH /webhooks/{id} | Modifica un webhook | update_webhook_action |
DELETE /webhooks/{id} | Elimina un webhook con i suoi strumenti | delete_webhook_action |
POST /webhooks/{id}/tools | Aggiunge uno strumento; restituisce 201 | add_webhook_tool |
PATCH /webhooks/{id}/tools/{toolId} | Modifica uno strumento | update_webhook_tool |
DELETE /webhooks/{id}/tools/{toolId} | Elimina uno strumento | delete_webhook_tool |
POST /webhooks/{id}/test | Chiama il webhook come fa il chatbot | test_webhook_action |
Le letture usano il limite di lettura (120 al minuto), le modifiche il limite di scrittura (60) e il test ha un proprio limite di 20 al minuto; vedere Limiti di frequenza. Lo strumento MCP get_webhook_guide restituisce una breve guida per gli assistenti IA.
Campi del webhook
| Campo | Descrizione |
|---|---|
name | Obbligatorio, fino a 100 caratteri |
webhook_url | Obbligatorio, indirizzo HTTPS pubblico |
http_method | POST (predefinito) o GET |
send_metadata | Predefinito true: la chiamata trasporta anche tool_name, args e metadata (chatbot_id, conversation_id, timestamp); false invia solo gli argomenti |
timeout_ms | Da 1000 a 30000, predefinito 10000 |
headers | Fino a 20 header personalizzati |
secret_query | Fino a 10 parametri di query segreti, ad esempio una chiave API |
tools | Strumenti che il chatbot può chiamare (vedere sotto) |
Campi dello strumento
| Campo | Descrizione |
|---|---|
name | Lettere minuscole, cifre e trattini bassi, inizia con una lettera, fino a 64 caratteri, univoco per chatbot; create_support_ticket è riservato |
description | Fino a 500 caratteri; indica al chatbot quando usare lo strumento |
parameters | Fino a 10 elementi con name, type (string, number, boolean), description (fino a 200 caratteri), required |
Regole
- I valori di
headersesecret_querynon vengono mai restituiti, solo i loro nomi. Una chiave trovata inwebhook_urlviene spostata automaticamente insecret_querye segnalata inwarnings. - Cambiare l'endpoint di un webhook richiede di inviare di nuovo tutte le chiavi memorizzate di
headersesecret_query, così i segreti non possono passare inosservati a un altro server. - Il chatbot effettua un solo giro di chiamate agli strumenti per risposta. Una risposta viene troncata a 10 KB, i reindirizzamenti non vengono seguiti e gli indirizzi interni vengono rifiutati.
Test
POST /webhooks/{id}/test con un corpo opzionale { "tool_name": "get_weather", "arguments": { "q": "Prague" } } restituisce ok, status, response_time_ms, body_preview (primi 2 KB), truncated e warnings. Dopo un test, porre al chatbot una domanda corrispondente tramite la chat e controllare tools_executed.
Errori#
Le chiamate REST non riuscite restituiscono uno stato HTTP non 2xx e questo involucro:
{
"success": false,
"error": { "code": "INVALID_REQUEST", "message": "message is required and cannot be empty", "details": {} },
"timestamp": "2026-01-01T10:00:00.000Z"
}
details è presente solo per alcuni errori. Gestire gli errori in base a code; i messaggi possono cambiare.
Codici di errore
| Codice | HTTP | Significato |
|---|---|---|
UNAUTHORIZED | 401 | Chiave API mancante, non valida o disattivata |
QUOTA_EXCEEDED | 403 | Quota mensile di messaggi esaurita (details.quota_info) |
FORBIDDEN | 403 | La funzionalità non è inclusa nel piano |
LIMIT_EXCEEDED | 403 | Raggiunto il limite del piano per webhook o strumenti (details.resource, used, max) |
INVALID_REQUEST | 400 | Corpo o parametri non validi |
INVALID_URL | 400 | L'URL del webhook non è valido, non è HTTPS o non è pubblico |
INVALID_FILE | 400 | Il file è assente dal caricamento |
FILE_TOO_LARGE | 400 | File oltre 10 MB |
UNSUPPORTED_FILE_TYPE | 400 | Sono accettati solo .pdf, .docx, .txt, .md |
CONVERSATION_NOT_FOUND | 400 | conversation_id non esiste o appartiene a un altro chatbot |
EDIT_FAILED | 400 | Testo da sostituire non trovato, oppure trovato più volte |
NOT_EDITABLE | 400 | Possono essere modificati solo documenti .md e .txt in UTF-8 |
NOT_FOUND | 404 | Documento, ticket, webhook, strumento o caricamento non trovato, oppure chatbot inattivo |
DUPLICATE_FILENAME | 409 | Esiste un documento con questo nome (details.existing_document_id) |
DUPLICATE_CONTENT | 409 | Lo stesso contenuto è già indicizzato |
REPLACE_IN_PROGRESS | 409 | Il documento è in fase di sostituzione o elaborazione; attendere che sia completed |
CONFLICT | 409 | Il nome dello strumento esiste già, oppure il documento è cambiato dopo la lettura |
STORAGE_LIMIT_EXCEEDED | 413 | Superato il limite di spazio del chatbot |
RATE_LIMITED | 429 | Troppe richieste; vedere Limiti di frequenza |
GONE_USE_V1 | 410 | Il vecchio endpoint /api/chat è stato rimosso; usare /api/v1/chat |
INTERNAL_ERROR | 500 | Errore imprevisto del server |
Errori MCP
L'endpoint MCP risponde con errori JSON-RPC: 401 per un token mancante o non valido, 429 per troppe richieste e 403 quando il piano non include MCP. Quando uno strumento fallisce, il risultato è contrassegnato come errore e contiene il codice API, ad esempio Chatbotty API error [NOT_FOUND] (HTTP 404). Vedere Connettore MCP.
Supporto
Se un errore persiste, scrivere a support@chatbotty.ai indicando il codice, l'ora e l'endpoint.
Connettore MCP#
Il connettore MCP consente a un assistente IA come Claude, n8n o Cursor di lavorare con il Suo chatbot: conversare con esso, gestirne la base di conoscenza, configurare azioni webhook e leggere conversazioni, analisi e ticket. Un connettore appartiene a un solo chatbot; per usare un altro chatbot, aggiungere un altro connettore.
Connessione
| Elemento | Valore |
|---|---|
| URL del server | https://www.chatbotty.ai/api/mcp |
| Trasporto | Streamable HTTP tramite POST |
| Piani | Tutti i piani; verificato a ogni richiesta |
| Limite | 300 richieste al minuto per chiave (vedere Limiti di frequenza) |
Accesso o chiave
| Metodo | Usato da | Procedura |
|---|---|---|
| Accesso (OAuth) | claude.ai, Claude Desktop, Claude mobile, Claude Code | Il client apre una pagina di Chatbotty; si accede, si sceglie il chatbot e si fa clic su Consenti. Una chiave viene creata automaticamente |
| Chiave API | n8n, Cursor, VS Code, altri client | Inviare l'header Authorization: Bearer YOUR_API_KEY (Autenticazione) |
Una chiave creata tramite accesso è etichettata Connettore MCP in API e MCP. Eliminarla lì per scollegare l'assistente. I ticket e gli strumenti webhook compaiono solo se il piano li include. I passaggi di configurazione si trovano in Client MCP.
Strumenti
| Area | Strumenti |
|---|---|
| Chatbot e chat | get_chatbot_info, send_message |
| Documenti | list_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document |
| Lacune di conoscenza | list_knowledge_gaps |
| Conversazioni | list_conversations, get_conversation, get_conversation_messages |
| Analisi | get_analytics_summary, get_analytics_timeseries, get_top_queries |
| Ticket (piani con ticket) | list_tickets, get_ticket, update_ticket_status, list_ticket_notes, add_ticket_note |
| Azioni webhook (piani con azioni webhook) | get_webhook_guide, list_webhook_actions, get_webhook_action, create_webhook_action, update_webhook_action, test_webhook_action, delete_webhook_action, add_webhook_tool, update_webhook_tool, delete_webhook_tool |
Ogni strumento funziona come il corrispondente endpoint REST descritto nelle sezioni precedenti e ha gli stessi limiti ed errori.
Da sapere
send_messageconversa con il chatbot come un visitatore e usa la quota mensile di messaggi.test_webhook_actionno.list_knowledge_gapselenca le domande a cui il chatbot non ha saputo rispondere e richiede un periodo; usarlo per individuare cosa aggiungere alla base di conoscenza.- Un client può memorizzare nella cache le descrizioni degli strumenti. Se gli strumenti sembrano obsoleti, rimuovere il connettore e aggiungerlo di nuovo.
Client MCP#
Come collegare i client più diffusi a https://www.chatbotty.ai/api/mcp. Per i client che inviano una chiave, crearla prima come descritto in Autenticazione. Contesto: Connettore MCP.
Claude (claude.ai, Claude Desktop, mobile)
- Aprire Impostazioni, poi Connettori, quindi aggiungere un connettore personalizzato.
- Incollare l'URL del server e fare clic su Connetti.
- Accedere a Chatbotty, scegliere il chatbot e fare clic su Consenti.
Non è necessaria alcuna chiave API. Il connettore funziona poi anche nell'app mobile di Claude.
Claude Code
Accedere tramite il browser:
claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp
Oppure usare una chiave API:
claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
Quando la pagina di accesso avverte che l'app è in esecuzione sul proprio computer, consentire l'accesso solo se la connessione è stata avviata da Lei.
n8n
- Aggiungere il nodo MCP Client Tool.
- Endpoint: l'URL del server.
- Server Transport: HTTP Streamable.
- Authentication: Bearer Auth con la propria chiave API.
Cursor, VS Code e altri client
Aggiungere un server MCP remoto con l'URL del server e l'header Authorization: Bearer YOUR_API_KEY. In Cursor, ad esempio:
{
"mcpServers": {
"chatbotty": {
"url": "https://www.chatbotty.ai/api/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
Risoluzione dei problemi
| Problema | Cosa controllare |
|---|---|
401 | La chiave è errata, disattivata o eliminata |
| Mancano i ticket o gli strumenti webhook | Il piano non li include |
Un client manuale riceve 406 | Il client deve inviare Accept: application/json, text/event-stream |
Esempi#
Esempi da copiare e incollare per le attività più comuni. Sostituire YOUR_API_KEY con una chiave di API e MCP e https://www.chatbotty.ai con l'URL di base. Vedere Autenticazione.
Verificare il chatbot e la quota
curl https://www.chatbotty.ai/api/v1/chatbot \
-H "Authorization: Bearer YOUR_API_KEY"
Porre una domanda e proseguire la conversazione
curl -X POST https://www.chatbotty.ai/api/v1/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "What are your opening hours?"}'
Prendere conversation_id dalla risposta e inviarlo con il messaggio successivo:
curl -X POST https://www.chatbotty.ai/api/v1/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "And on Sunday?", "conversation_id": "CONVERSATION_ID"}'
Caricare un documento
curl -X POST https://www.chatbotty.ai/api/v1/documents \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@./faq.md"
Poi controllare lo stato finché non è completed:
curl https://www.chatbotty.ai/api/v1/documents/DOCUMENT_ID \
-H "Authorization: Bearer YOUR_API_KEY"
Trovare le domande senza risposta
curl "https://www.chatbotty.ai/api/v1/analytics/top-queries?quality=not_answered&period=month" \
-H "Authorization: Bearer YOUR_API_KEY"
Elencare le conversazioni che contengono una parola
curl "https://www.chatbotty.ai/api/v1/conversations?q=refund&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
Gestire gli errori
{ "success": false, "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Maximum 60 requests per minute per API key." }, "timestamp": "2026-01-01T10:00:00.000Z" }
Ramificare in base a error.code e vedere Errori. Per i limiti, vedere Limiti di frequenza. Domande: support@chatbotty.ai.