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
| Item | Waarde |
|---|---|
| REST-basis-URL | https://www.chatbotty.ai/api/v1 |
| MCP-server-URL | https://www.chatbotty.ai/api/mcp |
| Formaat | JSON via HTTPS |
| Authenticatie | Authorization: Bearer YOUR_API_KEY |
| Bereik van een sleutel | Eé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.
| Functie | Free | Evaluation | Support | Automate |
|---|---|---|---|---|
| Chat, documenten, gesprekken, analyses | Ja | Ja | Ja | Ja |
| Tickets | Nee | Ja | Ja | Ja |
| Webhookacties | Nee | Ja | Nee | Ja |
| Documentimport vanaf een web-URL | Nee | Ja | Ja | Ja |
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 /chatof de MCP-toolsend_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_EXCEEDEDterug. Controleer het resterende quotum metGET /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
| Item | Waarde |
|---|---|
| Formaat | Een willekeurige hexadecimale tekenreeks van 64 tekens |
| Bereik | Eén chatbot per sleutel |
| Limiet | Maximaal 50 sleutels per chatbot (inactieve sleutels tellen ook mee) |
| Opslag | Alleen 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
- Open API & MCP in de zijbalk.
- Klik op de kaart van uw chatbot op Nieuwe API-sleutel aanmaken, voer een naam in (bijvoorbeeld "Productie-app") en klik op Aanmaken.
- 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.
| Actie | Effect |
|---|---|
| Deactiveren | De sleutel werkt onmiddellijk niet meer; Activeren zet hem weer aan |
| Verwijderen | De 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
| Situatie | Antwoord |
|---|---|
| Header ontbreekt of is onjuist opgemaakt | 401 UNAUTHORIZED "Missing or invalid Authorization header" |
| Onbekende of gedeactiveerde sleutel | 401 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
| Klasse | Endpoints | Limiet per minuut |
|---|---|---|
| Chat | POST /chat | 60 |
| Lezen | Alle andere GET-endpoints behalve analyses (inclusief GET /chatbot) | 120 |
| Schrijven | POST-, PATCH- en DELETE-endpoints | 60 |
| Analyses | GET /analytics/summary, /analytics/timeseries, /analytics/top-queries | 60 |
| Webhooktest | POST /webhooks/{id}/test | 20 |
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
| Item | Waarde |
|---|---|
| Methode en pad | GET https://www.chatbotty.ai/api/v1/chatbot |
| Parameters | Geen |
| Limiet | Klasse Lezen (zie Limieten) |
| Quotum | Niet gebruikt |
| MCP-tool | get_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
planenmessage_quotahoren bij de accounteigenaar; het quotum wordt gedeeld door alle chatbots van het account.featurestoont welke van het abonnement afhankelijke functies deze sleutel kan gebruiken.handoff_contactis het contact dat de chatbot geeft wanneer hij het antwoord niet weet (hier alleen-lezen;nullwanneer niet ingesteld).last_updated_atis 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
| Item | Waarde |
|---|---|
| Methode en pad | POST https://www.chatbotty.ai/api/v1/chat |
| Limiet | Klasse Chat: 60 per minuut |
| Quotum | Eén bericht per aanroep; boven het quotum geeft de aanroep 403 QUOTA_EXCEEDED terug |
| MCP-tool | send_message |
Aanvraagbody
| Veld | Verplicht | Beschrijving |
|---|---|---|
message | Ja | De vraag van de bezoeker (niet-lege tekst) |
conversation_id | Nee | Zet een bestaand gesprek voort; laat weg om een nieuw gesprek te starten |
options | Nee | Optioneel 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 pad | Beschrijving | Belangrijkste parameters | MCP-tool |
|---|---|---|---|
GET /documents | Documenten weergeven | limit (standaard 20, max. 100), offset, status | list_documents |
POST /documents | Een document uploaden; geeft 202 terug | Zie hieronder | upload_document |
POST /documents/upload-url | Een ondertekende URL ophalen voor een groot of lokaal bestand | filename | create_upload_url |
GET /documents/{id} | Status en details van één document | - | get_document |
DELETE /documents/{id} | Een document verwijderen | - | delete_document |
GET /documents/{id}/content | De tekst lezen, gepagineerd | offset, limit (standaard 20000, max. 50000) | read_document |
PATCH /documents/{id}/content | Een .md- of .txt-document bewerken | edits, append, expected_hash | edit_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.
| Veld | Beschrijving |
|---|---|
file | Het bestand (alleen multipart) |
content | Tekst van een .md- of .txt-document (JSON; filename verplicht) |
content_base64 | Binair bestand in base64 (JSON; gebruik tot ongeveer 3 MB) |
url | Openbare bestands-URL die de server downloadt (JSON; alleen abonnementen met import via web-URL) |
upload_id | Id van POST /documents/upload-url nadat u het bestand heeft geüpload |
filename | Bestandsnaam met extensie |
description | Optionele beschrijving |
replace_existing | Standaard 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
POST /documents/upload-urlmet{ "filename": "price-list.pdf" }. Het antwoord bevatupload_id,upload_urlen headers; de URL is 2 uur geldig en werkt eenmalig.- Verstuur het ruwe bestand met
PUTnaarupload_url. POST /documentsmet{ "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}/contentverstuurt alleen de wijziging:edits(lijst vanold_textennew_text, elkeold_textmoet precies één keer voorkomen, maximaal 100) en/ofappend(text, optioneelafter_heading).expected_hash(uitGET .../content) beschermt tegen het overschrijven van een nieuwere versie (409 CONFLICT).- Alleen UTF-8
.md- en.txt-documenten kunnen worden bewerkt (anders400 NOT_EDITABLE). - Elke bewerking of vervanging maakt een nieuwe
document_idaan; de oude versie blijft antwoorden totdat de nieuwecompletedis. - Een tweede wijziging terwijl het document nog wordt verwerkt, geeft
409 REPLACE_IN_PROGRESSterug.
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 pad | Beschrijving | Belangrijkste parameters | MCP-tool |
|---|---|---|---|
GET /conversations | Gesprekken weergeven | Zie hieronder | list_conversations |
GET /conversations/{id} | Eén gesprek | - | get_conversation |
GET /conversations/{id}/messages | Berichten in chronologische volgorde | limit (standaard 50, max. 200), offset | get_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
| Parameter | Beschrijving |
|---|---|
limit, offset | Paginering (standaard 20, max. 100) |
status | active, completed of ticket_created |
source | widget of api |
from, to | ISO 8601-datums; filteren op het begin van het gesprek |
quality | Gesprekken met minstens één vraag van dit soort: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
q | Zoeken 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 pad | Beschrijving | MCP-tool |
|---|---|---|
GET /analytics/summary | Totalen voor de periode | get_analytics_summary |
GET /analytics/timeseries | Aantallen per uur, dag of week | get_analytics_timeseries |
GET /analytics/top-queries | Meest gestelde vragen | get_top_queries, list_knowledge_gaps |
Alle drie gebruiken de analyselimiet van 60 aanvragen per minuut (zie Limieten).
Gemeenschappelijke parameters
| Parameter | Beschrijving |
|---|---|
period | today (standaard), week, month of quarter, beoordeeld in de tijdzone van de chatbot |
from, to | ISO 8601-datums; ze vervangen period; het bereik is maximaal 366 dagen |
source | widget of api |
Aanvullende parameters
| Endpoint | Parameter | Beschrijving |
|---|---|---|
timeseries | granularity | auto (standaard), hour, day of week; hour met quarter wordt geweigerd |
top-queries | limit, offset | Paginering (standaard 20, max. 100) |
top-queries | quality | answered, 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 pad | Beschrijving | Belangrijkste parameters | MCP-tool |
|---|---|---|---|
GET /tickets | Tickets weergeven, nieuwste eerst | limit (standaard 20, max. 100), offset, status, conversation_id, from, to | list_tickets |
GET /tickets/{id} | Eén ticket | - | get_ticket |
PATCH /tickets/{id} | De status wijzigen | status in de body | update_ticket_status |
GET /tickets/{id}/notes | Interne notities, oudste eerst | - | list_ticket_notes |
POST /tickets/{id}/notes | Een notitie toevoegen; geeft 201 terug | content in de body | add_ticket_note |
GET-aanroepen gebruiken de leeslimiet (120 per minuut), PATCH en POST de schrijflimiet (60 per minuut); zie Limieten.
Waarden
| Item | Waarde |
|---|---|
| Status | open, in_progress, resolved, closed |
| Notitie | Niet-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 pad | Beschrijving | MCP-tool |
|---|---|---|
GET /webhooks | Webhooks weergeven en het gebruik van uw limieten | list_webhook_actions |
POST /webhooks | Een webhook aanmaken, optioneel met tools; geeft 201 terug | create_webhook_action |
GET /webhooks/{id} | Eén webhook met zijn tools | get_webhook_action |
PATCH /webhooks/{id} | Een webhook wijzigen | update_webhook_action |
DELETE /webhooks/{id} | Een webhook met zijn tools verwijderen | delete_webhook_action |
POST /webhooks/{id}/tools | Een tool toevoegen; geeft 201 terug | add_webhook_tool |
PATCH /webhooks/{id}/tools/{toolId} | Een tool wijzigen | update_webhook_tool |
DELETE /webhooks/{id}/tools/{toolId} | Een tool verwijderen | delete_webhook_tool |
POST /webhooks/{id}/test | De webhook aanroepen zoals de chatbot dat doet | test_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
| Veld | Beschrijving |
|---|---|
name | Verplicht, maximaal 100 tekens |
webhook_url | Verplicht, openbaar HTTPS-adres |
http_method | POST (standaard) of GET |
send_metadata | Standaard true: de aanroep bevat ook tool_name, args en metadata (chatbot_id, conversation_id, timestamp); false verstuurt alleen de argumenten |
timeout_ms | 1000 tot 30000, standaard 10000 |
headers | Maximaal 20 aangepaste headers |
secret_query | Maximaal 10 geheime queryparameters, bijvoorbeeld een API-sleutel |
tools | Tools die de chatbot mag aanroepen (zie hieronder) |
Toolvelden
| Veld | Beschrijving |
|---|---|
name | Kleine letters, cijfers en underscores, begint met een letter, maximaal 64 tekens, uniek per chatbot; create_support_ticket is gereserveerd |
description | Maximaal 500 tekens; vertelt de chatbot wanneer hij de tool moet gebruiken |
parameters | Maximaal 10 items met name, type (string, number, boolean), description (maximaal 200 tekens), required |
Regels
- Waarden van
headersensecret_queryworden nooit teruggegeven, alleen hun namen. Een sleutel die inwebhook_urlwordt gevonden, wordt automatisch naarsecret_queryverplaatst en gemeld inwarnings. - Om het endpoint van een webhook te wijzigen, moet u alle opgeslagen
headers- ensecret_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
| Code | HTTP | Betekenis |
|---|---|---|
UNAUTHORIZED | 401 | Ontbrekende, ongeldige of gedeactiveerde API-sleutel |
QUOTA_EXCEEDED | 403 | Maandelijks berichtenquotum opgebruikt (details.quota_info) |
FORBIDDEN | 403 | De functie zit niet in uw abonnement |
LIMIT_EXCEEDED | 403 | Abonnementslimiet voor webhooks of tools bereikt (details.resource, used, max) |
INVALID_REQUEST | 400 | Ongeldige body of parameters |
INVALID_URL | 400 | Webhook-URL is ongeldig, niet HTTPS of niet openbaar |
INVALID_FILE | 400 | Het bestand ontbreekt bij de upload |
FILE_TOO_LARGE | 400 | Bestand groter dan 10 MB |
UNSUPPORTED_FILE_TYPE | 400 | Alleen .pdf, .docx, .txt, .md worden geaccepteerd |
CONVERSATION_NOT_FOUND | 400 | conversation_id bestaat niet of hoort bij een andere chatbot |
EDIT_FAILED | 400 | Te vervangen tekst niet gevonden, of meer dan één keer gevonden |
NOT_EDITABLE | 400 | Alleen UTF-8 .md- en .txt-documenten kunnen worden bewerkt |
NOT_FOUND | 404 | Document, ticket, webhook, tool of upload niet gevonden, of inactieve chatbot |
DUPLICATE_FILENAME | 409 | Er bestaat al een document met deze naam (details.existing_document_id) |
DUPLICATE_CONTENT | 409 | Dezelfde inhoud is al geïndexeerd |
REPLACE_IN_PROGRESS | 409 | Het document wordt vervangen of verwerkt; wacht tot het completed is |
CONFLICT | 409 | Toolnaam bestaat al, of het document is gewijzigd sinds u het las |
STORAGE_LIMIT_EXCEEDED | 413 | Opslaglimiet van de chatbot overschreden |
RATE_LIMITED | 429 | Te veel aanvragen; zie Limieten |
GONE_USE_V1 | 410 | Het oude endpoint /api/chat is verwijderd; gebruik /api/v1/chat |
INTERNAL_ERROR | 500 | Onverwachte 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
| Item | Waarde |
|---|---|
| Server-URL | https://www.chatbotty.ai/api/mcp |
| Transport | Streamable HTTP via POST |
| Abonnementen | Alle abonnementen; bij elke aanvraag gecontroleerd |
| Limiet | 300 aanvragen per minuut per sleutel (zie Limieten) |
Aanmelden of sleutel
| Methode | Gebruikt door | Hoe |
|---|---|---|
| Aanmelden (OAuth) | claude.ai, Claude Desktop, Claude mobiel, Claude Code | De client opent een Chatbotty-pagina; u meldt zich aan, kiest de chatbot en klikt op Toestaan. Er wordt automatisch een sleutel aangemaakt |
| API-sleutel | n8n, Cursor, VS Code, andere clients | Verstuur 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
| Gebied | Tools |
|---|---|
| Chatbot en chat | get_chatbot_info, send_message |
| Documenten | list_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document |
| Kennishiaten | list_knowledge_gaps |
| Gesprekken | list_conversations, get_conversation, get_conversation_messages |
| Analyses | get_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_messagepraat met de chatbot als een bezoeker en gebruikt het maandelijkse berichtenquotum.test_webhook_actionniet.list_knowledge_gapsgeeft 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)
- Open Instellingen, daarna Connectors, en voeg een aangepaste connector toe.
- Plak de server-URL en klik op Verbinden.
- 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
- Voeg het node MCP Client Tool toe.
- Endpoint: de server-URL.
- Server Transport: HTTP Streamable.
- 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
| Probleem | Controleer |
|---|---|
401 | De sleutel is onjuist, gedeactiveerd of verwijderd |
| Tickets of webhooktools ontbreken | Uw abonnement bevat ze niet |
Handmatige client krijgt 406 | De 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.