Descripción general de la Public API de Chatfuel

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

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.

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: el bot, su configuración, la cuenta actual
• equipo y roles: usuarios virtuales, miembros del equipo e invitaciones
• contactos: contactos, atributos, responsables, notas, etapas de venta, importación y exportación CSV
• mensajería: conversaciones y mensajes en todos los canales, plantillas de WhatsApp
• flujos: flujos, bloques, reglas de palabras clave y chats de prueba
• automatizaciones con IA: configuración de Fuely AI, automatizaciones y difusiones
• reservas y catálogo: reservas, especialistas, productos y servicios
• canales: configuración de WhatsApp, Instagram, Facebook, TikTok y del widget del sitio web
• archivos y tareas: carga de archivos y tareas de larga duración

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 compara los dos tokens en detalle, y usuarios virtuales explica los roles y los límites.

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:

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 cubre la paginación, las suscripciones y la carga de archivos, y errores enumera los códigos de error.

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, que te lleva de no tener ningún token a tu primera llamada a la API.

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

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?

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.