--- title: "Descripción general de la Public API de Chatfuel" description: "La Public API de Chatfuel es una API GraphQL para gestionar bots, contactos, mensajes y flujos desde tu servidor con tokens de usuarios virtuales." canonical_url: https://chatfuel.com/es/docs/public-api/overview markdown_url: https://chatfuel.com/es/docs/public-api/overview.md last_updated: 2026-10-06 lang: es site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Descripción general de la Public API de Chatfuel La Public API de Chatfuel es una API GraphQL para gestionar bots, contactos, mensajes y flujos desde tu servidor con tokens de usuarios virtuales. La Public API de Chatfuel permite que tu propio software trabaje con los bots de Chatfuel: leer y actualizar contactos, enviar mensajes por WhatsApp, Instagram, Facebook, TikTok y el chat del sitio web, gestionar reservas y el catálogo, y crear flujos y automatizaciones con IA. Es una API GraphQL en `https://panel.chatfuel.com/graphql`, pensada para desarrolladores que conectan Chatfuel con un CRM, una herramienta interna o su propio producto. ## Qué cubre la Public API [#qué-cubre-la-public-api] La Public API es una parte estable y documentada de la misma API GraphQL que usa el panel de Chatfuel. Solo forman parte de ella los campos publicados explícitamente, así que los cambios internos del panel nunca rompen tu integración. Los campos publicados solo cambian cuando se agregan campos o argumentos nuevos; todo lo que va a desaparecer primero se marca como obsoleto y sigue funcionando hasta una fecha indicada, como se describe en [versionado y obsolescencia](https://chatfuel.com/es/docs/public-api/versioning). La Public API se organiza en torno a un bot. Todo lo que puedes leer o cambiar pertenece a un bot y se alcanza desde la consulta `bot(id:)` o desde una mutación que recibe un `botID`: * [bots y datos de la cuenta](https://chatfuel.com/es/docs/public-api/bots-and-account): el bot, su configuración, la cuenta actual * [equipo y roles](https://chatfuel.com/es/docs/public-api/team-and-roles): usuarios virtuales, miembros del equipo e invitaciones * [contactos](https://chatfuel.com/es/docs/public-api/contacts): contactos, atributos, responsables, notas, etapas de venta, importación y exportación CSV * [mensajería](https://chatfuel.com/es/docs/public-api/messaging): conversaciones y mensajes en todos los canales, plantillas de WhatsApp * [flujos](https://chatfuel.com/es/docs/public-api/flows): flujos, bloques, reglas de palabras clave y chats de prueba * [automatizaciones con IA](https://chatfuel.com/es/docs/public-api/ai-automations): configuración de Fuely AI, automatizaciones y difusiones * [reservas y catálogo](https://chatfuel.com/es/docs/public-api/bookings-and-catalog): reservas, especialistas, productos y servicios * [canales](https://chatfuel.com/es/docs/public-api/channels): configuración de WhatsApp, Instagram, Facebook, TikTok y del widget del sitio web * [archivos y tareas](https://chatfuel.com/es/docs/public-api/files-and-tasks): carga de archivos y tareas de larga duración ## Cómo funciona el acceso: token personal y usuarios virtuales [#cómo-funciona-el-acceso-token-personal-y-usuarios-virtuales] La Public API acepta dos tipos de tokens, y no son equivalentes. El **token de API personal** te pertenece a ti, un usuario real de Chatfuel. En el panel se llama **CLI token**. Actúa con tus propios permisos en todos los bots de los que eres miembro. Úsalo para un pequeño conjunto de operaciones a nivel de cuenta: crear y eliminar usuarios virtuales, gestionar miembros del equipo, renombrar o eliminar bots, conectar canales y trabajar con espacios de trabajo. Un **usuario virtual** es una cuenta solo para la API que creas dentro de un bot con el rol Editor o Agent. Tiene su propio token, no puede iniciar sesión en el panel y no puede ver nada fuera de su bot. Usa tokens de usuarios virtuales para todo el trabajo diario: contactos, mensajes, flujos, automatizaciones, reservas. Todos los ejemplos de esta documentación usan un token de usuario virtual, salvo que indiquen **Solo token personal** (Personal token only). Crea un usuario virtual por integración, o uno por cada cliente de tu producto. Si un token se filtra, eliminas un solo usuario virtual en lugar de perder el acceso a toda tu cuenta. [Autenticación](https://chatfuel.com/es/docs/public-api/authentication) compara los dos tokens en detalle, y [usuarios virtuales](https://chatfuel.com/es/docs/public-api/virtual-users) explica los roles y los límites. ## Cómo es una solicitud [#cómo-es-una-solicitud] Cada llamada es un `POST` HTTP con un cuerpo JSON a `https://panel.chatfuel.com/graphql`. El token va en el encabezado `Authorization` con el esquema `Bearer`: ```bash curl https://panel.chatfuel.com/graphql \ -H "Authorization: Bearer $CHATFUEL_VIRTUAL_USER_TOKEN" \ -H "Content-Type: application/json" \ -d '{"query":"query Bot($id: BotID!) { bot(id: $id) { id title timezone } }","variables":{"id":"'"$BOT_ID"'"}}' ``` La respuesta es JSON estándar de GraphQL con `data` y, cuando algo falla, `errors`. [Cómo hacer solicitudes](https://chatfuel.com/es/docs/public-api/requests) cubre la paginación, las suscripciones y la carga de archivos, y [errores](https://chatfuel.com/es/docs/public-api/errors) enumera los códigos de error. ## Qué necesitas para empezar [#qué-necesitas-para-empezar] Para empezar con la Public API necesitas: * Una cuenta de Chatfuel con el rol **Admin** en el bot, porque solo quienes tienen el rol Admin en el bot pueden crear usuarios virtuales. * Un servidor o un proceso de backend que haga las llamadas. La Public API es para uso de servidor a servidor: CORS bloquea los navegadores en otros dominios, y los tokens nunca deben enviarse a un navegador ni a una app móvil. * Unos diez minutos para la [guía de inicio rápido](https://chatfuel.com/es/docs/public-api/quickstart), que te lleva de no tener ningún token a tu primera llamada a la API. ## Límites de un vistazo [#límites-de-un-vistazo] * **Límite de solicitudes:** 25 operaciones por segundo por cuenta. Cada usuario virtual tiene su propio límite. * **Usuarios virtuales:** hasta 20 por bot. * **Tamaño de página:** hasta 500 elementos por página para contactos, conversaciones y reglas de palabras clave. * **Tokens:** se muestran una sola vez al crearlos y son válidos durante 10 años, salvo que se revoquen. ## Problemas comunes [#problemas-comunes] ### Las solicitudes desde una página web fallan con un error de CORS [#las-solicitudes-desde-una-página-web-fallan-con-un-error-de-cors] La Public API acepta solicitudes del navegador solo desde el panel de Chatfuel. Llámala desde tu servidor y guarda el token allí; tu página web se comunica con tu servidor. ### ¿Puedo usar la clave de API de Settings → API? [#puedo-usar-la-clave-de-api-de-settings--api] La clave **API** de la configuración de un bot es una clave distinta y más antigua para los endpoints de difusiones e importación de contactos. La Public API solo acepta el token de API personal (**CLI token**) y los tokens de usuarios virtuales.