← Terug naar de app

API & MCP

Bestuur uw chatbot vanuit uw eigen code of vanuit AI-assistenten.

Overzicht#

Chatbotty kan op twee manieren buiten het dashboard worden gebruikt en beheerd: de REST API voor uw eigen code en de MCP-connector voor AI-assistenten zoals Claude. Beide werken met één chatbot tegelijk en gebruiken dezelfde API-sleutels. Begin met Authenticatie.

Basisgegevens

ItemWaarde
REST-basis-URLhttps://www.chatbotty.ai/api/v1
MCP-server-URLhttps://www.chatbotty.ai/api/mcp
FormaatJSON via HTTPS
AuthenticatieAuthorization: Bearer YOUR_API_KEY
Bereik van een sleutelEén sleutel hoort bij precies één chatbot; de chatbot wordt nooit in de aanvraag meegestuurd, maar afgeleid uit de sleutel

Welke u moet gebruiken

  • REST API - u schrijft code die chatberichten verstuurt of documenten, gesprekken, tickets en webhookacties beheert. Zie Chatbot en de volgende endpointsecties.
  • MCP-connector - u koppelt een AI-assistent en laat die zonder te programmeren met de chatbot werken. Zie MCP-connector en MCP-clients.

Abonnementen

API-sleutels, de REST API en de MCP-connector zijn beschikbaar bij elk abonnement: Free, Evaluation, Support en Automate. Afzonderlijke functies zijn afhankelijk van het abonnement.

FunctieFreeEvaluationSupportAutomate
Chat, documenten, gesprekken, analysesJaJaJaJa
TicketsNeeJaJaJa
WebhookactiesNeeJaNeeJa
Documentimport vanaf een web-URLNeeJaJaJa

Een aanroep naar een functie die niet in uw abonnement zit, geeft 403 FORBIDDEN terug. De MCP-connector biedt dergelijke tools helemaal niet aan. Een abonnementswijziging geldt vanaf de volgende aanvraag.

Quotum

  • Alleen berichten die via chat worden verstuurd (REST POST /chat of de MCP-tool send_message) tellen mee voor het maandelijkse berichtenquotum, precies zoals widgetberichten.
  • Andere aanroepen (documenten, gesprekken, analyses, tickets, webhookacties) gebruiken het quotum niet.
  • Wanneer het quotum op is, geeft de chataanroep 403 QUOTA_EXCEEDED terug. Controleer het resterende quotum met GET /chatbot.
  • Sleutels werken ongeacht de toegestane domeinen van de chatbot en zelfs wanneer de chatbot voor de widget inactief is (behalve het versturen van chatberichten, wat een inactieve chatbot weigert met 404 NOT_FOUND).

Antwoordformaat

Elk REST-antwoord gebruikt dezelfde envelop. Fouten worden beschreven in Fouten.

{ "success": true, "data": { }, "timestamp": "2026-01-01T10:00:00.000Z" }

Authenticatie#

Elke aanvraag moet een API-sleutel van de chatbot als Bearer-token meesturen. Dezelfde sleutel werkt voor de REST API en voor de MCP-connector.

curl -H "Authorization: Bearer YOUR_API_KEY" https://www.chatbotty.ai/api/v1/chatbot

API-sleutels

ItemWaarde
FormaatEen willekeurige hexadecimale tekenreeks van 64 tekens
BereikEén chatbot per sleutel
LimietMaximaal 50 sleutels per chatbot (inactieve sleutels tellen ook mee)
OpslagAlleen een hash wordt opgeslagen; de volledige sleutel wordt eenmalig getoond, direct na het aanmaken

Behandel sleutels als wachtwoorden: deel ze nooit en plaats ze nooit in code aan de clientzijde.

Sleutels beheren in het dashboard

  1. Open API & MCP in de zijbalk.
  2. Klik op de kaart van uw chatbot op Nieuwe API-sleutel aanmaken, voer een naam in (bijvoorbeeld "Productie-app") en klik op Aanmaken.
  3. Kopieer de sleutel onmiddellijk. Hij kan niet opnieuw worden getoond ("Kopieer deze sleutel nu. U kunt hem daarna niet meer zien.").

Daarna toont de lijst de naam van de sleutel, de eerste 12 tekens en Laatst gebruikt.

ActieEffect
DeactiverenDe sleutel werkt onmiddellijk niet meer; Activeren zet hem weer aan
VerwijderenDe sleutel wordt definitief verwijderd; apps die hem gebruiken, werken onmiddellijk niet meer

Sleutels die zijn aangemaakt door een AI-assistent te koppelen, hebben het label MCP-connector. Als u zo'n sleutel verwijdert, wordt de assistent losgekoppeld. Als u dezelfde assistent opnieuw aan dezelfde chatbot koppelt, wordt de oude sleutel vervangen.

Authenticatiefouten

SituatieAntwoord
Header ontbreekt of is onjuist opgemaakt401 UNAUTHORIZED "Missing or invalid Authorization header"
Onbekende of gedeactiveerde sleutel401 UNAUTHORIZED "Invalid or inactive API key"

Zie Fouten voor alle codes en Limieten voor aanvraaglimieten.

Limieten#

Limieten gelden per API-sleutel en per minuut. Elke klasse endpoints heeft een eigen teller, zodat veel schrijfaanvragen het budget voor leesaanvragen niet opmaken.

REST API

KlasseEndpointsLimiet per minuut
ChatPOST /chat60
LezenAlle andere GET-endpoints behalve analyses (inclusief GET /chatbot)120
SchrijvenPOST-, PATCH- en DELETE-endpoints60
AnalysesGET /analytics/summary, /analytics/timeseries, /analytics/top-queries60
WebhooktestPOST /webhooks/{id}/test20

Aanvullende limiet: POST /documents/upload-url geeft maximaal 50 upload-URL's per chatbot binnen 2 uur uit.

MCP-connector

Het MCP-endpoint staat 300 aanvragen per minuut per sleutel toe. Elke toolaanroep valt daarnaast onder de REST-limiet van het endpoint dat hij gebruikt, en send_message gebruikt het berichtenquotum.

Wanneer u een limiet overschrijdt

De API geeft 429 RATE_LIMITED terug met een melding zoals "Rate limit exceeded. Maximum 60 requests per minute per API key." Wacht tot de volgende minuut en probeer het opnieuw, bij voorkeur met een oplopende vertraging.

Limieten staan los van het maandelijkse berichtenquotum; zie Overzicht en Fouten.

Chatbot#

Identificeer de chatbot waartoe uw API-sleutel behoort en controleer het abonnement en het quotum voordat u ermee aan de slag gaat.

GET /chatbot

ItemWaarde
Methode en padGET https://www.chatbotty.ai/api/v1/chatbot
ParametersGeen
LimietKlasse Lezen (zie Limieten)
QuotumNiet gebruikt
MCP-toolget_chatbot_info

Antwoord

{
  "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"
    }
  }
}

Opmerkingen

  • plan en message_quota horen bij de accounteigenaar; het quotum wordt gedeeld door alle chatbots van het account.
  • features toont welke van het abonnement afhankelijke functies deze sleutel kan gebruiken.
  • handoff_contact is het contact dat de chatbot geeft wanneer hij het antwoord niet weet (hier alleen-lezen; null wanneer niet ingesteld).
  • last_updated_at is het tijdstip van het nieuwste geüploade document.

Chat#

Verstuur een bericht naar de chatbot en ontvang zijn antwoord, precies zoals een bezoeker in de widget.

POST /chat

ItemWaarde
Methode en padPOST https://www.chatbotty.ai/api/v1/chat
LimietKlasse Chat: 60 per minuut
QuotumEén bericht per aanroep; boven het quotum geeft de aanroep 403 QUOTA_EXCEEDED terug
MCP-toolsend_message

Aanvraagbody

VeldVerplichtBeschrijving
messageJaDe vraag van de bezoeker (niet-lege tekst)
conversation_idNeeZet een bestaand gesprek voort; laat weg om een nieuw gesprek te starten
optionsNeeOptioneel object; niet nodig voor normaal gebruik

Als conversation_id niet bestaat of bij een andere chatbot hoort, geeft de aanroep 400 CONVERSATION_NOT_FOUND terug. Een chatbot die niet actief is, geeft 404 NOT_FOUND terug.

Antwoord

{
  "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 }]
    }
  }
}

Gesprekscontext

De eerste aanroep maakt een gesprek aan en geeft de conversation_id ervan terug. Stuur die id mee met elk volgend bericht om de context te behouden. Gesprekken die via de API zijn aangemaakt, verschijnen in het dashboard met de bron api.

tools_executed

metadata.tools_executed somt de tools op die de chatbot tijdens het antwoorden heeft aangeroepen (webhookacties, het aanmaken van een supportticket). Elk item heeft name, ok en, bij een fout, een korte code zoals webhook_timeout, webhook_redirect, webhook_blocked of invalid_args. Een lege lijst betekent dat er geen tool is aangeroepen. Gebruik dit om te controleren of een webhookactie daadwerkelijk is uitgevoerd.

Documenten#

Beheer de kennisbank van de chatbot: documenten uploaden, lezen, bewerken, weergeven en verwijderen. Deze aanroepen gebruiken het berichtenquotum niet.

Endpoints

Methode en padBeschrijvingBelangrijkste parametersMCP-tool
GET /documentsDocumenten weergevenlimit (standaard 20, max. 100), offset, statuslist_documents
POST /documentsEen document uploaden; geeft 202 terugZie hieronderupload_document
POST /documents/upload-urlEen ondertekende URL ophalen voor een groot of lokaal bestandfilenamecreate_upload_url
GET /documents/{id}Status en details van één document-get_document
DELETE /documents/{id}Een document verwijderen-delete_document
GET /documents/{id}/contentDe tekst lezen, gepagineerdoffset, limit (standaard 20000, max. 50000)read_document
PATCH /documents/{id}/contentEen .md- of .txt-document bewerkenedits, append, expected_hashedit_document, append_to_document

Limieten: GET-aanroepen gebruiken de leeslimiet, de overige de schrijflimiet (zie Limieten).

Uploaden

Toegestane typen: .pdf, .docx, .txt, .md, tot 10 MB. Verstuur multipart/form-data of JSON.

VeldBeschrijving
fileHet bestand (alleen multipart)
contentTekst van een .md- of .txt-document (JSON; filename verplicht)
content_base64Binair bestand in base64 (JSON; gebruik tot ongeveer 3 MB)
urlOpenbare bestands-URL die de server downloadt (JSON; alleen abonnementen met import via web-URL)
upload_idId van POST /documents/upload-url nadat u het bestand heeft geüpload
filenameBestandsnaam met extensie
descriptionOptionele beschrijving
replace_existingStandaard true: een bestand met dezelfde naam wordt door de nieuwe versie vervangen

Verstuur in JSON precies één van content, content_base64, url, upload_id.

{ "filename": "faq.md", "content": "# FAQ\n\n## Opening hours\n..." }

Grote of lokale bestanden

  1. POST /documents/upload-url met { "filename": "price-list.pdf" }. Het antwoord bevat upload_id, upload_url en headers; de URL is 2 uur geldig en werkt eenmalig.
  2. Verstuur het ruwe bestand met PUT naar upload_url.
  3. POST /documents met { "upload_id": "...", "filename": "price-list.pdf" }.

Verwerking en status

De verwerking is asynchroon. De status gaat van pending via processing naar completed, of eindigt als failed met een error_message. Een mislukt document blijft in de lijst staan; verwijder het of upload het opnieuw. Poll GET /documents/{id} totdat de status completed is.

Bewerken en vervangen

  • PATCH /documents/{id}/content verstuurt alleen de wijziging: edits (lijst van old_text en new_text, elke old_text moet precies één keer voorkomen, maximaal 100) en/of append (text, optioneel after_heading).
  • expected_hash (uit GET .../content) beschermt tegen het overschrijven van een nieuwere versie (409 CONFLICT).
  • Alleen UTF-8 .md- en .txt-documenten kunnen worden bewerkt (anders 400 NOT_EDITABLE).
  • Elke bewerking of vervanging maakt een nieuwe document_id aan; de oude versie blijft antwoorden totdat de nieuwe completed is.
  • Een tweede wijziging terwijl het document nog wordt verwerkt, geeft 409 REPLACE_IN_PROGRESS terug.

Gesprekken#

Lees de gespreksgeschiedenis van de chatbot, inclusief gesprekken die in de widget zijn aangemaakt. Deze aanroepen zijn alleen-lezen en gebruiken het berichtenquotum niet.

Endpoints

Methode en padBeschrijvingBelangrijkste parametersMCP-tool
GET /conversationsGesprekken weergevenZie hieronderlist_conversations
GET /conversations/{id}Eén gesprek-get_conversation
GET /conversations/{id}/messagesBerichten in chronologische volgordelimit (standaard 50, max. 200), offsetget_conversation_messages

Alle drie gebruiken de leeslimiet van 120 aanvragen per minuut (zie Limieten). Een gesprek van een andere chatbot geeft 404 NOT_FOUND terug.

Lijstfilters

ParameterBeschrijving
limit, offsetPaginering (standaard 20, max. 100)
statusactive, completed of ticket_created
sourcewidget of api
from, toISO 8601-datums; filteren op het begin van het gesprek
qualityGesprekken met minstens één vraag van dit soort: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified
qZoeken in de volledige tekst van berichten (2 tot 200 tekens)

Antwoord

{
  "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 }
  }
}

Bij abonnementen met tickets bevat het detail van een gesprek ook de tickets die daarin zijn aangemaakt. Berichten hebben id, role (user of assistant), content en created_at.

Tip

Om vragen te vinden die de chatbot niet kon beantwoorden, gebruikt u GET /analytics/top-queries?quality=not_answered (zie Analyses) en opent u de bijbehorende gesprekken via conversation_ids.

Analyses#

Geaggregeerde statistieken van de chatbot. Analyses zijn beschikbaar bij elk abonnement, ook Free. Deze aanroepen gebruiken het berichtenquotum niet.

Endpoints

Methode en padBeschrijvingMCP-tool
GET /analytics/summaryTotalen voor de periodeget_analytics_summary
GET /analytics/timeseriesAantallen per uur, dag of weekget_analytics_timeseries
GET /analytics/top-queriesMeest gestelde vragenget_top_queries, list_knowledge_gaps

Alle drie gebruiken de analyselimiet van 60 aanvragen per minuut (zie Limieten).

Gemeenschappelijke parameters

ParameterBeschrijving
periodtoday (standaard), week, month of quarter, beoordeeld in de tijdzone van de chatbot
from, toISO 8601-datums; ze vervangen period; het bereik is maximaal 366 dagen
sourcewidget of api

Aanvullende parameters

EndpointParameterBeschrijving
timeseriesgranularityauto (standaard), hour, day of week; hour met quarter wordt geweigerd
top-querieslimit, offsetPaginering (standaard 20, max. 100)
top-queriesqualityanswered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified

Antwoord van 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 is het aantal beantwoorde vragen gedeeld door beantwoord plus niet beantwoord, in procenten.

Onbeantwoorde vragen

GET /analytics/top-queries?quality=not_answered&period=month geeft de vragen terug die de chatbot niet kon beantwoorden, de meest gestelde eerst. Elk item heeft content, count, last_asked en maximaal 5 conversation_ids die u kunt openen via gesprekken. Voeg de ontbrekende feiten toe aan de kennisbank en controleer het resultaat met chat.

Tickets#

Lees supporttickets, wijzig hun status en voeg interne notities toe. Tickets zijn beschikbaar bij de abonnementen Evaluation, Support en Automate; Free geeft 403 FORBIDDEN terug. Tickets kunnen niet via de API worden aangemaakt: de chatbot maakt ze aan tijdens een gesprek.

Endpoints

Methode en padBeschrijvingBelangrijkste parametersMCP-tool
GET /ticketsTickets weergeven, nieuwste eerstlimit (standaard 20, max. 100), offset, status, conversation_id, from, tolist_tickets
GET /tickets/{id}Eén ticket-get_ticket
PATCH /tickets/{id}De status wijzigenstatus in de bodyupdate_ticket_status
GET /tickets/{id}/notesInterne notities, oudste eerst-list_ticket_notes
POST /tickets/{id}/notesEen notitie toevoegen; geeft 201 terugcontent in de bodyadd_ticket_note

GET-aanroepen gebruiken de leeslimiet (120 per minuut), PATCH en POST de schrijflimiet (60 per minuut); zie Limieten.

Waarden

ItemWaarde
Statusopen, in_progress, resolved, closed
NotitieNiet-lege tekst, maximaal 5000 tekens

Een ongeldige status geeft 400 INVALID_REQUEST terug. Een ticket van een andere chatbot geeft 404 NOT_FOUND terug.

Ticketobject

{
  "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"
}

Voorbeeld

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"}'

Webhookacties#

Beheer de webhookacties van de chatbot: externe API's of automatiseringswebhooks (bijvoorbeeld n8n) die de chatbot tijdens het antwoorden als tools aanroept. Beschikbaar bij het Automate-abonnement (10 webhooks en 10 tools per chatbot) en de Evaluation-proefperiode (5 webhooks en 5 tools per chatbot). Andere abonnementen krijgen 403 FORBIDDEN; het overschrijden van de limieten geeft 403 LIMIT_EXCEEDED terug. Aanroepen gebruiken het berichtenquotum niet.

Endpoints

Methode en padBeschrijvingMCP-tool
GET /webhooksWebhooks weergeven en het gebruik van uw limietenlist_webhook_actions
POST /webhooksEen webhook aanmaken, optioneel met tools; geeft 201 terugcreate_webhook_action
GET /webhooks/{id}Eén webhook met zijn toolsget_webhook_action
PATCH /webhooks/{id}Een webhook wijzigenupdate_webhook_action
DELETE /webhooks/{id}Een webhook met zijn tools verwijderendelete_webhook_action
POST /webhooks/{id}/toolsEen tool toevoegen; geeft 201 terugadd_webhook_tool
PATCH /webhooks/{id}/tools/{toolId}Een tool wijzigenupdate_webhook_tool
DELETE /webhooks/{id}/tools/{toolId}Een tool verwijderendelete_webhook_tool
POST /webhooks/{id}/testDe webhook aanroepen zoals de chatbot dat doettest_webhook_action

Lezen gebruikt de leeslimiet (120 per minuut), wijzigingen de schrijflimiet (60) en de test heeft een eigen limiet van 20 per minuut; zie Limieten. De MCP-tool get_webhook_guide geeft een korte handleiding voor AI-assistenten terug.

Webhookvelden

VeldBeschrijving
nameVerplicht, maximaal 100 tekens
webhook_urlVerplicht, openbaar HTTPS-adres
http_methodPOST (standaard) of GET
send_metadataStandaard true: de aanroep bevat ook tool_name, args en metadata (chatbot_id, conversation_id, timestamp); false verstuurt alleen de argumenten
timeout_ms1000 tot 30000, standaard 10000
headersMaximaal 20 aangepaste headers
secret_queryMaximaal 10 geheime queryparameters, bijvoorbeeld een API-sleutel
toolsTools die de chatbot mag aanroepen (zie hieronder)

Toolvelden

VeldBeschrijving
nameKleine letters, cijfers en underscores, begint met een letter, maximaal 64 tekens, uniek per chatbot; create_support_ticket is gereserveerd
descriptionMaximaal 500 tekens; vertelt de chatbot wanneer hij de tool moet gebruiken
parametersMaximaal 10 items met name, type (string, number, boolean), description (maximaal 200 tekens), required

Regels

  • Waarden van headers en secret_query worden nooit teruggegeven, alleen hun namen. Een sleutel die in webhook_url wordt gevonden, wordt automatisch naar secret_query verplaatst en gemeld in warnings.
  • Om het endpoint van een webhook te wijzigen, moet u alle opgeslagen headers- en secret_query-sleutels opnieuw meesturen, zodat geheimen niet ongemerkt naar een andere server kunnen verhuizen.
  • De chatbot doet per antwoord één ronde toolaanroepen. Een antwoord wordt afgekapt bij 10 KB, omleidingen worden niet gevolgd en interne adressen worden geweigerd.

Test

POST /webhooks/{id}/test met een optionele body { "tool_name": "get_weather", "arguments": { "q": "Prague" } } geeft ok, status, response_time_ms, body_preview (eerste 2 KB), truncated en warnings terug. Stel na een test de chatbot via chat een passende vraag en controleer tools_executed.

Fouten#

Mislukte REST-aanroepen geven een HTTP-status buiten het 2xx-bereik en deze envelop terug:

{
  "success": false,
  "error": { "code": "INVALID_REQUEST", "message": "message is required and cannot be empty", "details": {} },
  "timestamp": "2026-01-01T10:00:00.000Z"
}

details is alleen bij sommige fouten aanwezig. Verwerk fouten op basis van code; meldingen kunnen veranderen.

Foutcodes

CodeHTTPBetekenis
UNAUTHORIZED401Ontbrekende, ongeldige of gedeactiveerde API-sleutel
QUOTA_EXCEEDED403Maandelijks berichtenquotum opgebruikt (details.quota_info)
FORBIDDEN403De functie zit niet in uw abonnement
LIMIT_EXCEEDED403Abonnementslimiet voor webhooks of tools bereikt (details.resource, used, max)
INVALID_REQUEST400Ongeldige body of parameters
INVALID_URL400Webhook-URL is ongeldig, niet HTTPS of niet openbaar
INVALID_FILE400Het bestand ontbreekt bij de upload
FILE_TOO_LARGE400Bestand groter dan 10 MB
UNSUPPORTED_FILE_TYPE400Alleen .pdf, .docx, .txt, .md worden geaccepteerd
CONVERSATION_NOT_FOUND400conversation_id bestaat niet of hoort bij een andere chatbot
EDIT_FAILED400Te vervangen tekst niet gevonden, of meer dan één keer gevonden
NOT_EDITABLE400Alleen UTF-8 .md- en .txt-documenten kunnen worden bewerkt
NOT_FOUND404Document, ticket, webhook, tool of upload niet gevonden, of inactieve chatbot
DUPLICATE_FILENAME409Er bestaat al een document met deze naam (details.existing_document_id)
DUPLICATE_CONTENT409Dezelfde inhoud is al geïndexeerd
REPLACE_IN_PROGRESS409Het document wordt vervangen of verwerkt; wacht tot het completed is
CONFLICT409Toolnaam bestaat al, of het document is gewijzigd sinds u het las
STORAGE_LIMIT_EXCEEDED413Opslaglimiet van de chatbot overschreden
RATE_LIMITED429Te veel aanvragen; zie Limieten
GONE_USE_V1410Het oude endpoint /api/chat is verwijderd; gebruik /api/v1/chat
INTERNAL_ERROR500Onverwachte serverfout

MCP-fouten

Het MCP-endpoint antwoordt met JSON-RPC-fouten: 401 voor een ontbrekend of ongeldig token, 429 voor te veel aanvragen en 403 wanneer het abonnement geen MCP bevat. Wanneer een tool mislukt, is het resultaat als fout gemarkeerd en bevat het de API-code, bijvoorbeeld Chatbotty API error [NOT_FOUND] (HTTP 404). Zie MCP-connector.

Support

Als een fout aanhoudt, schrijf dan naar support@chatbotty.ai en vermeld de code, het tijdstip en het endpoint.

MCP-connector#

Met de MCP-connector kan een AI-assistent zoals Claude, n8n of Cursor met uw chatbot werken: ermee chatten, de kennisbank beheren, webhookacties instellen en gesprekken, analyses en tickets lezen. Eén connector hoort bij één chatbot; om een andere chatbot te gebruiken, voegt u een andere connector toe.

Verbinding

ItemWaarde
Server-URLhttps://www.chatbotty.ai/api/mcp
TransportStreamable HTTP via POST
AbonnementenAlle abonnementen; bij elke aanvraag gecontroleerd
Limiet300 aanvragen per minuut per sleutel (zie Limieten)

Aanmelden of sleutel

MethodeGebruikt doorHoe
Aanmelden (OAuth)claude.ai, Claude Desktop, Claude mobiel, Claude CodeDe client opent een Chatbotty-pagina; u meldt zich aan, kiest de chatbot en klikt op Toestaan. Er wordt automatisch een sleutel aangemaakt
API-sleuteln8n, Cursor, VS Code, andere clientsVerstuur de header Authorization: Bearer YOUR_API_KEY (Authenticatie)

Een sleutel die door aanmelden is aangemaakt, heeft in API & MCP het label MCP-connector. Verwijder hem daar om de assistent los te koppelen. Tickets en webhooktools verschijnen alleen als uw abonnement ze bevat. De installatiestappen staan in MCP-clients.

Tools

GebiedTools
Chatbot en chatget_chatbot_info, send_message
Documentenlist_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document
Kennishiatenlist_knowledge_gaps
Gesprekkenlist_conversations, get_conversation, get_conversation_messages
Analysesget_analytics_summary, get_analytics_timeseries, get_top_queries
Tickets (abonnementen met tickets)list_tickets, get_ticket, update_ticket_status, list_ticket_notes, add_ticket_note
Webhookacties (abonnementen met webhookacties)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

Elke tool werkt als het overeenkomstige REST-endpoint dat in de bovenstaande secties wordt beschreven en heeft dezelfde limieten en fouten.

Goed om te weten

  • send_message praat met de chatbot als een bezoeker en gebruikt het maandelijkse berichtenquotum. test_webhook_action niet.
  • list_knowledge_gaps geeft vragen weer die de chatbot niet kon beantwoorden en heeft een periode nodig; gebruik het om te vinden wat u aan de kennisbank moet toevoegen.
  • Een client kan toolbeschrijvingen in de cache bewaren. Als tools verouderd lijken, verwijdert u de connector en voegt u hem opnieuw toe.

MCP-clients#

Zo koppelt u gangbare clients aan https://www.chatbotty.ai/api/mcp. Voor clients die een sleutel meesturen, maakt u die eerst aan zoals beschreven in Authenticatie. Achtergrond: MCP-connector.

Claude (claude.ai, Claude Desktop, mobiel)

  1. Open Instellingen, daarna Connectors, en voeg een aangepaste connector toe.
  2. Plak de server-URL en klik op Verbinden.
  3. Meld u aan bij Chatbotty, kies de chatbot en klik op Toestaan.

Er is geen API-sleutel nodig. De connector werkt daarna ook in de mobiele Claude-app.

Claude Code

Aanmelden via de browser:

claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp

Of gebruik een API-sleutel:

claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Wanneer de aanmeldpagina waarschuwt dat de app op uw eigen computer draait, geeft u alleen toegang als u de verbinding zelf heeft gestart.

n8n

  1. Voeg het node MCP Client Tool toe.
  2. Endpoint: de server-URL.
  3. Server Transport: HTTP Streamable.
  4. Authentication: Bearer Auth met uw API-sleutel.

Cursor, VS Code en andere clients

Voeg een externe MCP-server toe met de server-URL en de header Authorization: Bearer YOUR_API_KEY. In Cursor bijvoorbeeld:

{
  "mcpServers": {
    "chatbotty": {
      "url": "https://www.chatbotty.ai/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Probleemoplossing

ProbleemControleer
401De sleutel is onjuist, gedeactiveerd of verwijderd
Tickets of webhooktools ontbrekenUw abonnement bevat ze niet
Handmatige client krijgt 406De client moet Accept: application/json, text/event-stream meesturen

Voorbeelden#

Voorbeelden om te kopiëren en plakken voor de meest voorkomende taken. Vervang YOUR_API_KEY door een sleutel van API & MCP en https://www.chatbotty.ai door de basis-URL. Zie Authenticatie.

De chatbot en het quotum controleren

curl https://www.chatbotty.ai/api/v1/chatbot \
  -H "Authorization: Bearer YOUR_API_KEY"

Een vraag stellen en het gesprek voortzetten

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?"}'

Neem conversation_id uit het antwoord over en stuur die mee met het volgende bericht:

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"}'

Een document uploaden

curl -X POST https://www.chatbotty.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./faq.md"

Controleer daarna de status totdat die completed is:

curl https://www.chatbotty.ai/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Onbeantwoorde vragen vinden

curl "https://www.chatbotty.ai/api/v1/analytics/top-queries?quality=not_answered&period=month" \
  -H "Authorization: Bearer YOUR_API_KEY"

Gesprekken weergeven die een woord bevatten

curl "https://www.chatbotty.ai/api/v1/conversations?q=refund&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Fouten afhandelen

{ "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" }

Vertak op error.code en zie Fouten. Voor limieten, zie Limieten. Vragen: support@chatbotty.ai.