← Volver a la aplicación

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

ElementoValor
URL base de RESThttps://www.chatbotty.ai/api/v1
URL del servidor MCPhttps://www.chatbotty.ai/api/mcp
FormatoJSON sobre HTTPS
AutenticaciónAuthorization: Bearer YOUR_API_KEY
Ámbito de una claveUna 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ónFreeEvaluationSupportAutomate
Chat, documentos, conversaciones, analíticasSíSíSíSí
TicketsNoSíSíSí
Acciones de webhookNoSíNoSí
Importación de documentos desde una URL webNoSí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 /chat o la herramienta MCP send_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 con GET /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

ElementoValor
FormatoUna cadena hexadecimal aleatoria de 64 caracteres
ÁmbitoUn chatbot por clave
LímiteHasta 50 claves por chatbot (las claves inactivas también cuentan)
AlmacenamientoSolo 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

  1. Abra API y MCP en la barra lateral.
  2. 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.
  3. 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ónEfecto
DesactivarLa clave deja de funcionar al instante; Activar la vuelve a activar
EliminarLa 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ónRespuesta
Encabezado ausente o mal formado401 UNAUTHORIZED "Missing or invalid Authorization header"
Clave desconocida o desactivada401 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

ClaseEndpointsLímite por minuto
ChatPOST /chat60
LecturaTodos los demás endpoints GET excepto analíticas (incluido GET /chatbot)120
EscrituraEndpoints POST, PATCH, DELETE60
AnalíticasGET /analytics/summary, /analytics/timeseries, /analytics/top-queries60
Prueba de webhookPOST /webhooks/{id}/test20

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

ElementoValor
Método y rutaGET https://www.chatbotty.ai/api/v1/chatbot
ParámetrosNinguno
Límite de solicitudesClase de lectura (consulte Límites de solicitudes)
CuotaNo se consume
Herramienta MCPget_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

  • plan y message_quota pertenecen al propietario de la cuenta; la cuota la comparten todos los chatbots de la cuenta.
  • features indica qué funciones dependientes del plan puede utilizar esta clave.
  • handoff_contact es el contacto que da el chatbot cuando no sabe la respuesta (aquí es de solo lectura; null cuando no está definido).
  • last_updated_at es 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

ElementoValor
Método y rutaPOST https://www.chatbotty.ai/api/v1/chat
Límite de solicitudesClase de chat: 60 por minuto
CuotaUn mensaje por llamada; si se supera la cuota, la llamada devuelve 403 QUOTA_EXCEEDED
Herramienta MCPsend_message

Cuerpo de la solicitud

CampoObligatorioDescripción
messageSíLa pregunta del visitante (texto no vacío)
conversation_idNoContinúa una conversación existente; omítalo para iniciar una nueva
optionsNoObjeto 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 rutaDescripciónParámetros claveHerramienta MCP
GET /documentsListar documentoslimit (predeterminado 20, máx. 100), offset, statuslist_documents
POST /documentsSubir un documento; devuelve 202Véase más abajoupload_document
POST /documents/upload-urlObtener una URL firmada para un archivo grande o localfilenamecreate_upload_url
GET /documents/{id}Estado y detalles de un documento-get_document
DELETE /documents/{id}Eliminar un documento-delete_document
GET /documents/{id}/contentLeer el texto, paginadooffset, limit (predeterminado 20000, máx. 50000)read_document
PATCH /documents/{id}/contentEditar un documento .md o .txtedits, append, expected_hashedit_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.

CampoDescripción
fileEl archivo (solo multipart)
contentTexto de un documento .md o .txt (JSON; filename obligatorio)
content_base64Archivo binario en base64 (JSON; utilícelo hasta unos 3 MB)
urlURL pública de un archivo que el servidor descarga (JSON; solo planes con importación desde URL web)
upload_idId de POST /documents/upload-url después de subir el archivo
filenameNombre del archivo con extensión
descriptionDescripción opcional
replace_existingPredeterminado 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

  1. POST /documents/upload-url con { "filename": "price-list.pdf" }. La respuesta contiene upload_id, upload_url y encabezados; la URL es válida durante 2 horas y funciona una sola vez.
  2. Envíe el archivo sin procesar con PUT a upload_url.
  3. POST /documents con { "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}/content envía solo el cambio: edits (lista de old_text y new_text, cada old_text debe aparecer exactamente una vez, hasta 100) y/o append (text, after_heading opcional).
  • expected_hash (de GET .../content) protege contra la sobrescritura de una versión más reciente (409 CONFLICT).
  • Solo se pueden editar documentos .md y .txt en UTF-8 (de lo contrario 400 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 rutaDescripciónParámetros claveHerramienta MCP
GET /conversationsListar conversacionesVéase más abajolist_conversations
GET /conversations/{id}Una conversación-get_conversation
GET /conversations/{id}/messagesMensajes en orden cronológicolimit (predeterminado 50, máx. 200), offsetget_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ámetroDescripción
limit, offsetPaginación (predeterminado 20, máx. 100)
statusactive, completed o ticket_created
sourcewidget o api
from, toFechas ISO 8601; filtran por el inicio de la conversación
qualityConversaciones con al menos una pregunta de este tipo: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified
qBú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 rutaDescripciónHerramienta MCP
GET /analytics/summaryTotales del períodoget_analytics_summary
GET /analytics/timeseriesRecuentos por hora, día o semanaget_analytics_timeseries
GET /analytics/top-queriesPreguntas más frecuentesget_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ámetroDescripción
periodtoday (predeterminado), week, month o quarter, evaluado en la zona horaria del chatbot
from, toFechas ISO 8601; sustituyen a period; el intervalo es de 366 días como máximo
sourcewidget o api

Parámetros adicionales

EndpointParámetroDescripción
timeseriesgranularityauto (predeterminado), hour, day o week; hour con quarter se rechaza
top-querieslimit, offsetPaginación (predeterminado 20, máx. 100)
top-queriesqualityanswered, 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 rutaDescripciónParámetros claveHerramienta MCP
GET /ticketsListar tickets, los más recientes primerolimit (predeterminado 20, máx. 100), offset, status, conversation_id, from, tolist_tickets
GET /tickets/{id}Un ticket-get_ticket
PATCH /tickets/{id}Cambiar el estadostatus en el cuerpoupdate_ticket_status
GET /tickets/{id}/notesNotas internas, las más antiguas primero-list_ticket_notes
POST /tickets/{id}/notesAñadir una nota; devuelve 201content en el cuerpoadd_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

ElementoValor
Estadoopen, in_progress, resolved, closed
NotaTexto 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 rutaDescripciónHerramienta MCP
GET /webhooksListar webhooks y el uso de sus límiteslist_webhook_actions
POST /webhooksCrear un webhook, opcionalmente con herramientas; devuelve 201create_webhook_action
GET /webhooks/{id}Un webhook con sus herramientasget_webhook_action
PATCH /webhooks/{id}Modificar un webhookupdate_webhook_action
DELETE /webhooks/{id}Eliminar un webhook con sus herramientasdelete_webhook_action
POST /webhooks/{id}/toolsAñadir una herramienta; devuelve 201add_webhook_tool
PATCH /webhooks/{id}/tools/{toolId}Modificar una herramientaupdate_webhook_tool
DELETE /webhooks/{id}/tools/{toolId}Eliminar una herramientadelete_webhook_tool
POST /webhooks/{id}/testLlamar al webhook como lo hace el chatbottest_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

CampoDescripción
nameObligatorio, hasta 100 caracteres
webhook_urlObligatorio, dirección HTTPS pública
http_methodPOST (predeterminado) o GET
send_metadataPredeterminado true: la llamada incluye además tool_name, args y metadata (chatbot_id, conversation_id, timestamp); false envía solo los argumentos
timeout_msDe 1000 a 30000, predeterminado 10000
headersHasta 20 encabezados personalizados
secret_queryHasta 10 parámetros de consulta secretos, por ejemplo una clave API
toolsHerramientas a las que puede llamar el chatbot (véase más abajo)

Campos de la herramienta

CampoDescripción
nameLetras minúsculas, dígitos y guiones bajos, comienza con una letra, hasta 64 caracteres, único por chatbot; create_support_ticket está reservado
descriptionHasta 500 caracteres; indica al chatbot cuándo utilizar la herramienta
parametersHasta 10 elementos con name, type (string, number, boolean), description (hasta 200 caracteres), required

Reglas

  • Los valores de headers y secret_query nunca se devuelven, solo sus nombres. Una clave encontrada en webhook_url se traslada automáticamente a secret_query y se notifica en warnings.
  • Cambiar el endpoint de un webhook requiere volver a enviar todas las claves almacenadas de headers y secret_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ódigoHTTPSignificado
UNAUTHORIZED401Clave API ausente, no válida o desactivada
QUOTA_EXCEEDED403Cuota mensual de mensajes agotada (details.quota_info)
FORBIDDEN403La función no está en su plan
LIMIT_EXCEEDED403Se alcanzó el límite del plan de webhooks o herramientas (details.resource, used, max)
INVALID_REQUEST400Cuerpo o parámetros no válidos
INVALID_URL400La URL del webhook no es válida, no es HTTPS o no es pública
INVALID_FILE400Falta el archivo en la subida
FILE_TOO_LARGE400Archivo de más de 10 MB
UNSUPPORTED_FILE_TYPE400Solo se aceptan .pdf, .docx, .txt, .md
CONVERSATION_NOT_FOUND400conversation_id no existe o pertenece a otro chatbot
EDIT_FAILED400No se encontró el texto a reemplazar, o se encontró más de una vez
NOT_EDITABLE400Solo se pueden editar documentos .md y .txt en UTF-8
NOT_FOUND404Documento, ticket, webhook, herramienta o subida no encontrados, o chatbot inactivo
DUPLICATE_FILENAME409Ya existe un documento con este nombre (details.existing_document_id)
DUPLICATE_CONTENT409El mismo contenido ya está indexado
REPLACE_IN_PROGRESS409El documento se está reemplazando o procesando; espere hasta que sea completed
CONFLICT409El nombre de la herramienta ya existe, o el documento cambió desde que lo leyó
STORAGE_LIMIT_EXCEEDED413Se superó el límite de almacenamiento del chatbot
RATE_LIMITED429Demasiadas solicitudes; consulte Límites de solicitudes
GONE_USE_V1410El antiguo endpoint /api/chat se eliminó; utilice /api/v1/chat
INTERNAL_ERROR500Error 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

ElementoValor
URL del servidorhttps://www.chatbotty.ai/api/mcp
TransporteStreamable HTTP sobre POST
PlanesTodos los planes; se comprueba en cada solicitud
Límite300 solicitudes por minuto por clave (consulte Límites de solicitudes)

Inicio de sesión o clave

MétodoUtilizado porCómo
Inicio de sesión (OAuth)claude.ai, Claude Desktop, Claude móvil, Claude CodeEl 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 APIn8n, Cursor, VS Code, otros clientesEnví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

ÁreaHerramientas
Chatbot y chatget_chatbot_info, send_message
Documentoslist_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document
Lagunas de conocimientolist_knowledge_gaps
Conversacioneslist_conversations, get_conversation, get_conversation_messages
Analíticasget_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_message habla con el chatbot como un visitante y consume la cuota mensual de mensajes. test_webhook_action no la consume.
  • list_knowledge_gaps enumera 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)

  1. Abra Settings, después Connectors, y añada un conector personalizado.
  2. Pegue la URL del servidor y haga clic en Connect.
  3. 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

  1. Añada el nodo MCP Client Tool.
  2. Endpoint: la URL del servidor.
  3. Server Transport: HTTP Streamable.
  4. 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

ProblemaQué comprobar
401La clave es incorrecta, está desactivada o se eliminó
Faltan las herramientas de tickets o de webhookSu plan no las incluye
Un cliente manual recibe 406El 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.