Visión general

Quickchat AI ofrece una API REST para acceder de forma programática a la configuración de tu Agente de IA, la Base de Conocimiento, las Conversaciones, las AI Actions y mucho más.

Autenticación

Todos los endpoints de la API usan autenticación mediante Bearer token. Incluye tu token de API en el encabezado Authorization de cada petición:

Authorization: Bearer <API_TOKEN>

Los tokens se crean en el Dashboard de Quickchat en External Apps > API. Cada token es un JWT que contiene tu scenario_id, por lo que no se necesita ningún encabezado identificador adicional.

• Validez del token: 52 semanas desde su creación
• Los tokens pueden revocarse en cualquier momento desde el Dashboard
• Cada token está vinculado a un único Agente de IA (scenario)
• La creación de tokens requiere el plan Business o superior; en los planes inferiores la opción está deshabilitada y el endpoint devuelve 402 Payment Required

Nota

El endpoint de Chat en tiempo real (POST https://app.quickchat.ai/chat) acepta el mismo Bearer token que el resto de esta API, pero está fuera de la ruta base /v1/api/ y requiere scenario_id en el cuerpo de la petición. Consulta la página de Chat para la referencia completa.

Token Scopes

Los tokens de API se crean con uno de dos scopes:

Scope	Access Level	Description
read_all	Solo lectura	Puede leer todos los recursos pero no crear, actualizar ni eliminar
write_all	Lectura + Escritura	Acceso completo a todos los endpoints, incluidas las operaciones de escritura

• A los tokens se les asigna un scope al crearse en el Dashboard, en External Apps > API
• El scope write_all incluye automáticamente todos los permisos de read_all
• Usar un token read_all en un endpoint de escritura devuelve 403 con "Insufficient token scope. Required: write_all"

Consejo

Usa tokens read_all para monitorización, analítica e integraciones de solo lectura. Usa tokens write_all únicamente cuando tu integración necesite crear o modificar recursos.

Requisitos de scope por grupo de endpoints:

Endpoint Group	Read Operations	Write Operations
Chatbot Settings	read_all	write_all
Knowledge Base Settings	read_all	write_all
Articles	read_all	write_all
Article Language URLs	read_all	write_all
Tags	read_all	—
File Upload	—	write_all
Import External Content	—	write_all
Intercom Knowledge Base	read_all	write_all
Widget Configuration	read_all	write_all
Conversations	read_all	—
Conversation Metadata	read_all	write_all
Handoff Configuration	read_all	write_all
Conversation Rating	read_all	write_all
AI Actions	read_all	write_all

URL base

Endpoint Group	Base URL
Knowledge Base, AI Actions, File Upload, Import, Chatbot Settings, Widget, Handoff, Conversation Rating	https://app.quickchat.ai/v1/api/
Conversations	https://app.quickchat.ai/v1/api_core/
Realtime Chat	https://app.quickchat.ai/chat

Límites de tasa

Los límites de tasa se aplican por token y por endpoint.

Tier	Limit	Applies To
READ	120 peticiones/min	Operaciones GET y de listado
WRITE	60 peticiones/min	POST, PATCH, PUT, DELETE
HEAVY	20 peticiones/min	Carga de archivos, importaciones, scraping

Cuando se excede un límite de tasa, la API devuelve HTTP 429 Too Many Requests.

Webhooks

Quickchat AI no envía webhooks salientes. No hay forma de suscribirse a un evento para que hagamos un POST a tu endpoint cuando llega un mensaje, se transfiere una conversación o se cierra una conversación.

Para sacar los datos a medida que ocurren las cosas, usa una de estas opciones:

• Acciones de IA: la IA llama a tu API en mitad de la conversación. Es lo más parecido a un webhook y funciona por push, no por sondeo: se llama a tu endpoint mientras la conversación está en curso. Se dispara cuando la IA decide que la acción corresponde, así que encaja mejor con “avisar a mi sistema de este lead” que con “avisar a mi sistema de cada mensaje”.
• Google Sheets: añade una fila por evento sin tener que construir un endpoint.
• Sondear la API de Conversations: para un registro completo. Ten en cuenta el límite READ de arriba.

El acceso a la API requiere el plan Business, consulta Planes y límites.

Paginación

Los endpoints de listado admiten paginación mediante parámetros de consulta:

Parameter	Description
limit integer	Número de elementos por página
offset integer	Número de elementos a omitir

Las respuestas paginadas siguen esta estructura:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Manejo de errores

Todos los errores se devuelven como JSON en el siguiente formato:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Status	Code	Description
400	BAD_REQUEST	Entrada no válida o campos obligatorios faltantes
401	PERMISSION_DENIED	Token no válido, expirado o revocado
402	PAYMENT_REQUIRED	Se requiere una suscripción activa
403	PERMISSION_DENIED	El token carece del scope necesario para esta operación
404	NOT_FOUND	Recurso no encontrado
409	CONFLICT	Operación en conflicto (p. ej., modificación concurrente)
422	VALIDATION_ERROR	El cuerpo de la petición no pasó la validación del esquema
429	TOO_MANY_REQUESTS	Límite de tasa excedido
500	UNKNOWN	Error interno del servidor
503	SERVICE_UNAVAILABLE	Indisponibilidad temporal

---