Como criar um chatbot inteligente usando vibe coding e Z-API
A forma de desenvolver software está mudando. Em vez de escrever manualmente cada etapa, os desenvolvedores podem descrever funcionalidades em linguagem natural e utilizar IA para gerar e ajustar código.
Essa abordagem ficou conhecida como vibe coding. O termo ganhou força em 2025 para descrever um processo baseado em prompts, testes rápidos e refinamento contínuo do software gerado por IA.
A técnica pode acelerar protótipos, mas não elimina a necessidade de revisar código, testar integrações e aplicar controles de segurança antes de colocar uma aplicação em produção.
Neste guia, você vai criar um chatbot conectado ao WhatsApp pelo Z-API, usando vibe coding para estruturar a aplicação, processar mensagens, realizar triagens e integrar outros sistemas.
O Z-API entra como camada de comunicação com o WhatsApp, permitindo receber eventos e enviar mensagens pela API. A proposta é começar com um MVP simples e evoluir para integrações com CRM, ERP, catálogo, agenda ou base de conhecimento.
Você já desenvolve com vibe coding?
Vibe coding é um termo popularizado para descrever a criação de software por meio de instruções em linguagem natural, deixando que modelos de IA gerem e alterem grande parte do código.
Na definição original, a abordagem envolve dar mais atenção ao resultado do que ao código gerado. Quando o desenvolvedor revisa cuidadosamente a implementação, o processo se aproxima do desenvolvimento assistido por agentes de IA.
Uma instrução poderia ser:
| “Crie uma API em Node.js com Express que receba mensagens do WhatsApp por webhook, identifique o telefone, envie o texto para um modelo de linguagem e responda pelo Z-API. Use variáveis de ambiente para credenciais, logs, tratamento de erros e proteção contra mensagens enviadas pelo próprio número.” |
A IA gera uma primeira versão. Depois, a pessoa pode executá-la, testar os resultados e pedir ajustes.
Essa abordagem é especialmente útil para protótipos e integrações rápidas, mas o código gerado por IA não deve ser considerado automaticamente seguro ou correto. Aplicações em produção exigem testes e validação, principalmente quando acessam dados ou sistemas sensíveis.
Vibe coding acelera a construção; revisão e testes ajudam a tornar o resultado mais confiável.
Por que usar vibe coding para criar um chatbot?
Um chatbot no WhatsApp envolve recebimento de eventos, autenticação, interpretação do payload, IA, memória, regras de negócio e envio de respostas.
O vibe coding pode reduzir o caminho entre a ideia e o primeiro protótipo, permitindo testar rapidamente uma arquitetura antes de investir em uma implementação mais completa.
| Benefício | Aplicação no chatbot |
| Prototipação rápida | Criar uma primeira versão do atendimento |
| Menor barreira inicial | Gerar estruturas a partir de linguagem natural |
| Iteração contínua | Ajustar regras e funcionalidades rapidamente |
| Integração de APIs | Gerar chamadas ao Z-API e sistemas internos |
| Documentação inicial | Criar README e exemplos junto com o código |
| Personalização | Adaptar fluxos para diferentes jornadas |
O ganho não está em eliminar o desenvolvedor, mas em acelerar a construção para concentrar mais atenção no processo, na experiência e nas regras da aplicação.
Formação Agentes de IA
Domine a criação de Agentes de IA e Venda para Empresas
- 402 aulas
- 32 projetos
- 38h 19min
O que é o Z-API nessa arquitetura?
O Z-API funciona como a camada de comunicação entre o WhatsApp e a aplicação do chatbot.
A aplicação recebe mensagens por webhook e utiliza a API para enviar respostas ao contato. O webhook de recebimento pode ser configurado pelo endpoint update-webhook-received, com uma URL HTTPS.
Depois do processamento, a resposta pode ser enviada por POST /send-text, utilizando phone e message no corpo da requisição.
A arquitetura básica é:
WhatsApp → Z-API → aplicação → IA + regras + integrações → Z-API → WhatsApp
O Z-API não é o cérebro do chatbot, mas a infraestrutura que o fará responder automaticamente. Por isso, a inteligência, memória, regras e integrações ficam na aplicação construída pela equipe.
Antes de começar: defina o escopo do MVP
Um erro comum ao usar IA para gerar código é pedir “um chatbot completo” sem definir o que ele deve fazer.
Comece por uma tarefa clara, como responder dúvidas frequentes, fazer triagem de leads ou consultar pedidos.
Um MVP pode ter cinco funções:
- Receber uma mensagem.
- Identificar contato e conteúdo.
- Gerar uma resposta.
- Enviar pelo Z-API.
- Encaminhar para uma pessoa quando necessário.
Depois que esse fluxo estiver validado, você pode adicionar memória, CRM, catálogo, agenda e outras integrações.
Exemplo de briefing para o projeto
Antes de abrir sua ferramenta de vibe coding, escreva requisitos claros:
Quero criar um chatbot para o WhatsApp de uma loja de roupas.
Ele deve responder dúvidas sobre horários, formas de pagamento, entregas e trocas.
Responda em português brasileiro, de forma objetiva. Não invente preços, estoque ou prazos.
Quando o cliente pedir atendimento humano, reclamar de um pedido ou solicitar uma alteração, acione o fluxo de encaminhamento para a equipe.
A aplicação será feita em Node.js e receberá mensagens pelo webhook do Z-API.
Todas as credenciais devem ser lidas por variáveis de ambiente.
Um briefing claro reduz ambiguidades e ajuda a IA a gerar uma base mais coerente para o projeto.
Como pedir à IA para gerar o projeto?
Um bom prompt de vibe coding funciona como uma especificação inicial. Ele informa stack, endpoints, campos e regras da aplicação.
Use este exemplo:
Crie um projeto Node.js com Express para um chatbot conectado ao WhatsApp pelo Z-API.
Requisitos:
- criar uma rota POST /webhook/whatsapp;
- receber o payload do Z-API;
- extrair phone, text.message e messageId;
- ignorar mensagens sem telefone ou texto e eventos com fromMe: true;
- usar ZAPI_INSTANCE_ID, ZAPI_INSTANCE_TOKEN e ZAPI_CLIENT_TOKEN;
- criar uma função sendText(phone, message) usando o endpoint send-text;
- separar rotas, serviços e validações;
- usar variáveis de ambiente para credenciais;
- registrar logs sem tokens ou dados pessoais;
- incluir README, .env.example e testes básicos.
Explique os arquivos e comandos necessários. Não invente campos do payload: utilize a documentação do Z-API e indique o que precisa ser validado com um evento real.
O último ponto é importante porque diferentes tipos de mensagem possuem payloads próprios. Para texto, o Z-API documenta campos como phone, messageId, fromMe e text.message.
Exemplo prático de servidor em Node.js
O exemplo abaixo demonstra a lógica central e deve ser adaptado antes do uso em produção:
| import express from ‘express’; const app = express();app.use(express.json({ limit: ‘256kb’ })); const { PORT = 3000, ZAPI_INSTANCE_ID, ZAPI_INSTANCE_TOKEN, ZAPI_CLIENT_TOKEN} = process.env; function extractMessage(body) { return { phone: body.phone ? String(body.phone) : null, text: body.text?.message?.trim() ?? ”, messageId: body.messageId ?? null, fromMe: body.fromMe === true };} async function sendText(phone, message) { const url = `https://api.z-api.io/instances/${ZAPI_INSTANCE_ID}` + `/token/${ZAPI_INSTANCE_TOKEN}/send-text`; const headers = { ‘Content-Type’: ‘application/json’ }; if (ZAPI_CLIENT_TOKEN) { headers[‘Client-Token’] = ZAPI_CLIENT_TOKEN; } const response = await fetch(url, { method: ‘POST’, headers, body: JSON.stringify({ phone, message }) }); if (!response.ok) { throw new Error(`Erro Z-API: ${response.status}`); } return response.json();} async function generateReply(text) { // Substitua pela chamada ao modelo de IA. if (/horário|horario/i.test(text)) { return ‘Nosso atendimento funciona de segunda a sexta, das 9h às 18h.’; } return ‘Recebi sua mensagem. Como posso ajudar?’;} app.post(‘/webhook/whatsapp’, async (req, res) => { const { phone, text, messageId, fromMe } = extractMessage(req.body ?? {}); res.status(200).json({ received: true }); if (!phone || !text || fromMe) return; try { const reply = await generateReply(text); await sendText(phone, reply); console.log(JSON.stringify({ event: ‘message_processed’, messageId })); } catch (error) { console.error(JSON.stringify({ event: ‘message_processing_error’, messageId, error: error.message })); }}); app.listen(PORT, () => { console.log(`Chatbot ativo na porta ${PORT}`);}); |
O endpoint de texto do Z-API utiliza POST /send-text, com phone e message no corpo. O Client-Token deve ser enviado quando a validação dessa camada de segurança estiver ativada.
Em produção, generateReply deve chamar o modelo de IA e aplicar regras de negócio, validações e integrações necessárias.
Como configurar as variáveis de ambiente?
Nunca coloque credenciais diretamente no código. Crie um .env.example sem valores reais:
- PORT=3000
- ZAPI_INSTANCE_ID=seu_instance_id
- ZAPI_INSTANCE_TOKEN=seu_instance_token
- ZAPI_CLIENT_TOKEN=seu_client_token
- OPENAI_API_KEY=sua_chave_de_ia
Configure os valores reais no servidor ou em um gerenciador de segredos e mantenha o arquivo .env fora do controle de versão.
Você também pode pedir à IA:
| “Procure credenciais e tokens hardcoded em todos os arquivos. Substitua-os por variáveis de ambiente e informe quais valores precisam ser configurados.” |
Credenciais devem permanecer fora do código, dos logs e de qualquer conteúdo público.
Como conectar o chatbot a um modelo de IA?
A função generateReply pode chamar um modelo de linguagem utilizando instruções do sistema, mensagem do usuário e contexto necessário.
Um prompt inicial poderia ser:
| Você é o assistente virtual da Loja Aurora.Responda dúvidas sobre produtos, entrega, pagamento e trocas em português brasileiro e com clareza.Não invente preços, estoque, prazos ou políticas.Se a informação não estiver disponível, informe que precisa consultar a equipe.Não confirme compras ou ações sem retorno do sistema.Não solicite senhas ou dados de cartão.Reclamações, cancelamentos e pedidos de atendimento humano devem seguir o fluxo de handoff. |
Segurança não deve depender apenas do prompt. Dados como preço, estoque e status precisam vir dos sistemas responsáveis, enquanto permissões para executar ações devem ser controladas no backend.
Exemplo de fluxo com consulta de pedido
Se o cliente perguntar “Qual é o status do meu pedido 4582?”, o fluxo pode ser:
| Etapa | Responsabilidade |
| Identificação | Detectar a consulta de pedido |
| Autorização | Validar se o cliente pode acessar o pedido |
| Consulta | Buscar os dados no ERP ou e-commerce |
| Interpretação | Transformar o status em linguagem clara |
| Resposta | Enviar pelo Z-API |
| Registro | Atualizar CRM ou histórico |
O modelo interpreta a solicitação; o sistema fornece e autoriza o acesso aos dados.
Exemplo de chatbot com triagem comercial
Uma triagem inicial pode perguntar:
| “Olá, sou o assistente virtual da Aurora. Você quer: 1) conhecer produtos, 2) acompanhar um pedido, 3) trocar um item ou 4) falar com um atendente?” |
Durante a conversa, o sistema pode estruturar informações para o CRM:
| { “intent”: “interesse_comercial”, “category”: “camisas”, “budget”: “até R$ 300”, “urgency”: “esta semana”, “next_step”: “enviar catálogo”} |
Antes de registrar os dados, valide a estrutura e os campos permitidos.
Exemplo de handoff humano
Algumas situações devem interromper a automação, como pedido explícito de atendimento humano, reclamação, cancelamento, reembolso ou ações que exigem autorização.
Uma regra pode solicitar:
| Quando houver uma dessas situações, retorne needs_human=true, o motivo e uma mensagem para o cliente. Não execute a ação diretamente. |
Depois, a aplicação valida o resultado, pausa a automação e encaminha o contexto.
| “Vou encaminhar sua conversa para nossa equipe, junto com as informações que você já enviou.” |
Handoff não é falha do chatbot. É parte do desenho da operação.
Como pedir à IA para melhorar o código?
No vibe coding, prefira solicitações específicas e incrementais:
| “Adicione idempotência usando messageId. Para o protótipo, use memória local e explique como migrar para Redis.”“Crie testes para payload sem telefone, sem texto, mensagem própria, duplicada e erro no Z-API.”“Se o modelo de IA falhar, aplique uma resposta de contingência sem registrar credenciais nos logs.”“Separe regras de atendimento da camada HTTP.”“Revise riscos de autenticação, prompt injection, exposição de dados e abuso do webhook.” |
O ciclo deve ser: gerar, executar, testar, revisar e melhorar.
Como testar o chatbot antes de publicar?
Não teste apenas o caminho ideal.
| Caso | Resultado esperado |
| Saudação | Resposta objetiva |
| Pergunta válida | Informação confirmada |
| Fora do escopo | Limite declarado |
| Pedido de humano | Handoff |
| fromMe: true | Nenhuma resposta |
| Payload sem texto | Fluxo encerrado |
| Mensagem duplicada | Uma única execução |
| IA indisponível | Contingência e log |
| Erro no envio | Registro e tratamento |
| Texto excessivo | Limite ou tratamento |
Também teste mensagens simultâneas para verificar ordem, concorrência e contexto.
Vibe coding não substitui segurança
Código gerado rapidamente pode incluir autenticação fraca, dependências desnecessárias ou tratamento inadequado de dados.
Use revisão humana, testes, análise estática, dependências atualizadas e privilégio mínimo.
No webhook, limite o tamanho do corpo e valide as entradas. Mantenha tokens apenas no backend e evite registrar conversas completas sem necessidade.
Prompt injection também precisa ser considerada. Não confie apenas em instruções para impedir que entradas maliciosas influenciem o modelo.
Restrinja dados acessíveis, tools e ações possíveis e utilize confirmação adicional para operações sensíveis.
Como evoluir do protótipo para produção?
| Estágio | Prioridades |
| Protótipo | Webhook, resposta e variáveis de ambiente |
| Validação | Logs, testes e fallback |
| Operação inicial | Memória, CRM e handoff |
| Escala | Filas, idempotência e monitoramento |
| Operação avançada | Base de conhecimento, tools e permissões |
Não adicione integrações apenas porque a IA consegue gerá-las. Cada nova capacidade deve ter objetivos, permissões e regras definidos.
Boas práticas para usar vibe coding com o Z-API
- A primeira boa prática é fornecer contexto técnico suficiente à IA: linguagem, framework, endpoints, payloads, regras e limitações. Quanto mais claros os requisitos, menor o risco de gerar código incompatível.
- A segunda é trabalhar em pequenos incrementos. Primeiro receba a mensagem, depois envie uma resposta fixa, conecte a IA e só então adicione memória e integrações.
- A terceira é testar com payloads reais e exemplos documentados, evitando assumir campos sem confirmação.
- A quarta é manter regras críticas fora do modelo. A IA pode interpretar uma solicitação, mas decisões como cancelar uma compra ou liberar acesso a um pedido devem ser validadas pelo sistema.
- A quinta é monitorar erros, tempo de resposta, mensagens ignoradas, handoffs e resultados.
- A sexta é operar com relevância e respeito às preferências do usuário. O Z-API não é destinado a spam e recomenda evitar mensagens indesejadas. Também não existe estratégia capaz de eliminar totalmente o risco de bloqueios.
Checklist final
Antes de publicar, confirme se:
- o webhook utiliza HTTPS e recebe o payload esperado;
- tokens e credenciais estão protegidos;
- mensagens próprias e duplicadas são filtradas;
- entradas inválidas são tratadas;
- o agente possui escopo e limites claros;
- dados como estoque, preço e pedidos vêm de fontes confiáveis;
- ações críticas possuem validação no backend;
- existe handoff humano;
- erros e indisponibilidades são monitorados.
Teste falhas do modelo, do Z-API e dos sistemas internos. Se a IA falhar e o WhatsApp estiver disponível, o fluxo pode enviar uma resposta alternativa. Se o próprio envio falhar, registre o erro e alerte a operação.
Depois da publicação, acompanhe resolução, handoffs, erros, conversões e impacto sobre atendimento ou vendas.
Conclusão
Usar vibe coding para criar um chatbot com Z-API pode reduzir o caminho entre uma ideia e um protótipo funcional.
O Z-API conecta o WhatsApp à aplicação por API e webhooks. A IA interpreta mensagens e gera respostas, enquanto o backend controla regras, segurança, memória, integrações e handoff.
O resultado mais consistente surge quando a velocidade vem acompanhada de disciplina. Vibe coding acelera a construção, mas não substitui revisão técnica, testes, proteção de credenciais e monitoramento.
Se sua empresa quer criar chatbots ou conectar o WhatsApp a sistemas internos, o Z-API oferece API e webhooks para integrar o canal às suas aplicações.
Teste o Z-API gratuitamente e monte seu chatbot inteligente no WhatsApp.
Matheus Battisti
Formações
Formação Claude Code
Domine Claude Code do absoluto zero até o avançado
- 120 aulas
- 4 projetos
- 9h 45min
Blog | Mais populares
IoT e Ambientes Inteligentes: Como Integrar Soluções Físicas e Digitais
A transformação digital deixou de estar restrita aos computadores e smartphones. Hoje, ela faz parte da forma como residências, empresas, indústrias e espaços públicos funcionam […]
Como criar chatbot para WhatsApp sem programar
Criar um chatbot para WhatsApp já foi um projeto que praticamente começava com uma equipe de desenvolvimento, documentação de APIs e várias horas de configuração […]
Como automatizar posts no Instagram com IA: do prompt à publicação
Vamos aprender mais sobre um fluxo de automação que está cada vez mais comum entre quem cria conteúdo ou administra redes sociais de clientes: automatizar […]
