Build an App on the Public API with the Chatfuel Wizard

The Chatfuel wizard (@chatfuel/wizard) is a command-line tool that writes a complete web app on top of the Chatfuel Public API: an operator inbox, a CRM, deals, bookings, the AI Agent settings and more, as React and Vite source code you own. It runs once, asks a few questions and leaves an ordinary project wired to your Chatfuel workspace, plus skills that let a coding agent such as Claude Code or Codex keep building it. The wizard and the app it writes are open source under the MIT license, at github.com/chatfuel-lab/wizard.

What you need before you run the wizard

• Node.js 22.19.0 or newer. Check with node --version. On an older version the wizard stops before it loads anything and prints the install command for your platform.
• A terminal. The wizard asks questions, so it needs an interactive terminal. For CI and scripts, --yes with the answers as flags runs it unattended.
• Your personal API token, called the CLI token in the dashboard. Copy it from the token page. Authentication explains what this token can do.
• A coding agent (optional). The wizard looks for Claude Code and Codex CLI and offers to install one if it finds neither.

Nothing else needs to be installed or cloned first: the wizard installs the app's dependencies itself.

How to run the wizard

Run one command in the directory where the app should be created:

npx @chatfuel/wizard

The wizard asks its questions in this order:

1. New app or existing project. A new app is the default. The other answer adds the modules to a project you already have (--embed).
2. Modules. Pick the parts of the app you want; wizard modules lists every one. A module that needs another brings it along, and the wizard offers the modules your picks recommend.
3. Coding agent and skills location. With both Claude Code and Codex installed, the wizard asks which one continues the work. The skills go into the project or into your home directory, for one copy across every app.
4. Chatfuel token. Paste the personal API token. The wizard checks it against the Chatfuel API, asks again up to three times if it is rejected, and saves it to .env with file mode 0600.
5. Workspace. Asked only when your account has more than one; an account with none gets its first workspace here. The app reads the bots inside the workspace at runtime, so a bot you create later appears without a re-run.
6. Plan. When the workspace has no subscription yet, the wizard shows the Chatfuel plans and a link to start a trial.
7. App name and logo. The name defaults to the workspace title and appears in the browser tab, the top bar and the sign-in screen. The logo can be an svg, png, jpg, webp, gif or ico file.
8. Allowed browser origins. The app's own origin is the recommended answer. * is for local development only: a deployed app refuses to start with it.
9. Directory. ./chatfuel-app unless you name another. The directory must be empty or not exist yet.

The auth and admin modules add their own questions: the Supabase project for sign-in, and the admin panel password.

What the wizard writes

The wizard copies the app, writes .env, installs the skills and installs the dependencies. The result is a Vite, React and TypeScript project:

• One directory per module under src/modules/<id>/. Modules you did not pick leave no code behind.
• The design system, the typed GraphQL client and the proxy copied in as source, not as npm packages. A release of the wizard cannot break your app; an upgrade is npx @chatfuel/wizard update, which reports what changed.
• .env with the token, the workspace ID, the app name and the logo, plus .env.example listing every variable the app reads.
• .chatfuel/lock.json, the record of what the wizard wrote, which update reads.
• Skills and an instructions file for your coding agent: CLAUDE.md for Claude Code, AGENTS.md for Codex. Coding agents and skills covers them.
• A Dockerfile and a Vercel deploy script for production, described in deploy your app.

Then the wizard offers, one yes or no at a time: deploy to Vercel, push the code to GitHub, launch your coding agent in the new app, and start the dev server. Decline every offer and the app is still complete.

How to start the app and check that it works

Start the dev server in the app directory:

npm run dev

The app opens at http://localhost:5173. The first installed module opens at /, and the other modules are in the sidebar. The top bar lists every workspace your token can reach and the bots inside each; that list is read live from the API, so seeing it proves the token reached Chatfuel. Every screen has a real address, such as /contacts or /bookings, so a reload returns to the same screen.

How the app keeps your token safe

The personal API token can read and change every bot in your account, so the app never sends it to the browser. The browser calls the app's own server at /chatfuel/*, and a proxy on that server adds the token and forwards the request to Chatfuel. This is the server-to-server pattern the Public API overview asks for, built in: the browser never talks to the Chatfuel API directly, and nothing named VITE_* holds a secret.

Other wizard commands

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 copies the modules into src/chatfuel/ of an existing project and leaves the wiring to your coding agent, which follows the embed playbook the wizard installs. An existing .env is appended to, never replaced.

Common issues

The token was rejected (Unauthorized).

The wizard accepts only the personal API token (CLI token) from the token page. Copy it again without spaces. The older API key from a bot's settings is a different key and does not work here.

exists and is not empty

The target directory already has files in it. Pick a new directory, or remove the old one first.

The wizard stops right after it starts

The wizard needs Node.js 22.19.0 or newer and an interactive terminal. Update Node.js, or for a CI job pass --yes with the answers as flags.