← Torna all'app

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

ElementoValore
URL di base RESThttps://www.chatbotty.ai/api/v1
URL del server MCPhttps://www.chatbotty.ai/api/mcp
FormatoJSON su HTTPS
AutenticazioneAuthorization: Bearer YOUR_API_KEY
Ambito di una chiaveUna 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àFreeEvaluationSupportAutomate
Chat, documenti, conversazioni, analisiSìSìSìSì
TicketNoSìSìSì
Azioni webhookNoSìNoSì
Importazione di documenti da URL webNoSì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 /chat o lo strumento MCP send_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 con GET /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

ElementoValore
FormatoUna stringa esadecimale casuale di 64 caratteri
AmbitoUn chatbot per chiave
LimiteFino a 50 chiavi per chatbot (contano anche le chiavi inattive)
ArchiviazioneViene 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

  1. Aprire API e MCP nella barra laterale.
  2. Nella scheda del proprio chatbot fare clic su Crea nuova chiave API, inserire un nome (ad esempio "Production app") e fare clic su Crea.
  3. 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.

AzioneEffetto
DisattivaLa chiave smette subito di funzionare; Attiva la riattiva
EliminaLa 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

SituazioneRisposta
Header mancante o malformato401 UNAUTHORIZED "Missing or invalid Authorization header"
Chiave sconosciuta o disattivata401 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

ClasseEndpointLimite al minuto
ChatPOST /chat60
LetturaTutti gli altri endpoint GET tranne le analisi (compreso GET /chatbot)120
ScritturaEndpoint POST, PATCH, DELETE60
AnalisiGET /analytics/summary, /analytics/timeseries, /analytics/top-queries60
Test webhookPOST /webhooks/{id}/test20

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

ElementoValore
Metodo e percorsoGET https://www.chatbotty.ai/api/v1/chatbot
ParametriNessuno
Limite di frequenzaClasse lettura (vedere Limiti di frequenza)
QuotaNon utilizzata
Strumento MCPget_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

  • plan e message_quota appartengono al proprietario dell'account; la quota è condivisa da tutti i chatbot dell'account.
  • features indica 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; null se 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

ElementoValore
Metodo e percorsoPOST https://www.chatbotty.ai/api/v1/chat
Limite di frequenzaClasse chat: 60 al minuto
QuotaUn messaggio per chiamata; oltre la quota la chiamata restituisce 403 QUOTA_EXCEEDED
Strumento MCPsend_message

Corpo della richiesta

CampoObbligatorioDescrizione
messageSìLa domanda del visitatore (testo non vuoto)
conversation_idNoProsegue una conversazione esistente; ometterlo per avviarne una nuova
optionsNoOggetto 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 percorsoDescrizioneParametri principaliStrumento MCP
GET /documentsElenca i documentilimit (predefinito 20, max 100), offset, statuslist_documents
POST /documentsCarica un documento; restituisce 202Vedere sottoupload_document
POST /documents/upload-urlOttiene un URL firmato per un file grande o localefilenamecreate_upload_url
GET /documents/{id}Stato e dettagli di un documento-get_document
DELETE /documents/{id}Elimina un documento-delete_document
GET /documents/{id}/contentLegge il testo, a pagineoffset, limit (predefinito 20000, max 50000)read_document
PATCH /documents/{id}/contentModifica un documento .md o .txtedits, append, expected_hashedit_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.

CampoDescrizione
fileIl file (solo multipart)
contentTesto di un documento .md o .txt (JSON; filename obbligatorio)
content_base64File binario in base64 (JSON; da usare fino a circa 3 MB)
urlURL pubblico del file che il server scarica (JSON; solo piani con importazione da URL web)
upload_idId da POST /documents/upload-url dopo aver caricato il file
filenameNome del file con estensione
descriptionDescrizione opzionale
replace_existingPredefinito 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

  1. POST /documents/upload-url con { "filename": "price-list.pdf" }. La risposta contiene upload_id, upload_url e gli header; l'URL è valido per 2 ore e funziona una sola volta.
  2. Inviare il file grezzo con PUT a upload_url.
  3. POST /documents con { "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}/content invia solo la modifica: edits (elenco di old_text e new_text, ogni old_text deve comparire esattamente una volta, fino a 100) e/o append (text, after_heading opzionale).
  • expected_hash (da GET .../content) protegge dalla sovrascrittura di una versione più recente (409 CONFLICT).
  • Possono essere modificati solo documenti .md e .txt in UTF-8 (altrimenti 400 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 percorsoDescrizioneParametri principaliStrumento MCP
GET /conversationsElenca le conversazioniVedere sottolist_conversations
GET /conversations/{id}Una conversazione-get_conversation
GET /conversations/{id}/messagesMessaggi in ordine cronologicolimit (predefinito 50, max 200), offsetget_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

ParametroDescrizione
limit, offsetPaginazione (predefinito 20, max 100)
statusactive, completed o ticket_created
sourcewidget o api
from, toDate ISO 8601; filtrano sull'inizio della conversazione
qualityConversazioni con almeno una domanda di questo tipo: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified
qRicerca 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 percorsoDescrizioneStrumento MCP
GET /analytics/summaryTotali del periodoget_analytics_summary
GET /analytics/timeseriesConteggi per ora, giorno o settimanaget_analytics_timeseries
GET /analytics/top-queriesDomande più frequentiget_top_queries, list_knowledge_gaps

Tutti e tre usano il limite delle analisi di 60 richieste al minuto (vedere Limiti di frequenza).

Parametri comuni

ParametroDescrizione
periodtoday (predefinito), week, month o quarter, valutato nel fuso orario del chatbot
from, toDate ISO 8601; sostituiscono period; l'intervallo è al massimo di 366 giorni
sourcewidget o api

Parametri aggiuntivi

EndpointParametroDescrizione
timeseriesgranularityauto (predefinito), hour, day o week; hour con quarter viene rifiutato
top-querieslimit, offsetPaginazione (predefinito 20, max 100)
top-queriesqualityanswered, 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 percorsoDescrizioneParametri principaliStrumento MCP
GET /ticketsElenca i ticket, dal più recentelimit (predefinito 20, max 100), offset, status, conversation_id, from, tolist_tickets
GET /tickets/{id}Un ticket-get_ticket
PATCH /tickets/{id}Cambia lo statostatus nel corpoupdate_ticket_status
GET /tickets/{id}/notesNote interne, dalla più vecchia-list_ticket_notes
POST /tickets/{id}/notesAggiunge una nota; restituisce 201content nel corpoadd_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

ElementoValore
Statoopen, in_progress, resolved, closed
NotaTesto 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 percorsoDescrizioneStrumento MCP
GET /webhooksElenca i webhook e l'utilizzo dei limitilist_webhook_actions
POST /webhooksCrea un webhook, facoltativamente con strumenti; restituisce 201create_webhook_action
GET /webhooks/{id}Un webhook con i suoi strumentiget_webhook_action
PATCH /webhooks/{id}Modifica un webhookupdate_webhook_action
DELETE /webhooks/{id}Elimina un webhook con i suoi strumentidelete_webhook_action
POST /webhooks/{id}/toolsAggiunge uno strumento; restituisce 201add_webhook_tool
PATCH /webhooks/{id}/tools/{toolId}Modifica uno strumentoupdate_webhook_tool
DELETE /webhooks/{id}/tools/{toolId}Elimina uno strumentodelete_webhook_tool
POST /webhooks/{id}/testChiama il webhook come fa il chatbottest_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

CampoDescrizione
nameObbligatorio, fino a 100 caratteri
webhook_urlObbligatorio, indirizzo HTTPS pubblico
http_methodPOST (predefinito) o GET
send_metadataPredefinito true: la chiamata trasporta anche tool_name, args e metadata (chatbot_id, conversation_id, timestamp); false invia solo gli argomenti
timeout_msDa 1000 a 30000, predefinito 10000
headersFino a 20 header personalizzati
secret_queryFino a 10 parametri di query segreti, ad esempio una chiave API
toolsStrumenti che il chatbot può chiamare (vedere sotto)

Campi dello strumento

CampoDescrizione
nameLettere minuscole, cifre e trattini bassi, inizia con una lettera, fino a 64 caratteri, univoco per chatbot; create_support_ticket è riservato
descriptionFino a 500 caratteri; indica al chatbot quando usare lo strumento
parametersFino a 10 elementi con name, type (string, number, boolean), description (fino a 200 caratteri), required

Regole

  • I valori di headers e secret_query non vengono mai restituiti, solo i loro nomi. Una chiave trovata in webhook_url viene spostata automaticamente in secret_query e segnalata in warnings.
  • Cambiare l'endpoint di un webhook richiede di inviare di nuovo tutte le chiavi memorizzate di headers e secret_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

CodiceHTTPSignificato
UNAUTHORIZED401Chiave API mancante, non valida o disattivata
QUOTA_EXCEEDED403Quota mensile di messaggi esaurita (details.quota_info)
FORBIDDEN403La funzionalità non è inclusa nel piano
LIMIT_EXCEEDED403Raggiunto il limite del piano per webhook o strumenti (details.resource, used, max)
INVALID_REQUEST400Corpo o parametri non validi
INVALID_URL400L'URL del webhook non è valido, non è HTTPS o non è pubblico
INVALID_FILE400Il file è assente dal caricamento
FILE_TOO_LARGE400File oltre 10 MB
UNSUPPORTED_FILE_TYPE400Sono accettati solo .pdf, .docx, .txt, .md
CONVERSATION_NOT_FOUND400conversation_id non esiste o appartiene a un altro chatbot
EDIT_FAILED400Testo da sostituire non trovato, oppure trovato più volte
NOT_EDITABLE400Possono essere modificati solo documenti .md e .txt in UTF-8
NOT_FOUND404Documento, ticket, webhook, strumento o caricamento non trovato, oppure chatbot inattivo
DUPLICATE_FILENAME409Esiste un documento con questo nome (details.existing_document_id)
DUPLICATE_CONTENT409Lo stesso contenuto è già indicizzato
REPLACE_IN_PROGRESS409Il documento è in fase di sostituzione o elaborazione; attendere che sia completed
CONFLICT409Il nome dello strumento esiste già, oppure il documento è cambiato dopo la lettura
STORAGE_LIMIT_EXCEEDED413Superato il limite di spazio del chatbot
RATE_LIMITED429Troppe richieste; vedere Limiti di frequenza
GONE_USE_V1410Il vecchio endpoint /api/chat è stato rimosso; usare /api/v1/chat
INTERNAL_ERROR500Errore 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

ElementoValore
URL del serverhttps://www.chatbotty.ai/api/mcp
TrasportoStreamable HTTP tramite POST
PianiTutti i piani; verificato a ogni richiesta
Limite300 richieste al minuto per chiave (vedere Limiti di frequenza)

Accesso o chiave

MetodoUsato daProcedura
Accesso (OAuth)claude.ai, Claude Desktop, Claude mobile, Claude CodeIl client apre una pagina di Chatbotty; si accede, si sceglie il chatbot e si fa clic su Consenti. Una chiave viene creata automaticamente
Chiave APIn8n, Cursor, VS Code, altri clientInviare 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

AreaStrumenti
Chatbot e chatget_chatbot_info, send_message
Documentilist_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document
Lacune di conoscenzalist_knowledge_gaps
Conversazionilist_conversations, get_conversation, get_conversation_messages
Analisiget_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_message conversa con il chatbot come un visitatore e usa la quota mensile di messaggi. test_webhook_action no.
  • list_knowledge_gaps elenca 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)

  1. Aprire Impostazioni, poi Connettori, quindi aggiungere un connettore personalizzato.
  2. Incollare l'URL del server e fare clic su Connetti.
  3. 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

  1. Aggiungere il nodo MCP Client Tool.
  2. Endpoint: l'URL del server.
  3. Server Transport: HTTP Streamable.
  4. 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

ProblemaCosa controllare
401La chiave è errata, disattivata o eliminata
Mancano i ticket o gli strumenti webhookIl piano non li include
Un client manuale riceve 406Il 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.