API & MCP
Controle su chatbot desde su propio código o desde asistentes de IA.
Visión general#
Chatbotty se puede utilizar y gestionar desde fuera del panel de dos maneras: la REST API para su propio código y el conector MCP para asistentes de IA como Claude. Ambos funcionan con un solo chatbot a la vez y utilizan las mismas claves API. Empiece por Autenticación.
Conceptos básicos
| Elemento | Valor |
|---|---|
| URL base de REST | https://www.chatbotty.ai/api/v1 |
| URL del servidor MCP | https://www.chatbotty.ai/api/mcp |
| Formato | JSON sobre HTTPS |
| Autenticación | Authorization: Bearer YOUR_API_KEY |
| Ámbito de una clave | Una clave pertenece exactamente a un chatbot; el chatbot nunca se envía en la solicitud, se deduce de la clave |
Cuál utilizar
- REST API - usted escribe código que envía mensajes de chat o gestiona documentos, conversaciones, tickets y acciones de webhook. Consulte Chatbot y las secciones de endpoints siguientes.
- Conector MCP - usted conecta un asistente de IA y le deja trabajar con el chatbot sin programar. Consulte Conector MCP y Clientes MCP.
Planes
Las claves API, la REST API y el conector MCP están disponibles en todos los planes: Free, Evaluation, Support y Automate. Las funciones concretas dependen del plan.
| Función | Free | Evaluation | Support | Automate |
|---|---|---|---|---|
| Chat, documentos, conversaciones, analíticas | Sí | Sí | Sí | Sí |
| Tickets | No | Sí | Sí | Sí |
| Acciones de webhook | No | Sí | No | Sí |
| Importación de documentos desde una URL web | No | Sí | Sí | Sí |
Una llamada a una función que no está en su plan devuelve 403 FORBIDDEN. El conector MCP ni siquiera ofrece esas herramientas. Un cambio de plan se aplica a la siguiente solicitud.
Cuota
- Solo los mensajes enviados a través del chat (REST
POST /chato la herramienta MCPsend_message) cuentan para la cuota mensual de mensajes, exactamente igual que los mensajes del widget. - Las demás llamadas (documentos, conversaciones, analíticas, tickets, acciones de webhook) no consumen cuota.
- Cuando se agota la cuota, la llamada de chat devuelve
403 QUOTA_EXCEEDED. Compruebe la cuota restante conGET /chatbot. - Las claves funcionan con independencia de los dominios permitidos del chatbot e incluso cuando el chatbot está inactivo para el widget (excepto el envío de mensajes de chat, que un chatbot inactivo rechaza con
404 NOT_FOUND).
Formato de la respuesta
Todas las respuestas REST utilizan la misma estructura. Los errores se describen en Errores.
{ "success": true, "data": { }, "timestamp": "2026-01-01T10:00:00.000Z" }
Autenticación#
Cada solicitud debe llevar una clave API del chatbot como token Bearer. La misma clave sirve para la REST API y para el conector MCP.
curl -H "Authorization: Bearer YOUR_API_KEY" https://www.chatbotty.ai/api/v1/chatbot
Claves API
| Elemento | Valor |
|---|---|
| Formato | Una cadena hexadecimal aleatoria de 64 caracteres |
| Ámbito | Un chatbot por clave |
| Límite | Hasta 50 claves por chatbot (las claves inactivas también cuentan) |
| Almacenamiento | Solo se almacena un hash; la clave completa se muestra una sola vez, justo después de crearla |
Trate las claves como contraseñas: no las comparta nunca ni las incluya en código del lado del cliente.
Gestionar las claves en el panel
- Abra API y MCP en la barra lateral.
- En la tarjeta de su chatbot, haga clic en Crear nueva clave API, introduzca un nombre (por ejemplo "Production app") y haga clic en Crear.
- Copie la clave de inmediato. No se puede volver a mostrar ("Copia esta clave ahora. No podrás verla de nuevo.").
Después, la lista muestra el nombre de la clave, sus primeros 12 caracteres y Último uso.
| Acción | Efecto |
|---|---|
| Desactivar | La clave deja de funcionar al instante; Activar la vuelve a activar |
| Eliminar | La clave se elimina de forma permanente; las aplicaciones que la utilicen dejan de funcionar de inmediato |
Las claves creadas al conectar un asistente de IA se etiquetan como Conector MCP. Eliminar una clave así desconecta el asistente. Conectar de nuevo el mismo asistente al mismo chatbot sustituye su clave anterior.
Errores de autenticación
| Situación | Respuesta |
|---|---|
| Encabezado ausente o mal formado | 401 UNAUTHORIZED "Missing or invalid Authorization header" |
| Clave desconocida o desactivada | 401 UNAUTHORIZED "Invalid or inactive API key" |
Consulte Errores para ver todos los códigos y Límites de solicitudes para los límites de solicitudes.
Límites de solicitudes#
Los límites se aplican por clave API y por minuto. Cada clase de endpoints tiene su propio contador, de modo que muchas escrituras no agotan el presupuesto de las lecturas.
REST API
| Clase | Endpoints | Límite por minuto |
|---|---|---|
| Chat | POST /chat | 60 |
| Lectura | Todos los demás endpoints GET excepto analíticas (incluido GET /chatbot) | 120 |
| Escritura | Endpoints POST, PATCH, DELETE | 60 |
| Analíticas | GET /analytics/summary, /analytics/timeseries, /analytics/top-queries | 60 |
| Prueba de webhook | POST /webhooks/{id}/test | 20 |
Límite adicional: POST /documents/upload-url emite como máximo 50 URL de subida por chatbot en 2 horas.
Conector MCP
El endpoint MCP permite 300 solicitudes por minuto por clave. Además, cada llamada a una herramienta está sujeta al límite REST del endpoint que utiliza, y send_message consume la cuota de mensajes.
Cuando supera un límite
La API devuelve 429 RATE_LIMITED con un mensaje como "Rate limit exceeded. Maximum 60 requests per minute per API key." Espere al minuto siguiente y vuelva a intentarlo, idealmente con un retardo creciente.
Los límites de solicitudes son independientes de la cuota mensual de mensajes; consulte Visión general y Errores.
Chatbot#
Identifique el chatbot al que pertenece su clave API y compruebe su plan y su cuota antes de empezar a trabajar con él.
GET /chatbot
| Elemento | Valor |
|---|---|
| Método y ruta | GET https://www.chatbotty.ai/api/v1/chatbot |
| Parámetros | Ninguno |
| Límite de solicitudes | Clase de lectura (consulte Límites de solicitudes) |
| Cuota | No se consume |
| Herramienta MCP | get_chatbot_info |
Respuesta
{
"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"
}
}
}
Notas
planymessage_quotapertenecen al propietario de la cuenta; la cuota la comparten todos los chatbots de la cuenta.featuresindica qué funciones dependientes del plan puede utilizar esta clave.handoff_contactes el contacto que da el chatbot cuando no sabe la respuesta (aquí es de solo lectura;nullcuando no está definido).last_updated_ates la hora del documento subido más reciente.
Chat#
Envíe un mensaje al chatbot y reciba su respuesta, exactamente igual que un visitante en el widget.
POST /chat
| Elemento | Valor |
|---|---|
| Método y ruta | POST https://www.chatbotty.ai/api/v1/chat |
| Límite de solicitudes | Clase de chat: 60 por minuto |
| Cuota | Un mensaje por llamada; si se supera la cuota, la llamada devuelve 403 QUOTA_EXCEEDED |
| Herramienta MCP | send_message |
Cuerpo de la solicitud
| Campo | Obligatorio | Descripción |
|---|---|---|
message | Sí | La pregunta del visitante (texto no vacío) |
conversation_id | No | Continúa una conversación existente; omítalo para iniciar una nueva |
options | No | Objeto opcional; no es necesario para un uso normal |
Si conversation_id no existe o pertenece a otro chatbot, la llamada devuelve 400 CONVERSATION_NOT_FOUND. Un chatbot que no está activo devuelve 404 NOT_FOUND.
Respuesta
{
"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 }]
}
}
}
Contexto de la conversación
La primera llamada crea una conversación y devuelve su conversation_id. Envíe ese id con cada mensaje siguiente para mantener el contexto. Las conversaciones creadas a través de la API aparecen en el panel con la fuente api.
tools_executed
metadata.tools_executed enumera las herramientas que el chatbot llamó al responder (acciones de webhook, creación de tickets de soporte). Cada elemento tiene name, ok y, si falla, un breve code como webhook_timeout, webhook_redirect, webhook_blocked o invalid_args. Una lista vacía significa que no se llamó a ninguna herramienta. Utilícelo para verificar que una acción de webhook realmente se ejecutó.
Documentos#
Gestione la base de conocimiento del chatbot: suba, lea, edite, enumere y elimine documentos. Estas llamadas no consumen la cuota de mensajes.
Endpoints
| Método y ruta | Descripción | Parámetros clave | Herramienta MCP |
|---|---|---|---|
GET /documents | Listar documentos | limit (predeterminado 20, máx. 100), offset, status | list_documents |
POST /documents | Subir un documento; devuelve 202 | Véase más abajo | upload_document |
POST /documents/upload-url | Obtener una URL firmada para un archivo grande o local | filename | create_upload_url |
GET /documents/{id} | Estado y detalles de un documento | - | get_document |
DELETE /documents/{id} | Eliminar un documento | - | delete_document |
GET /documents/{id}/content | Leer el texto, paginado | offset, limit (predeterminado 20000, máx. 50000) | read_document |
PATCH /documents/{id}/content | Editar un documento .md o .txt | edits, append, expected_hash | edit_document, append_to_document |
Límites: las llamadas GET utilizan el límite de lectura, las demás el de escritura (consulte Límites de solicitudes).
Subida
Tipos permitidos: .pdf, .docx, .txt, .md, hasta 10 MB. Envíe multipart/form-data o JSON.
| Campo | Descripción |
|---|---|
file | El archivo (solo multipart) |
content | Texto de un documento .md o .txt (JSON; filename obligatorio) |
content_base64 | Archivo binario en base64 (JSON; utilícelo hasta unos 3 MB) |
url | URL pública de un archivo que el servidor descarga (JSON; solo planes con importación desde URL web) |
upload_id | Id de POST /documents/upload-url después de subir el archivo |
filename | Nombre del archivo con extensión |
description | Descripción opcional |
replace_existing | Predeterminado true: un archivo con el mismo nombre se sustituye por la nueva versión |
En JSON, envíe exactamente uno de content, content_base64, url, upload_id.
{ "filename": "faq.md", "content": "# FAQ\n\n## Opening hours\n..." }
Archivos grandes o locales
POST /documents/upload-urlcon{ "filename": "price-list.pdf" }. La respuesta contieneupload_id,upload_urly encabezados; la URL es válida durante 2 horas y funciona una sola vez.- Envíe el archivo sin procesar con
PUTaupload_url. POST /documentscon{ "upload_id": "...", "filename": "price-list.pdf" }.
Procesamiento y estado
El procesamiento es asíncrono. El estado pasa de pending a processing y a completed, o termina como failed con un error_message. Un documento fallido permanece en la lista; elimínelo o vuelva a subirlo. Consulte GET /documents/{id} periódicamente hasta que sea completed.
Editar y reemplazar
PATCH /documents/{id}/contentenvía solo el cambio:edits(lista deold_textynew_text, cadaold_textdebe aparecer exactamente una vez, hasta 100) y/oappend(text,after_headingopcional).expected_hash(deGET .../content) protege contra la sobrescritura de una versión más reciente (409 CONFLICT).- Solo se pueden editar documentos
.mdy.txten UTF-8 (de lo contrario400 NOT_EDITABLE). - Cada edición o sustitución crea un nuevo
document_id; la versión anterior sigue respondiendo hasta que la nueva estécompleted. - Un segundo cambio mientras el documento aún se está procesando devuelve
409 REPLACE_IN_PROGRESS.
Conversaciones#
Lea el historial de conversaciones del chatbot, incluidas las conversaciones creadas en el widget. Estas llamadas son de solo lectura y no consumen la cuota de mensajes.
Endpoints
| Método y ruta | Descripción | Parámetros clave | Herramienta MCP |
|---|---|---|---|
GET /conversations | Listar conversaciones | Véase más abajo | list_conversations |
GET /conversations/{id} | Una conversación | - | get_conversation |
GET /conversations/{id}/messages | Mensajes en orden cronológico | limit (predeterminado 50, máx. 200), offset | get_conversation_messages |
Las tres utilizan el límite de lectura de 120 solicitudes por minuto (consulte Límites de solicitudes). Una conversación de otro chatbot devuelve 404 NOT_FOUND.
Filtros de la lista
| Parámetro | Descripción |
|---|---|
limit, offset | Paginación (predeterminado 20, máx. 100) |
status | active, completed o ticket_created |
source | widget o api |
from, to | Fechas ISO 8601; filtran por el inicio de la conversación |
quality | Conversaciones con al menos una pregunta de este tipo: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
q | Búsqueda de texto completo en el texto de los mensajes (de 2 a 200 caracteres) |
Respuesta
{
"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 }
}
}
En los planes con tickets, el detalle de una conversación también contiene los tickets creados en ella. Los mensajes tienen id, role (user o assistant), content y created_at.
Consejo
Para encontrar las preguntas que el chatbot no pudo responder, utilice GET /analytics/top-queries?quality=not_answered (consulte Analíticas) y abra las conversaciones relacionadas a través de conversation_ids.
Analíticas#
Estadísticas agregadas del chatbot. Las analíticas están disponibles en todos los planes, Free incluido. Estas llamadas no consumen la cuota de mensajes.
Endpoints
| Método y ruta | Descripción | Herramienta MCP |
|---|---|---|
GET /analytics/summary | Totales del período | get_analytics_summary |
GET /analytics/timeseries | Recuentos por hora, día o semana | get_analytics_timeseries |
GET /analytics/top-queries | Preguntas más frecuentes | get_top_queries, list_knowledge_gaps |
Las tres utilizan el límite de analíticas de 60 solicitudes por minuto (consulte Límites de solicitudes).
Parámetros comunes
| Parámetro | Descripción |
|---|---|
period | today (predeterminado), week, month o quarter, evaluado en la zona horaria del chatbot |
from, to | Fechas ISO 8601; sustituyen a period; el intervalo es de 366 días como máximo |
source | widget o api |
Parámetros adicionales
| Endpoint | Parámetro | Descripción |
|---|---|---|
timeseries | granularity | auto (predeterminado), hour, day o week; hour con quarter se rechaza |
top-queries | limit, offset | Paginación (predeterminado 20, máx. 100) |
top-queries | quality | answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
Respuesta 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 es el número de respondidas dividido entre respondidas más no respondidas, en porcentaje.
Preguntas sin respuesta
GET /analytics/top-queries?quality=not_answered&period=month devuelve las preguntas que el chatbot no pudo responder, las más frecuentes primero. Cada elemento tiene content, count, last_asked y hasta 5 conversation_ids que puede abrir a través de conversaciones. Añada los datos que faltan a la base de conocimiento y verifique el resultado con el chat.
Tickets#
Lea los tickets de soporte, cambie su estado y añada notas internas. Los tickets están disponibles en los planes Evaluation, Support y Automate; Free devuelve 403 FORBIDDEN. Los tickets no se pueden crear a través de la API: los crea el chatbot durante una conversación.
Endpoints
| Método y ruta | Descripción | Parámetros clave | Herramienta MCP |
|---|---|---|---|
GET /tickets | Listar tickets, los más recientes primero | limit (predeterminado 20, máx. 100), offset, status, conversation_id, from, to | list_tickets |
GET /tickets/{id} | Un ticket | - | get_ticket |
PATCH /tickets/{id} | Cambiar el estado | status en el cuerpo | update_ticket_status |
GET /tickets/{id}/notes | Notas internas, las más antiguas primero | - | list_ticket_notes |
POST /tickets/{id}/notes | Añadir una nota; devuelve 201 | content en el cuerpo | add_ticket_note |
Las llamadas GET utilizan el límite de lectura (120 por minuto), PATCH y POST el límite de escritura (60 por minuto); consulte Límites de solicitudes.
Valores
| Elemento | Valor |
|---|---|
| Estado | open, in_progress, resolved, closed |
| Nota | Texto no vacío, hasta 5000 caracteres |
Un estado no válido devuelve 400 INVALID_REQUEST. Un ticket de otro chatbot devuelve 404 NOT_FOUND.
Objeto de 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"
}
Ejemplo
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"}'
Acciones de webhook#
Gestione las acciones de webhook del chatbot: API externas o webhooks de automatización (por ejemplo n8n) a los que el chatbot llama como herramientas mientras responde. Disponible en el plan Automate (10 webhooks y 10 herramientas por chatbot) y en la prueba de Evaluation (5 webhooks y 5 herramientas por chatbot). Los demás planes reciben 403 FORBIDDEN; superar los límites devuelve 403 LIMIT_EXCEEDED. Las llamadas no consumen la cuota de mensajes.
Endpoints
| Método y ruta | Descripción | Herramienta MCP |
|---|---|---|
GET /webhooks | Listar webhooks y el uso de sus límites | list_webhook_actions |
POST /webhooks | Crear un webhook, opcionalmente con herramientas; devuelve 201 | create_webhook_action |
GET /webhooks/{id} | Un webhook con sus herramientas | get_webhook_action |
PATCH /webhooks/{id} | Modificar un webhook | update_webhook_action |
DELETE /webhooks/{id} | Eliminar un webhook con sus herramientas | delete_webhook_action |
POST /webhooks/{id}/tools | Añadir una herramienta; devuelve 201 | add_webhook_tool |
PATCH /webhooks/{id}/tools/{toolId} | Modificar una herramienta | update_webhook_tool |
DELETE /webhooks/{id}/tools/{toolId} | Eliminar una herramienta | delete_webhook_tool |
POST /webhooks/{id}/test | Llamar al webhook como lo hace el chatbot | test_webhook_action |
Las lecturas utilizan el límite de lectura (120 por minuto), las modificaciones el límite de escritura (60), y la prueba tiene su propio límite de 20 por minuto; consulte Límites de solicitudes. La herramienta MCP get_webhook_guide devuelve una guía breve para asistentes de IA.
Campos del webhook
| Campo | Descripción |
|---|---|
name | Obligatorio, hasta 100 caracteres |
webhook_url | Obligatorio, dirección HTTPS pública |
http_method | POST (predeterminado) o GET |
send_metadata | Predeterminado true: la llamada incluye además tool_name, args y metadata (chatbot_id, conversation_id, timestamp); false envía solo los argumentos |
timeout_ms | De 1000 a 30000, predeterminado 10000 |
headers | Hasta 20 encabezados personalizados |
secret_query | Hasta 10 parámetros de consulta secretos, por ejemplo una clave API |
tools | Herramientas a las que puede llamar el chatbot (véase más abajo) |
Campos de la herramienta
| Campo | Descripción |
|---|---|
name | Letras minúsculas, dígitos y guiones bajos, comienza con una letra, hasta 64 caracteres, único por chatbot; create_support_ticket está reservado |
description | Hasta 500 caracteres; indica al chatbot cuándo utilizar la herramienta |
parameters | Hasta 10 elementos con name, type (string, number, boolean), description (hasta 200 caracteres), required |
Reglas
- Los valores de
headersysecret_querynunca se devuelven, solo sus nombres. Una clave encontrada enwebhook_urlse traslada automáticamente asecret_queryy se notifica enwarnings. - Cambiar el endpoint de un webhook requiere volver a enviar todas las claves almacenadas de
headersysecret_query, de modo que los secretos no puedan pasar a otro servidor sin que se note. - El chatbot realiza una ronda de llamadas a herramientas por respuesta. Una respuesta se corta a 10 KB, las redirecciones no se siguen y las direcciones internas se rechazan.
Prueba
POST /webhooks/{id}/test con un cuerpo opcional { "tool_name": "get_weather", "arguments": { "q": "Prague" } } devuelve ok, status, response_time_ms, body_preview (primeros 2 KB), truncated y warnings. Tras una prueba, formule al chatbot una pregunta correspondiente a través del chat y compruebe tools_executed.
Errores#
Las llamadas REST fallidas devuelven un estado HTTP distinto de 2xx y esta estructura:
{
"success": false,
"error": { "code": "INVALID_REQUEST", "message": "message is required and cannot be empty", "details": {} },
"timestamp": "2026-01-01T10:00:00.000Z"
}
details está presente solo en algunos errores. Gestione los errores por code; los mensajes pueden cambiar.
Códigos de error
| Código | HTTP | Significado |
|---|---|---|
UNAUTHORIZED | 401 | Clave API ausente, no válida o desactivada |
QUOTA_EXCEEDED | 403 | Cuota mensual de mensajes agotada (details.quota_info) |
FORBIDDEN | 403 | La función no está en su plan |
LIMIT_EXCEEDED | 403 | Se alcanzó el límite del plan de webhooks o herramientas (details.resource, used, max) |
INVALID_REQUEST | 400 | Cuerpo o parámetros no válidos |
INVALID_URL | 400 | La URL del webhook no es válida, no es HTTPS o no es pública |
INVALID_FILE | 400 | Falta el archivo en la subida |
FILE_TOO_LARGE | 400 | Archivo de más de 10 MB |
UNSUPPORTED_FILE_TYPE | 400 | Solo se aceptan .pdf, .docx, .txt, .md |
CONVERSATION_NOT_FOUND | 400 | conversation_id no existe o pertenece a otro chatbot |
EDIT_FAILED | 400 | No se encontró el texto a reemplazar, o se encontró más de una vez |
NOT_EDITABLE | 400 | Solo se pueden editar documentos .md y .txt en UTF-8 |
NOT_FOUND | 404 | Documento, ticket, webhook, herramienta o subida no encontrados, o chatbot inactivo |
DUPLICATE_FILENAME | 409 | Ya existe un documento con este nombre (details.existing_document_id) |
DUPLICATE_CONTENT | 409 | El mismo contenido ya está indexado |
REPLACE_IN_PROGRESS | 409 | El documento se está reemplazando o procesando; espere hasta que sea completed |
CONFLICT | 409 | El nombre de la herramienta ya existe, o el documento cambió desde que lo leyó |
STORAGE_LIMIT_EXCEEDED | 413 | Se superó el límite de almacenamiento del chatbot |
RATE_LIMITED | 429 | Demasiadas solicitudes; consulte Límites de solicitudes |
GONE_USE_V1 | 410 | El antiguo endpoint /api/chat se eliminó; utilice /api/v1/chat |
INTERNAL_ERROR | 500 | Error inesperado del servidor |
Errores de MCP
El endpoint MCP responde con errores JSON-RPC: 401 para un token ausente o no válido, 429 para demasiadas solicitudes y 403 cuando el plan no incluye MCP. Cuando falla una herramienta, el resultado se marca como error y contiene el código de la API, por ejemplo Chatbotty API error [NOT_FOUND] (HTTP 404). Consulte Conector MCP.
Soporte
Si un error persiste, escriba a support@chatbotty.ai e incluya el código, la hora y el endpoint.
Conector MCP#
El conector MCP permite que un asistente de IA como Claude, n8n o Cursor trabaje con su chatbot: conversar con él, gestionar su base de conocimiento, configurar acciones de webhook y leer conversaciones, analíticas y tickets. Un conector pertenece a un chatbot; para utilizar otro chatbot, añada otro conector.
Conexión
| Elemento | Valor |
|---|---|
| URL del servidor | https://www.chatbotty.ai/api/mcp |
| Transporte | Streamable HTTP sobre POST |
| Planes | Todos los planes; se comprueba en cada solicitud |
| Límite | 300 solicitudes por minuto por clave (consulte Límites de solicitudes) |
Inicio de sesión o clave
| Método | Utilizado por | Cómo |
|---|---|---|
| Inicio de sesión (OAuth) | claude.ai, Claude Desktop, Claude móvil, Claude Code | El cliente abre una página de Chatbotty; usted inicia sesión, elige el chatbot y hace clic en Permitir. Se crea una clave automáticamente |
| Clave API | n8n, Cursor, VS Code, otros clientes | Envíe el encabezado Authorization: Bearer YOUR_API_KEY (Autenticación) |
Una clave creada al iniciar sesión se etiqueta como Conector MCP en API y MCP. Elimínela allí para desconectar el asistente. Los tickets y las herramientas de webhook aparecen solo si su plan los incluye. Los pasos de configuración están en Clientes MCP.
Herramientas
| Área | Herramientas |
|---|---|
| Chatbot y chat | get_chatbot_info, send_message |
| Documentos | list_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document |
| Lagunas de conocimiento | list_knowledge_gaps |
| Conversaciones | list_conversations, get_conversation, get_conversation_messages |
| Analíticas | get_analytics_summary, get_analytics_timeseries, get_top_queries |
| Tickets (planes con tickets) | list_tickets, get_ticket, update_ticket_status, list_ticket_notes, add_ticket_note |
| Acciones de webhook (planes con acciones de 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 |
Cada herramienta funciona como el endpoint REST correspondiente descrito en las secciones anteriores y tiene los mismos límites y errores.
Conviene saber
send_messagehabla con el chatbot como un visitante y consume la cuota mensual de mensajes.test_webhook_actionno la consume.list_knowledge_gapsenumera las preguntas que el chatbot no pudo responder y requiere un período; utilícela para encontrar qué añadir a la base de conocimiento.- Un cliente puede almacenar en caché las descripciones de las herramientas. Si las herramientas parecen desactualizadas, elimine el conector y vuelva a añadirlo.
Clientes MCP#
Cómo conectar los clientes habituales a https://www.chatbotty.ai/api/mcp. Para los clientes que envían una clave, créela primero como se describe en Autenticación. Contexto: Conector MCP.
Claude (claude.ai, Claude Desktop, móvil)
- Abra Settings, después Connectors, y añada un conector personalizado.
- Pegue la URL del servidor y haga clic en Connect.
- Inicie sesión en Chatbotty, elija el chatbot y haga clic en Permitir.
No se necesita ninguna clave API. El conector funciona después también en la aplicación móvil de Claude.
Claude Code
Inicie sesión a través del navegador:
claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp
O utilice una clave API:
claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
Cuando la página de inicio de sesión advierta de que la aplicación se ejecuta en su propio ordenador, permita el acceso solo si usted mismo inició la conexión.
n8n
- Añada el nodo MCP Client Tool.
- Endpoint: la URL del servidor.
- Server Transport: HTTP Streamable.
- Authentication: Bearer Auth con su clave API.
Cursor, VS Code y otros clientes
Añada un servidor MCP remoto con la URL del servidor y el encabezado Authorization: Bearer YOUR_API_KEY. En Cursor, por ejemplo:
{
"mcpServers": {
"chatbotty": {
"url": "https://www.chatbotty.ai/api/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
Solución de problemas
| Problema | Qué comprobar |
|---|---|
401 | La clave es incorrecta, está desactivada o se eliminó |
| Faltan las herramientas de tickets o de webhook | Su plan no las incluye |
Un cliente manual recibe 406 | El cliente debe enviar Accept: application/json, text/event-stream |
Ejemplos#
Ejemplos para copiar y pegar de las tareas más habituales. Sustituya YOUR_API_KEY por una clave de API y MCP y https://www.chatbotty.ai por la URL base. Consulte Autenticación.
Comprobar el chatbot y la cuota
curl https://www.chatbotty.ai/api/v1/chatbot \
-H "Authorization: Bearer YOUR_API_KEY"
Hacer una pregunta y continuar la conversación
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?"}'
Tome conversation_id de la respuesta y envíelo con el mensaje siguiente:
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"}'
Subir un documento
curl -X POST https://www.chatbotty.ai/api/v1/documents \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@./faq.md"
Después compruebe el estado hasta que sea completed:
curl https://www.chatbotty.ai/api/v1/documents/DOCUMENT_ID \
-H "Authorization: Bearer YOUR_API_KEY"
Encontrar preguntas sin respuesta
curl "https://www.chatbotty.ai/api/v1/analytics/top-queries?quality=not_answered&period=month" \
-H "Authorization: Bearer YOUR_API_KEY"
Listar conversaciones que contienen una palabra
curl "https://www.chatbotty.ai/api/v1/conversations?q=refund&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
Gestionar errores
{ "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" }
Ramifique según error.code y consulte Errores. Para los límites, consulte Límites de solicitudes. Preguntas: support@chatbotty.ai.