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ément | Valeur |
|---|---|
| URL de base REST | https://www.chatbotty.ai/api/v1 |
| URL du serveur MCP | https://www.chatbotty.ai/api/mcp |
| Format | JSON via HTTPS |
| Authentification | Authorization: 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é | Free | Evaluation | Support | Automate |
|---|---|---|---|---|
| Chat, documents, conversations, analytique | Oui | Oui | Oui | Oui |
| Tickets | Non | Oui | Oui | Oui |
| Actions webhook | Non | Oui | Non | Oui |
| Import de documents depuis une URL web | Non | Oui | Oui | Oui |
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 /chatou l'outil MCPsend_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 avecGET /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ément | Valeur |
|---|---|
| Format | Une chaîne hexadécimale aléatoire de 64 caractères |
| Portée | Un chatbot par clé |
| Limite | Jusqu'à 50 clés par chatbot (les clés inactives comptent aussi) |
| Stockage | Seul 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
- Ouvrez API et MCP dans la barre latérale.
- 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.
- 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.
| Action | Effet |
|---|---|
| Désactiver | La clé cesse de fonctionner immédiatement ; Activer la réactive |
| Supprimer | La 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
| Situation | Réponse |
|---|---|
| En-tête manquant ou mal formé | 401 UNAUTHORIZED "Missing or invalid Authorization header" |
| Clé inconnue ou désactivée | 401 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
| Classe | Endpoints | Limite par minute |
|---|---|---|
| Chat | POST /chat | 60 |
| Lecture | Tous les autres endpoints GET sauf l'analytique (y compris GET /chatbot) | 120 |
| Écriture | Endpoints POST, PATCH, DELETE | 60 |
| Analytique | GET /analytics/summary, /analytics/timeseries, /analytics/top-queries | 60 |
| Test de webhook | POST /webhooks/{id}/test | 20 |
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ément | Valeur |
|---|---|
| Méthode et chemin | GET https://www.chatbotty.ai/api/v1/chatbot |
| Paramètres | Aucun |
| Limite de débit | Classe Lecture (voir Limites de débit) |
| Quota | Non utilisé |
| Outil MCP | get_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
planetmessage_quotaappartiennent au propriétaire du compte ; le quota est partagé par tous les chatbots du compte.featuresindique quelles fonctionnalités dépendant du forfait cette clé peut utiliser.handoff_contactest le contact que le chatbot donne lorsqu'il ne connaît pas la réponse (en lecture seule ici ;nulls'il n'est pas défini).last_updated_atest 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ément | Valeur |
|---|---|
| Méthode et chemin | POST https://www.chatbotty.ai/api/v1/chat |
| Limite de débit | Classe Chat : 60 par minute |
| Quota | Un message par appel ; au-delà du quota, l'appel renvoie 403 QUOTA_EXCEEDED |
| Outil MCP | send_message |
Corps de la requête
| Champ | Requis | Description |
|---|---|---|
message | Oui | La question du visiteur (texte non vide) |
conversation_id | Non | Poursuit une conversation existante ; omettez-le pour en démarrer une nouvelle |
options | Non | Objet 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 chemin | Description | Paramètres clés | Outil MCP |
|---|---|---|---|
GET /documents | Lister les documents | limit (20 par défaut, max 100), offset, status | list_documents |
POST /documents | Téléverser un document ; renvoie 202 | Voir ci-dessous | upload_document |
POST /documents/upload-url | Obtenir une URL signée pour un fichier volumineux ou local | filename | create_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}/content | Lire le texte, paginé | offset, limit (20000 par défaut, max 50000) | read_document |
PATCH /documents/{id}/content | Modifier un document .md ou .txt | edits, append, expected_hash | edit_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.
| Champ | Description |
|---|---|
file | Le fichier (multipart uniquement) |
content | Texte d'un document .md ou .txt (JSON ; filename requis) |
content_base64 | Fichier binaire en base64 (JSON ; à utiliser jusqu'à environ 3 Mo) |
url | URL publique d'un fichier que le serveur télécharge (JSON ; forfaits avec import par URL web uniquement) |
upload_id | Identifiant issu de POST /documents/upload-url après le téléversement du fichier |
filename | Nom du fichier avec extension |
description | Description facultative |
replace_existing | true 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
POST /documents/upload-urlavec{ "filename": "price-list.pdf" }. La réponse contientupload_id,upload_urlet des en-têtes ; l'URL est valide 2 heures et ne fonctionne qu'une fois.- Envoyez le fichier brut avec
PUTversupload_url. POST /documentsavec{ "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}/contentenvoie uniquement la modification :edits(liste deold_textetnew_text, chaqueold_textdoit apparaître exactement une fois, jusqu'à 100) et/ouappend(text,after_headingfacultatif).expected_hash(issu deGET .../content) protège contre l'écrasement d'une version plus récente (409 CONFLICT).- Seuls les documents
.mdet.txten UTF-8 peuvent être modifiés (400 NOT_EDITABLEsinon). - Chaque modification ou remplacement crée un nouveau
document_id; l'ancienne version continue de répondre jusqu'à ce que la nouvelle soitcompleted. - 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 chemin | Description | Paramètres clés | Outil MCP |
|---|---|---|---|
GET /conversations | Lister les conversations | Voir ci-dessous | list_conversations |
GET /conversations/{id} | Une conversation | - | get_conversation |
GET /conversations/{id}/messages | Messages par ordre chronologique | limit (50 par défaut, max 200), offset | get_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ètre | Description |
|---|---|
limit, offset | Pagination (20 par défaut, max 100) |
status | active, completed ou ticket_created |
source | widget ou api |
from, to | Dates ISO 8601 ; filtrent sur le début de la conversation |
quality | Conversations comportant au moins une question de ce type : answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
q | Recherche 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 chemin | Description | Outil MCP |
|---|---|---|
GET /analytics/summary | Totaux pour la période | get_analytics_summary |
GET /analytics/timeseries | Nombres par heure, jour ou semaine | get_analytics_timeseries |
GET /analytics/top-queries | Questions les plus fréquentes | get_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ètre | Description |
|---|---|
period | today (par défaut), week, month ou quarter, évalué dans le fuseau horaire du chatbot |
from, to | Dates ISO 8601 ; elles remplacent period ; la plage est de 366 jours au maximum |
source | widget ou api |
Paramètres supplémentaires
| Endpoint | Paramètre | Description |
|---|---|---|
timeseries | granularity | auto (par défaut), hour, day ou week ; hour avec quarter est refusé |
top-queries | limit, offset | Pagination (20 par défaut, max 100) |
top-queries | quality | answered, 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 chemin | Description | Paramètres clés | Outil MCP |
|---|---|---|---|
GET /tickets | Lister les tickets, les plus récents en premier | limit (20 par défaut, max 100), offset, status, conversation_id, from, to | list_tickets |
GET /tickets/{id} | Un ticket | - | get_ticket |
PATCH /tickets/{id} | Changer le statut | status dans le corps | update_ticket_status |
GET /tickets/{id}/notes | Notes internes, les plus anciennes en premier | - | list_ticket_notes |
POST /tickets/{id}/notes | Ajouter une note ; renvoie 201 | content dans le corps | add_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ément | Valeur |
|---|---|
| Statut | open, in_progress, resolved, closed |
| Note | Texte 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 chemin | Description | Outil MCP |
|---|---|---|
GET /webhooks | Lister les webhooks et l'utilisation de vos limites | list_webhook_actions |
POST /webhooks | Créer un webhook, éventuellement avec des outils ; renvoie 201 | create_webhook_action |
GET /webhooks/{id} | Un webhook avec ses outils | get_webhook_action |
PATCH /webhooks/{id} | Modifier un webhook | update_webhook_action |
DELETE /webhooks/{id} | Supprimer un webhook avec ses outils | delete_webhook_action |
POST /webhooks/{id}/tools | Ajouter un outil ; renvoie 201 | add_webhook_tool |
PATCH /webhooks/{id}/tools/{toolId} | Modifier un outil | update_webhook_tool |
DELETE /webhooks/{id}/tools/{toolId} | Supprimer un outil | delete_webhook_tool |
POST /webhooks/{id}/test | Appeler le webhook comme le fait le chatbot | test_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
| Champ | Description |
|---|---|
name | Requis, 100 caractères maximum |
webhook_url | Requis, adresse HTTPS publique |
http_method | POST (par défaut) ou GET |
send_metadata | true par défaut : l'appel transmet aussi tool_name, args et metadata (chatbot_id, conversation_id, timestamp) ; false n'envoie que les arguments |
timeout_ms | 1000 à 30000, 10000 par défaut |
headers | Jusqu'à 20 en-têtes personnalisés |
secret_query | Jusqu'à 10 paramètres de requête secrets, par exemple une clé API |
tools | Outils que le chatbot peut appeler (voir ci-dessous) |
Champs de l'outil
| Champ | Description |
|---|---|
name | Lettres minuscules, chiffres et tirets bas, commence par une lettre, 64 caractères maximum, unique par chatbot ; create_support_ticket est réservé |
description | 500 caractères maximum ; indique au chatbot quand utiliser l'outil |
parameters | Jusqu'à 10 éléments avec name, type (string, number, boolean), description (200 caractères maximum), required |
Règles
- Les valeurs de
headersetsecret_queryne sont jamais renvoyées, seulement leurs noms. Une clé trouvée danswebhook_urlest automatiquement déplacée verssecret_queryet signalée danswarnings. - Modifier l'endpoint d'un webhook exige de renvoyer toutes les clés
headersetsecret_queryenregistré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
| Code | HTTP | Signification |
|---|---|---|
UNAUTHORIZED | 401 | Clé API manquante, invalide ou désactivée |
QUOTA_EXCEEDED | 403 | Quota mensuel de messages épuisé (details.quota_info) |
FORBIDDEN | 403 | La fonctionnalité n'est pas incluse dans votre forfait |
LIMIT_EXCEEDED | 403 | Limite du forfait pour les webhooks ou les outils atteinte (details.resource, used, max) |
INVALID_REQUEST | 400 | Corps ou paramètres invalides |
INVALID_URL | 400 | L'URL du webhook est invalide, n'est pas en HTTPS ou n'est pas publique |
INVALID_FILE | 400 | Le fichier est absent du téléversement |
FILE_TOO_LARGE | 400 | Fichier de plus de 10 Mo |
UNSUPPORTED_FILE_TYPE | 400 | Seuls .pdf, .docx, .txt, .md sont acceptés |
CONVERSATION_NOT_FOUND | 400 | conversation_id n'existe pas ou appartient à un autre chatbot |
EDIT_FAILED | 400 | Texte à remplacer introuvable, ou trouvé plus d'une fois |
NOT_EDITABLE | 400 | Seuls les documents .md et .txt en UTF-8 peuvent être modifiés |
NOT_FOUND | 404 | Document, ticket, webhook, outil ou téléversement introuvable, ou chatbot inactif |
DUPLICATE_FILENAME | 409 | Un document portant ce nom existe (details.existing_document_id) |
DUPLICATE_CONTENT | 409 | Le même contenu est déjà indexé |
REPLACE_IN_PROGRESS | 409 | Le document est en cours de remplacement ou de traitement ; attendez qu'il soit completed |
CONFLICT | 409 | Le nom de l'outil existe déjà, ou le document a changé depuis votre lecture |
STORAGE_LIMIT_EXCEEDED | 413 | Limite de stockage du chatbot dépassée |
RATE_LIMITED | 429 | Trop de requêtes ; voir Limites de débit |
GONE_USE_V1 | 410 | L'ancien endpoint /api/chat a été supprimé ; utilisez /api/v1/chat |
INTERNAL_ERROR | 500 | Erreur 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ément | Valeur |
|---|---|
| URL du serveur | https://www.chatbotty.ai/api/mcp |
| Transport | Streamable HTTP via POST |
| Forfaits | Tous les forfaits ; vérifié à chaque requête |
| Limite | 300 requêtes par minute et par clé (voir Limites de débit) |
Connexion ou clé
| Méthode | Utilisée par | Comment |
|---|---|---|
| Connexion (OAuth) | claude.ai, Claude Desktop, Claude mobile, Claude Code | Le client ouvre une page Chatbotty ; vous vous connectez, choisissez le chatbot et cliquez sur Autoriser. Une clé est créée automatiquement |
| Clé API | n8n, Cursor, VS Code, autres clients | Envoyez 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
| Domaine | Outils |
|---|---|
| Chatbot et chat | get_chatbot_info, send_message |
| Documents | list_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document |
| Lacunes de connaissances | list_knowledge_gaps |
| Conversations | list_conversations, get_conversation, get_conversation_messages |
| Analytique | get_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_messages'adresse au chatbot comme un visiteur et utilise le quota mensuel de messages.test_webhook_actionne l'utilise pas.list_knowledge_gapsliste 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)
- Ouvrez Paramètres, puis Connecteurs, puis ajoutez un connecteur personnalisé.
- Collez l'URL du serveur et cliquez sur Connecter.
- 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
- Ajoutez le nœud MCP Client Tool.
- Endpoint : l'URL du serveur.
- Server Transport : HTTP Streamable.
- 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ème | Vérification |
|---|---|
401 | La clé est erronée, désactivée ou supprimée |
| Outils de tickets ou de webhook absents | Votre forfait ne les inclut pas |
Un client manuel reçoit 406 | Le 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.