--- title: "Crie um app sobre a Public API com o Chatfuel wizard" description: "Rode npx @chatfuel/wizard e tenha um app React na Public API do Chatfuel: caixa de entrada, CRM, agendamentos e ajustes de IA em código seu, token no servidor." canonical_url: https://chatfuel.com/pt/docs/wizard/quickstart markdown_url: https://chatfuel.com/pt/docs/wizard/quickstart.md last_updated: 2026-10-27 lang: pt site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/docs/llms.txt --- # Crie um app sobre a Public API com o Chatfuel wizard Rode npx @chatfuel/wizard e tenha um app React na Public API do Chatfuel: caixa de entrada, CRM, agendamentos e ajustes de IA em código seu, token no servidor. 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](https://github.com/chatfuel-lab/wizard). ## O que você precisa antes de executar o 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](https://panel.chatfuel.com/integration/auth/token). [Autenticação](https://chatfuel.com/pt/docs/public-api/authentication) 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 [#como-executar-o-wizard] Execute um único comando no diretório onde o app deve ser criado: ```bash 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](https://chatfuel.com/pt/docs/wizard/modules) 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-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//`. 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](https://chatfuel.com/pt/docs/wizard/coding-agents) trata deles. * **Um `Dockerfile` e um script de implantação na Vercel** para produção, descritos em [implante o seu app](https://chatfuel.com/pt/docs/wizard/deploy). 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 [#como-iniciar-o-app-e-verificar-se-ele-funciona] Inicie o servidor de desenvolvimento no diretório do app: ```bash 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 [#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](https://chatfuel.com/pt/docs/public-api/overview) 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 [#outros-comandos-do-wizard] ```bash 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 [#problemas-comuns] ### The token was rejected (Unauthorized). [#the-token-was-rejected-unauthorized] O wizard aceita apenas o token de API pessoal (**CLI token**) da [página do token](https://panel.chatfuel.com/integration/auth/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 [#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-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.