Crie um app sobre a Public API com o Chatfuel wizard

O Chatfuel wizard (@chatfuel/wizard) é uma ferramenta de linha de comando que escreve um app web completo sobre a Public API do Chatfuel: uma caixa de entrada para operadores, um CRM, negócios, agendamentos, as configurações do AI Agent e mais, como código-fonte React e Vite que é seu. Ele roda uma vez, faz algumas perguntas e deixa um projeto comum conectado ao seu workspace do Chatfuel, além de skills que permitem que um agente de programação como o Claude Code ou o Codex continue a construí-lo. O wizard e o app que ele escreve são de código aberto sob a licença MIT, em github.com/chatfuel-lab/wizard.

O que você precisa antes de executar o wizard

• Node.js 22.19.0 ou mais recente. Confira com node --version. Em uma versão mais antiga, o wizard para antes de carregar qualquer coisa e mostra o comando de instalação para a sua plataforma.
• Um terminal. O wizard faz perguntas, então precisa de um terminal interativo. Para CI e scripts, --yes com as respostas como flags o executa sem interação.
• O seu token de API pessoal, chamado de CLI token no painel. Copie-o da página do token. Autenticação explica o que esse token pode fazer.
• Um agente de programação (opcional). O wizard procura o Claude Code e o Codex CLI e oferece instalar um deles se não encontrar nenhum.

Não é preciso instalar nem clonar mais nada antes: o wizard instala sozinho as dependências do app.

Como executar o wizard

Execute um único comando no diretório onde o app deve ser criado:

npx @chatfuel/wizard

O wizard faz as perguntas nesta ordem:

1. App novo ou projeto existente. Um app novo é o padrão. A outra resposta adiciona os módulos a um projeto que você já tem (--embed).
2. Módulos. Escolha as partes do app que você quer; módulos do wizard lista cada um deles. Um módulo que precisa de outro o traz junto, e o wizard oferece os módulos que as suas escolhas recomendam.
3. Agente de programação e local das skills. Com o Claude Code e o Codex instalados, o wizard pergunta qual deles continua o trabalho. As skills vão para o projeto ou para o seu diretório pessoal, para ter uma única cópia em todos os apps.
4. Token do Chatfuel. Cole o token de API pessoal. O wizard o verifica na API do Chatfuel, pergunta de novo até três vezes se ele for rejeitado e o salva em .env com o modo de arquivo 0600.
5. Workspace. Perguntado só quando a sua conta tem mais de um; uma conta sem nenhum ganha aqui o primeiro workspace. O app lê os bots do workspace em tempo de execução, então um bot que você criar depois aparece sem uma nova execução.
6. Plano. Quando o workspace ainda não tem assinatura, o wizard mostra os planos do Chatfuel e um link para iniciar um período de teste.
7. Nome e logo do app. O nome padrão é o título do workspace e aparece na aba do navegador, na barra superior e na tela de login. O logo pode ser um arquivo svg, png, jpg, webp, gif ou ico.
8. Origens de navegador permitidas. A própria origem do app é a resposta recomendada. * é só para desenvolvimento local: um app implantado se recusa a iniciar com esse valor.
9. Diretório. ./chatfuel-app, a menos que você indique outro. O diretório precisa estar vazio ou ainda não existir.

Os módulos auth e admin acrescentam as próprias perguntas: o projeto do Supabase para o login e a senha do painel de administração.

O que o wizard escreve

O wizard copia o app, escreve o .env, instala as skills e instala as dependências. O resultado é um projeto Vite, React e TypeScript:

• Um diretório por módulo em src/modules/<id>/. Os módulos que você não escolheu não deixam nenhum código.
• O design system, o cliente GraphQL tipado e o proxy copiados como código-fonte, não como pacotes npm. Uma nova versão do wizard não pode quebrar o seu app; para atualizar, use npx @chatfuel/wizard update, que informa o que mudou.
• .env com o token, o ID do workspace, o nome do app e o logo, além do .env.example, que lista todas as variáveis que o app lê.
• .chatfuel/lock.json, o registro do que o wizard escreveu, que o update lê.
• Skills e um arquivo de instruções para o seu agente de programação: CLAUDE.md para o Claude Code, AGENTS.md para o Codex. Agentes de programação e skills trata deles.
• Um Dockerfile e um script de implantação na Vercel para produção, descritos em implante o seu app.

Depois, o wizard faz algumas ofertas, uma de cada vez, para você responder sim ou não: implantar na Vercel, enviar o código para o GitHub, iniciar o seu agente de programação no novo app e iniciar o servidor de desenvolvimento. Se você recusar todas, o app continua completo.

Como iniciar o app e verificar se ele funciona

Inicie o servidor de desenvolvimento no diretório do app:

npm run dev

O app abre em http://localhost:5173. O primeiro módulo instalado abre em /, e os outros módulos ficam na barra lateral. A barra superior lista todos os workspaces que o seu token alcança e os bots de cada um; essa lista é lida ao vivo da API, então vê-la prova que o token chegou ao Chatfuel. Cada tela tem um endereço real, como /contacts ou /bookings, então recarregar a página volta para a mesma tela.

Como o app mantém o seu token seguro

O token de API pessoal pode ler e alterar todos os bots da sua conta, então o app nunca o envia para o navegador. O navegador chama o próprio servidor do app em /chatfuel/*, e um proxy nesse servidor adiciona o token e encaminha a requisição ao Chatfuel. Esse é o padrão servidor a servidor que a visão geral da Public API pede, já embutido: o navegador nunca fala diretamente com a API do Chatfuel, e nada com nome VITE_* guarda um segredo.

Outros comandos do 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 os módulos para src/chatfuel/ de um projeto existente e deixa a integração com o resto do código para o seu agente de programação, que segue o playbook de incorporação que o wizard instala. Um .env existente recebe acréscimos e nunca é substituído.

Problemas comuns

The token was rejected (Unauthorized).

O wizard aceita apenas o token de API pessoal (CLI token) da página do token. Copie-o de novo, sem espaços. A chave API mais antiga, das configurações de um bot, é uma chave diferente e não funciona aqui.

exists and is not empty

O diretório de destino já contém arquivos. Escolha um diretório novo ou remova o antigo primeiro.

O wizard para logo depois de iniciar

O wizard precisa do Node.js 22.19.0 ou mais recente e de um terminal interativo. Atualize o Node.js ou, em um job de CI, passe --yes com as respostas como flags.