← Retour à l'application

API & MCP

Pilotez votre chatbot depuis votre propre code ou depuis des assistants IA.

Vue d'ensemble#

Chatbotty peut être utilisé et géré depuis l'extérieur du tableau de bord de deux façons : l'API REST pour votre propre code et le connecteur MCP pour les assistants IA tels que Claude. Les deux fonctionnent avec un seul chatbot à la fois et utilisent les mêmes clés API. Commencez par Authentification.

Notions de base

ÉlémentValeur
URL de base RESThttps://www.chatbotty.ai/api/v1
URL du serveur MCPhttps://www.chatbotty.ai/api/mcp
FormatJSON via HTTPS
AuthentificationAuthorization: Bearer YOUR_API_KEY
Portée d'une cléUne clé appartient à exactement un chatbot ; le chatbot n'est jamais envoyé dans la requête, il est déduit de la clé

Lequel utiliser

  • API REST - vous écrivez du code qui envoie des messages de chat ou gère les documents, conversations, tickets et actions webhook. Voir Chatbot et les sections d'endpoints suivantes.
  • Connecteur MCP - vous connectez un assistant IA et le laissez travailler avec le chatbot sans coder. Voir Connecteur MCP et Clients MCP.

Forfaits

Les clés API, l'API REST et le connecteur MCP sont disponibles avec tous les forfaits : Free, Evaluation, Support et Automate. Les fonctionnalités individuelles dépendent du forfait.

FonctionnalitéFreeEvaluationSupportAutomate
Chat, documents, conversations, analytiqueOuiOuiOuiOui
TicketsNonOuiOuiOui
Actions webhookNonOuiNonOui
Import de documents depuis une URL webNonOuiOuiOui

Un appel à une fonctionnalité absente de votre forfait renvoie 403 FORBIDDEN. Le connecteur MCP ne propose tout simplement pas ces outils. Un changement de forfait s'applique à la requête suivante.

Quota

  • Seuls les messages envoyés via le chat (REST POST /chat ou l'outil MCP send_message) sont décomptés du quota mensuel de messages, exactement comme les messages du widget.
  • Les autres appels (documents, conversations, analytique, tickets, actions webhook) n'utilisent pas le quota.
  • Lorsque le quota est épuisé, l'appel de chat renvoie 403 QUOTA_EXCEEDED. Vérifiez le quota restant avec GET /chatbot.
  • Les clés fonctionnent indépendamment des domaines autorisés du chatbot et même lorsque le chatbot est inactif pour le widget (sauf pour l'envoi de messages de chat, qu'un chatbot inactif refuse avec 404 NOT_FOUND).

Format de réponse

Chaque réponse REST utilise la même enveloppe. Les erreurs sont décrites dans Erreurs.

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

Authentification#

Chaque requête doit porter une clé API du chatbot en tant que jeton Bearer. La même clé fonctionne pour l'API REST et pour le connecteur MCP.

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

Clés API

ÉlémentValeur
FormatUne chaîne hexadécimale aléatoire de 64 caractères
PortéeUn chatbot par clé
LimiteJusqu'à 50 clés par chatbot (les clés inactives comptent aussi)
StockageSeul un hachage est stocké ; la clé complète n'est affichée qu'une fois, juste après sa création

Traitez les clés comme des mots de passe : ne les partagez jamais et ne les placez jamais dans du code côté client.

Gérer les clés dans le tableau de bord

  1. Ouvrez API et MCP dans la barre latérale.
  2. Sur la carte de votre chatbot, cliquez sur Créer une nouvelle clé API, saisissez un nom (par exemple « Production app ») et cliquez sur Créer.
  3. Copiez la clé immédiatement. Elle ne peut plus être affichée ensuite (« Copiez cette clé maintenant. Vous ne pourrez plus la voir ensuite. »).

Ensuite, la liste affiche le nom de la clé, ses 12 premiers caractères et Dernière utilisation.

ActionEffet
DésactiverLa clé cesse de fonctionner immédiatement ; Activer la réactive
SupprimerLa clé est supprimée définitivement ; les applications qui l'utilisent cessent aussitôt de fonctionner

Les clés créées en connectant un assistant IA portent l'étiquette Connecteur MCP. Supprimer une telle clé déconnecte l'assistant. Connecter à nouveau le même assistant au même chatbot remplace son ancienne clé.

Erreurs d'authentification

SituationRéponse
En-tête manquant ou mal formé401 UNAUTHORIZED "Missing or invalid Authorization header"
Clé inconnue ou désactivée401 UNAUTHORIZED "Invalid or inactive API key"

Voir Erreurs pour tous les codes et Limites de débit pour les limites de requêtes.

Limites de débit#

Les limites s'appliquent par clé API et par minute. Chaque classe d'endpoints a son propre compteur : de nombreuses écritures n'épuisent donc pas le budget des lectures.

API REST

ClasseEndpointsLimite par minute
ChatPOST /chat60
LectureTous les autres endpoints GET sauf l'analytique (y compris GET /chatbot)120
ÉcritureEndpoints POST, PATCH, DELETE60
AnalytiqueGET /analytics/summary, /analytics/timeseries, /analytics/top-queries60
Test de webhookPOST /webhooks/{id}/test20

Limite supplémentaire : POST /documents/upload-url délivre au plus 50 URL de téléversement par chatbot en 2 heures.

Connecteur MCP

L'endpoint MCP autorise 300 requêtes par minute et par clé. Chaque appel d'outil est ensuite soumis à la limite REST de l'endpoint qu'il utilise, et send_message utilise le quota de messages.

Lorsque vous dépassez une limite

L'API renvoie 429 RATE_LIMITED avec un message tel que « Rate limit exceeded. Maximum 60 requests per minute per API key. » Attendez la minute suivante et réessayez, idéalement avec un délai croissant.

Les limites de débit sont distinctes du quota mensuel de messages ; voir Vue d'ensemble et Erreurs.

Chatbot#

Identifiez le chatbot auquel appartient votre clé API et vérifiez son forfait et son quota avant de commencer à travailler avec lui.

GET /chatbot

ÉlémentValeur
Méthode et cheminGET https://www.chatbotty.ai/api/v1/chatbot
ParamètresAucun
Limite de débitClasse Lecture (voir Limites de débit)
QuotaNon utilisé
Outil MCPget_chatbot_info

Réponse

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

Remarques

  • plan et message_quota appartiennent au propriétaire du compte ; le quota est partagé par tous les chatbots du compte.
  • features indique quelles fonctionnalités dépendant du forfait cette clé peut utiliser.
  • handoff_contact est le contact que le chatbot donne lorsqu'il ne connaît pas la réponse (en lecture seule ici ; null s'il n'est pas défini).
  • last_updated_at est l'heure du document téléversé le plus récent.

Chat#

Envoyez un message au chatbot et recevez sa réponse, exactement comme un visiteur dans le widget.

POST /chat

ÉlémentValeur
Méthode et cheminPOST https://www.chatbotty.ai/api/v1/chat
Limite de débitClasse Chat : 60 par minute
QuotaUn message par appel ; au-delà du quota, l'appel renvoie 403 QUOTA_EXCEEDED
Outil MCPsend_message

Corps de la requête

ChampRequisDescription
messageOuiLa question du visiteur (texte non vide)
conversation_idNonPoursuit une conversation existante ; omettez-le pour en démarrer une nouvelle
optionsNonObjet facultatif ; inutile pour un usage normal

Si conversation_id n'existe pas ou appartient à un autre chatbot, l'appel renvoie 400 CONVERSATION_NOT_FOUND. Un chatbot qui n'est pas actif renvoie 404 NOT_FOUND.

Réponse

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

Contexte de la conversation

Le premier appel crée une conversation et renvoie son conversation_id. Envoyez cet identifiant avec chaque message suivant pour conserver le contexte. Les conversations créées via l'API apparaissent dans le tableau de bord avec la source api.

tools_executed

metadata.tools_executed liste les outils que le chatbot a appelés pendant sa réponse (actions webhook, création de ticket de support). Chaque élément comporte name, ok et, en cas d'échec, un court code tel que webhook_timeout, webhook_redirect, webhook_blocked ou invalid_args. Une liste vide signifie qu'aucun outil n'a été appelé. Utilisez-la pour vérifier qu'une action webhook s'est réellement exécutée.

Documents#

Gérez la base de connaissances du chatbot : téléversez, lisez, modifiez, listez et supprimez des documents. Ces appels n'utilisent pas le quota de messages.

Endpoints

Méthode et cheminDescriptionParamètres clésOutil MCP
GET /documentsLister les documentslimit (20 par défaut, max 100), offset, statuslist_documents
POST /documentsTéléverser un document ; renvoie 202Voir ci-dessousupload_document
POST /documents/upload-urlObtenir une URL signée pour un fichier volumineux ou localfilenamecreate_upload_url
GET /documents/{id}Statut et détails d'un document-get_document
DELETE /documents/{id}Supprimer un document-delete_document
GET /documents/{id}/contentLire le texte, paginéoffset, limit (20000 par défaut, max 50000)read_document
PATCH /documents/{id}/contentModifier un document .md ou .txtedits, append, expected_hashedit_document, append_to_document

Limites : les appels GET utilisent la limite de lecture, les autres la limite d'écriture (voir Limites de débit).

Téléversement

Types autorisés : .pdf, .docx, .txt, .md, jusqu'à 10 Mo. Envoyez soit du multipart/form-data, soit du JSON.

ChampDescription
fileLe fichier (multipart uniquement)
contentTexte d'un document .md ou .txt (JSON ; filename requis)
content_base64Fichier binaire en base64 (JSON ; à utiliser jusqu'à environ 3 Mo)
urlURL publique d'un fichier que le serveur télécharge (JSON ; forfaits avec import par URL web uniquement)
upload_idIdentifiant issu de POST /documents/upload-url après le téléversement du fichier
filenameNom du fichier avec extension
descriptionDescription facultative
replace_existingtrue par défaut : un fichier du même nom est remplacé par la nouvelle version

En JSON, envoyez exactement un seul parmi content, content_base64, url, upload_id.

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

Fichiers volumineux ou locaux

  1. POST /documents/upload-url avec { "filename": "price-list.pdf" }. La réponse contient upload_id, upload_url et des en-têtes ; l'URL est valide 2 heures et ne fonctionne qu'une fois.
  2. Envoyez le fichier brut avec PUT vers upload_url.
  3. POST /documents avec { "upload_id": "...", "filename": "price-list.pdf" }.

Traitement et statut

Le traitement est asynchrone. Le statut passe de pending à processing puis à completed, ou se termine par failed avec un error_message. Un document en échec reste dans la liste ; supprimez-le ou téléversez-le à nouveau. Interrogez GET /documents/{id} jusqu'à completed.

Modifier et remplacer

  • PATCH /documents/{id}/content envoie uniquement la modification : edits (liste de old_text et new_text, chaque old_text doit apparaître exactement une fois, jusqu'à 100) et/ou append (text, after_heading facultatif).
  • expected_hash (issu de GET .../content) protège contre l'écrasement d'une version plus récente (409 CONFLICT).
  • Seuls les documents .md et .txt en UTF-8 peuvent être modifiés (400 NOT_EDITABLE sinon).
  • Chaque modification ou remplacement crée un nouveau document_id ; l'ancienne version continue de répondre jusqu'à ce que la nouvelle soit completed.
  • Une seconde modification pendant que le document est encore en cours de traitement renvoie 409 REPLACE_IN_PROGRESS.

Conversations#

Lisez l'historique des conversations du chatbot, y compris celles créées dans le widget. Ces appels sont en lecture seule et n'utilisent pas le quota de messages.

Endpoints

Méthode et cheminDescriptionParamètres clésOutil MCP
GET /conversationsLister les conversationsVoir ci-dessouslist_conversations
GET /conversations/{id}Une conversation-get_conversation
GET /conversations/{id}/messagesMessages par ordre chronologiquelimit (50 par défaut, max 200), offsetget_conversation_messages

Les trois utilisent la limite de lecture de 120 requêtes par minute (voir Limites de débit). Une conversation d'un autre chatbot renvoie 404 NOT_FOUND.

Filtres de liste

ParamètreDescription
limit, offsetPagination (20 par défaut, max 100)
statusactive, completed ou ticket_created
sourcewidget ou api
from, toDates ISO 8601 ; filtrent sur le début de la conversation
qualityConversations comportant au moins une question de ce type : answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified
qRecherche en texte intégral dans le texte des messages (2 à 200 caractères)

Réponse

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

Avec les forfaits comportant les tickets, le détail d'une conversation contient aussi les tickets créés dans celle-ci. Les messages comportent id, role (user ou assistant), content et created_at.

Astuce

Pour trouver les questions auxquelles le chatbot n'a pas su répondre, utilisez GET /analytics/top-queries?quality=not_answered (voir Analytique) et ouvrez les conversations associées via conversation_ids.

Analytique#

Statistiques agrégées du chatbot. L'analytique est disponible avec tous les forfaits, Free compris. Ces appels n'utilisent pas le quota de messages.

Endpoints

Méthode et cheminDescriptionOutil MCP
GET /analytics/summaryTotaux pour la périodeget_analytics_summary
GET /analytics/timeseriesNombres par heure, jour ou semaineget_analytics_timeseries
GET /analytics/top-queriesQuestions les plus fréquentesget_top_queries, list_knowledge_gaps

Les trois utilisent la limite d'analytique de 60 requêtes par minute (voir Limites de débit).

Paramètres communs

ParamètreDescription
periodtoday (par défaut), week, month ou quarter, évalué dans le fuseau horaire du chatbot
from, toDates ISO 8601 ; elles remplacent period ; la plage est de 366 jours au maximum
sourcewidget ou api

Paramètres supplémentaires

EndpointParamètreDescription
timeseriesgranularityauto (par défaut), hour, day ou week ; hour avec quarter est refusé
top-querieslimit, offsetPagination (20 par défaut, max 100)
top-queriesqualityanswered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified

Réponse de 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 correspond au nombre de réponses divisé par la somme des réponses et des questions sans réponse, en pourcentage.

Questions sans réponse

GET /analytics/top-queries?quality=not_answered&period=month renvoie les questions auxquelles le chatbot n'a pas su répondre, les plus fréquentes en premier. Chaque élément comporte content, count, last_asked et jusqu'à 5 conversation_ids que vous pouvez ouvrir via les conversations. Ajoutez les faits manquants à la base de connaissances et vérifiez le résultat avec le chat.

Tickets#

Lisez les tickets de support, changez leur statut et ajoutez des notes internes. Les tickets sont disponibles avec les forfaits Evaluation, Support et Automate ; Free renvoie 403 FORBIDDEN. Les tickets ne peuvent pas être créés via l'API : le chatbot les crée pendant une conversation.

Endpoints

Méthode et cheminDescriptionParamètres clésOutil MCP
GET /ticketsLister les tickets, les plus récents en premierlimit (20 par défaut, max 100), offset, status, conversation_id, from, tolist_tickets
GET /tickets/{id}Un ticket-get_ticket
PATCH /tickets/{id}Changer le statutstatus dans le corpsupdate_ticket_status
GET /tickets/{id}/notesNotes internes, les plus anciennes en premier-list_ticket_notes
POST /tickets/{id}/notesAjouter une note ; renvoie 201content dans le corpsadd_ticket_note

Les appels GET utilisent la limite de lecture (120 par minute), PATCH et POST la limite d'écriture (60 par minute) ; voir Limites de débit.

Valeurs

ÉlémentValeur
Statutopen, in_progress, resolved, closed
NoteTexte non vide, jusqu'à 5000 caractères

Un statut invalide renvoie 400 INVALID_REQUEST. Un ticket d'un autre chatbot renvoie 404 NOT_FOUND.

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

Exemple

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

Actions webhook#

Gérez les actions webhook du chatbot : API externes ou webhooks d'automatisation (par exemple n8n) que le chatbot appelle comme des outils pendant qu'il répond. Disponibles avec le forfait Automate (10 webhooks et 10 outils par chatbot) et l'essai Evaluation (5 webhooks et 5 outils par chatbot). Les autres forfaits reçoivent 403 FORBIDDEN ; le dépassement des limites renvoie 403 LIMIT_EXCEEDED. Les appels n'utilisent pas le quota de messages.

Endpoints

Méthode et cheminDescriptionOutil MCP
GET /webhooksLister les webhooks et l'utilisation de vos limiteslist_webhook_actions
POST /webhooksCréer un webhook, éventuellement avec des outils ; renvoie 201create_webhook_action
GET /webhooks/{id}Un webhook avec ses outilsget_webhook_action
PATCH /webhooks/{id}Modifier un webhookupdate_webhook_action
DELETE /webhooks/{id}Supprimer un webhook avec ses outilsdelete_webhook_action
POST /webhooks/{id}/toolsAjouter un outil ; renvoie 201add_webhook_tool
PATCH /webhooks/{id}/tools/{toolId}Modifier un outilupdate_webhook_tool
DELETE /webhooks/{id}/tools/{toolId}Supprimer un outildelete_webhook_tool
POST /webhooks/{id}/testAppeler le webhook comme le fait le chatbottest_webhook_action

Les lectures utilisent la limite de lecture (120 par minute), les modifications la limite d'écriture (60), et le test a sa propre limite de 20 par minute ; voir Limites de débit. L'outil MCP get_webhook_guide renvoie un court guide destiné aux assistants IA.

Champs du webhook

ChampDescription
nameRequis, 100 caractères maximum
webhook_urlRequis, adresse HTTPS publique
http_methodPOST (par défaut) ou GET
send_metadatatrue par défaut : l'appel transmet aussi tool_name, args et metadata (chatbot_id, conversation_id, timestamp) ; false n'envoie que les arguments
timeout_ms1000 à 30000, 10000 par défaut
headersJusqu'à 20 en-têtes personnalisés
secret_queryJusqu'à 10 paramètres de requête secrets, par exemple une clé API
toolsOutils que le chatbot peut appeler (voir ci-dessous)

Champs de l'outil

ChampDescription
nameLettres minuscules, chiffres et tirets bas, commence par une lettre, 64 caractères maximum, unique par chatbot ; create_support_ticket est réservé
description500 caractères maximum ; indique au chatbot quand utiliser l'outil
parametersJusqu'à 10 éléments avec name, type (string, number, boolean), description (200 caractères maximum), required

Règles

  • Les valeurs de headers et secret_query ne sont jamais renvoyées, seulement leurs noms. Une clé trouvée dans webhook_url est automatiquement déplacée vers secret_query et signalée dans warnings.
  • Modifier l'endpoint d'un webhook exige de renvoyer toutes les clés headers et secret_query enregistrées, afin que des secrets ne puissent pas être déplacés vers un autre serveur à votre insu.
  • Le chatbot effectue un seul tour d'appels d'outils par réponse. Une réponse est tronquée à 10 Ko, les redirections ne sont pas suivies et les adresses internes sont refusées.

Test

POST /webhooks/{id}/test avec un corps facultatif { "tool_name": "get_weather", "arguments": { "q": "Prague" } } renvoie ok, status, response_time_ms, body_preview (les 2 premiers Ko), truncated et warnings. Après un test, posez au chatbot une question correspondante via le chat et vérifiez tools_executed.

Erreurs#

Les appels REST en échec renvoient un statut HTTP non 2xx et cette enveloppe :

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

details n'est présent que pour certaines erreurs. Traitez les erreurs selon code ; les messages peuvent changer.

Codes d'erreur

CodeHTTPSignification
UNAUTHORIZED401Clé API manquante, invalide ou désactivée
QUOTA_EXCEEDED403Quota mensuel de messages épuisé (details.quota_info)
FORBIDDEN403La fonctionnalité n'est pas incluse dans votre forfait
LIMIT_EXCEEDED403Limite du forfait pour les webhooks ou les outils atteinte (details.resource, used, max)
INVALID_REQUEST400Corps ou paramètres invalides
INVALID_URL400L'URL du webhook est invalide, n'est pas en HTTPS ou n'est pas publique
INVALID_FILE400Le fichier est absent du téléversement
FILE_TOO_LARGE400Fichier de plus de 10 Mo
UNSUPPORTED_FILE_TYPE400Seuls .pdf, .docx, .txt, .md sont acceptés
CONVERSATION_NOT_FOUND400conversation_id n'existe pas ou appartient à un autre chatbot
EDIT_FAILED400Texte à remplacer introuvable, ou trouvé plus d'une fois
NOT_EDITABLE400Seuls les documents .md et .txt en UTF-8 peuvent être modifiés
NOT_FOUND404Document, ticket, webhook, outil ou téléversement introuvable, ou chatbot inactif
DUPLICATE_FILENAME409Un document portant ce nom existe (details.existing_document_id)
DUPLICATE_CONTENT409Le même contenu est déjà indexé
REPLACE_IN_PROGRESS409Le document est en cours de remplacement ou de traitement ; attendez qu'il soit completed
CONFLICT409Le nom de l'outil existe déjà, ou le document a changé depuis votre lecture
STORAGE_LIMIT_EXCEEDED413Limite de stockage du chatbot dépassée
RATE_LIMITED429Trop de requêtes ; voir Limites de débit
GONE_USE_V1410L'ancien endpoint /api/chat a été supprimé ; utilisez /api/v1/chat
INTERNAL_ERROR500Erreur serveur inattendue

Erreurs MCP

L'endpoint MCP répond avec des erreurs JSON-RPC : 401 pour un jeton manquant ou invalide, 429 pour trop de requêtes et 403 lorsque le forfait n'inclut pas MCP. Lorsqu'un outil échoue, le résultat est marqué comme une erreur et contient le code de l'API, par exemple Chatbotty API error [NOT_FOUND] (HTTP 404). Voir Connecteur MCP.

Support

Si une erreur persiste, écrivez à support@chatbotty.ai en indiquant le code, l'heure et l'endpoint.

Connecteur MCP#

Le connecteur MCP permet à un assistant IA tel que Claude, n8n ou Cursor de travailler avec votre chatbot : discuter avec lui, gérer sa base de connaissances, configurer des actions webhook et lire les conversations, l'analytique et les tickets. Un connecteur appartient à un seul chatbot ; pour utiliser un autre chatbot, ajoutez un autre connecteur.

Connexion

ÉlémentValeur
URL du serveurhttps://www.chatbotty.ai/api/mcp
TransportStreamable HTTP via POST
ForfaitsTous les forfaits ; vérifié à chaque requête
Limite300 requêtes par minute et par clé (voir Limites de débit)

Connexion ou clé

MéthodeUtilisée parComment
Connexion (OAuth)claude.ai, Claude Desktop, Claude mobile, Claude CodeLe client ouvre une page Chatbotty ; vous vous connectez, choisissez le chatbot et cliquez sur Autoriser. Une clé est créée automatiquement
Clé APIn8n, Cursor, VS Code, autres clientsEnvoyez l'en-tête Authorization: Bearer YOUR_API_KEY (Authentification)

Une clé créée par la connexion porte l'étiquette Connecteur MCP dans API et MCP. Supprimez-la à cet endroit pour déconnecter l'assistant. Les tickets et les outils webhook n'apparaissent que si votre forfait les inclut. Les étapes de configuration se trouvent dans Clients MCP.

Outils

DomaineOutils
Chatbot et chatget_chatbot_info, send_message
Documentslist_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document
Lacunes de connaissanceslist_knowledge_gaps
Conversationslist_conversations, get_conversation, get_conversation_messages
Analytiqueget_analytics_summary, get_analytics_timeseries, get_top_queries
Tickets (forfaits avec tickets)list_tickets, get_ticket, update_ticket_status, list_ticket_notes, add_ticket_note
Actions webhook (forfaits avec actions 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

Chaque outil fonctionne comme l'endpoint REST correspondant décrit dans les sections précédentes et a les mêmes limites et erreurs.

À savoir

  • send_message s'adresse au chatbot comme un visiteur et utilise le quota mensuel de messages. test_webhook_action ne l'utilise pas.
  • list_knowledge_gaps liste les questions auxquelles le chatbot n'a pas su répondre et exige une période ; utilisez-le pour trouver ce qu'il faut ajouter à la base de connaissances.
  • Un client peut mettre en cache les descriptions des outils. Si les outils semblent obsolètes, retirez le connecteur et ajoutez-le à nouveau.

Clients MCP#

Comment connecter les clients courants à https://www.chatbotty.ai/api/mcp. Pour les clients qui envoient une clé, créez-la d'abord comme décrit dans Authentification. Contexte : Connecteur MCP.

Claude (claude.ai, Claude Desktop, mobile)

  1. Ouvrez Paramètres, puis Connecteurs, puis ajoutez un connecteur personnalisé.
  2. Collez l'URL du serveur et cliquez sur Connecter.
  3. Connectez-vous à Chatbotty, choisissez le chatbot et cliquez sur Autoriser.

Aucune clé API n'est nécessaire. Le connecteur fonctionne ensuite aussi dans l'application mobile Claude.

Claude Code

Connexion via le navigateur :

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

Ou avec une clé API :

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

Lorsque la page de connexion avertit que l'application s'exécute sur votre propre ordinateur, n'autorisez l'accès que si vous avez vous-même lancé la connexion.

n8n

  1. Ajoutez le nœud MCP Client Tool.
  2. Endpoint : l'URL du serveur.
  3. Server Transport : HTTP Streamable.
  4. Authentication : Bearer Auth avec votre clé API.

Cursor, VS Code et autres clients

Ajoutez un serveur MCP distant avec l'URL du serveur et l'en-tête Authorization: Bearer YOUR_API_KEY. Dans Cursor, par exemple :

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

Dépannage

ProblèmeVérification
401La clé est erronée, désactivée ou supprimée
Outils de tickets ou de webhook absentsVotre forfait ne les inclut pas
Un client manuel reçoit 406Le client doit envoyer Accept: application/json, text/event-stream

Exemples#

Exemples à copier-coller pour les tâches les plus courantes. Remplacez YOUR_API_KEY par une clé issue de API et MCP et https://www.chatbotty.ai par l'URL de base. Voir Authentification.

Vérifier le chatbot et le quota

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

Poser une question et poursuivre la conversation

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

Prenez conversation_id dans la réponse et envoyez-le avec le message suivant :

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

Téléverser un document

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

Vérifiez ensuite le statut jusqu'à completed :

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

Trouver les questions sans réponse

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

Lister les conversations contenant un mot

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

Gérer les erreurs

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

Branchez votre logique sur error.code et consultez Erreurs. Pour les limites, voir Limites de débit. Questions : support@chatbotty.ai.