Crea una app sobre la Public API con el Chatfuel wizard

El Chatfuel wizard (@chatfuel/wizard) es una herramienta de línea de comandos que escribe una app web completa sobre la Public API de Chatfuel: una bandeja de entrada para operadores, un CRM, negocios, reservas, la configuración del AI Agent y más, como código fuente React y Vite que es tuyo. Se ejecuta una vez, hace algunas preguntas y deja un proyecto común conectado a tu espacio de trabajo de Chatfuel, además de skills que permiten que un agente de programación como Claude Code o Codex siga desarrollándolo. El wizard y la app que escribe son de código abierto con licencia MIT, en github.com/chatfuel-lab/wizard.

Qué necesitas antes de ejecutar el wizard

• Node.js 22.19.0 o una versión más reciente. Compruébalo con node --version. Con una versión anterior, el wizard se detiene antes de cargar nada y muestra el comando de instalación para tu plataforma.
• Una terminal. El wizard hace preguntas, así que necesita una terminal interactiva. Para CI y scripts, --yes con las respuestas como flags lo ejecuta sin intervención.
• Tu token de API personal, que en el panel se llama CLI token. Cópialo de la página del token. Autenticación explica qué puede hacer este token.
• Un agente de programación (opcional). El wizard busca Claude Code y Codex CLI, y ofrece instalar uno si no encuentra ninguno.

No necesitas instalar ni clonar nada más antes: el wizard instala por sí mismo las dependencias de la app.

Cómo ejecutar el wizard

Ejecuta un solo comando en el directorio donde quieres crear la app:

npx @chatfuel/wizard

El wizard hace sus preguntas en este orden:

1. App nueva o proyecto existente. La app nueva es la opción predeterminada. La otra respuesta agrega los módulos a un proyecto que ya tienes (--embed).
2. Módulos. Elige las partes de la app que quieres; módulos del wizard los enumera todos. Un módulo que necesita otro lo trae consigo, y el wizard te ofrece los módulos que recomiendan los que elegiste.
3. Agente de programación y ubicación de las skills. Si tienes instalados Claude Code y Codex, el wizard pregunta cuál de los dos continúa el trabajo. Las skills se instalan en el proyecto o en tu directorio personal, para tener una sola copia para todas tus apps.
4. Token de Chatfuel. Pega el token de API personal. El wizard lo verifica con la API de Chatfuel, vuelve a pedirlo hasta tres veces si es rechazado y lo guarda en .env con el modo de archivo 0600.
5. Espacio de trabajo. Solo lo pregunta si tu cuenta tiene más de uno; si tu cuenta no tiene ninguno, aquí se crea su primer espacio de trabajo. La app lee los bots del espacio de trabajo en tiempo de ejecución, así que un bot que crees más adelante aparece sin volver a ejecutar el wizard.
6. Plan. Si el espacio de trabajo todavía no tiene una suscripción, el wizard muestra los planes de Chatfuel y un enlace para empezar una prueba.
7. Nombre y logo de la app. El nombre predeterminado es el título del espacio de trabajo y aparece en la pestaña del navegador, la barra superior y la pantalla de inicio de sesión. El logo puede ser un archivo svg, png, jpg, webp, gif o ico.
8. Orígenes de navegador permitidos. La respuesta recomendada es el propio origen de la app. * es solo para desarrollo local: una app desplegada se niega a iniciar con ese valor.
9. Directorio. ./chatfuel-app, salvo que indiques otro. El directorio debe estar vacío o no existir todavía.

Los módulos auth y admin agregan sus propias preguntas: el proyecto de Supabase para el inicio de sesión y la contraseña del panel de administración.

Qué escribe el wizard

El wizard copia la app, escribe .env, instala las skills e instala las dependencias. El resultado es un proyecto de Vite, React y TypeScript:

• Un directorio por módulo en src/modules/<id>/. Los módulos que no elegiste no dejan código.
• El sistema de diseño, el cliente GraphQL tipado y el proxy, copiados como código fuente, no como paquetes de npm. Una nueva versión del wizard no puede romper tu app; para actualizarla, ejecuta npx @chatfuel/wizard update, que informa qué cambió.
• .env con el token, el ID del espacio de trabajo, el nombre de la app y el logo, además de .env.example con todas las variables que lee la app.
• .chatfuel/lock.json, el registro de lo que escribió el wizard, que lee update.
• Skills y un archivo de instrucciones para tu agente de programación: CLAUDE.md para Claude Code y AGENTS.md para Codex. Agentes de programación y skills los explica.
• Un Dockerfile y un script de despliegue en Vercel para producción, descritos en despliega tu app.

Después, el wizard te ofrece, con un sí o un no cada vez: desplegar en Vercel, subir el código a GitHub, abrir tu agente de programación en la nueva app e iniciar el servidor de desarrollo. Aunque rechaces todas las ofertas, la app queda completa.

Cómo iniciar la app y comprobar que funciona

Inicia el servidor de desarrollo en el directorio de la app:

npm run dev

La app se abre en http://localhost:5173. El primer módulo instalado se abre en / y los demás módulos están en la barra lateral. La barra superior muestra todos los espacios de trabajo a los que llega tu token y los bots de cada uno; esa lista se lee en vivo desde la API, así que verla demuestra que el token llegó a Chatfuel. Cada pantalla tiene una dirección real, como /contacts o /bookings, así que al recargar vuelves a la misma pantalla.

Cómo protege la app tu token

El token de API personal puede leer y cambiar todos los bots de tu cuenta, así que la app nunca lo envía al navegador. El navegador llama al propio servidor de la app en /chatfuel/*, y un proxy en ese servidor agrega el token y reenvía la solicitud a Chatfuel. Es el patrón de servidor a servidor que pide la descripción general de la Public API, ya integrado: el navegador nunca se comunica directamente con la API de Chatfuel y nada con nombre VITE_* guarda un secreto.

Otros comandos del wizard

npx @chatfuel/wizard --embed   # add the modules to a project you already have
npx @chatfuel/wizard doctor    # show what the wizard can see before it asks anything
npx @chatfuel/wizard update    # bring an app it made up to the current wizard
npx @chatfuel/wizard auth      # replace the stored Chatfuel token

--embed copia los módulos en src/chatfuel/ de un proyecto existente y deja la conexión en manos de tu agente de programación, que sigue la guía de integración que instala el wizard. Si ya existe un .env, el wizard le agrega líneas y nunca lo reemplaza.

Problemas comunes

The token was rejected (Unauthorized).

El wizard solo acepta el token de API personal (CLI token) de la página del token. Vuelve a copiarlo sin espacios. La clave API más antigua de la configuración de un bot es una clave distinta y aquí no funciona.

exists and is not empty

El directorio de destino ya tiene archivos. Elige un directorio nuevo o elimina primero el anterior.

El wizard se detiene justo después de iniciar

El wizard necesita Node.js 22.19.0 o una versión más reciente y una terminal interactiva. Actualiza Node.js o, para un trabajo de CI, pasa --yes con las respuestas como flags.