Como criar um bot de WhatsApp com Node.js — template com fluxos e sessões

Criei um boilerplate para bots de WhatsApp que vai além do exemplo básico de "responder mensagem".
A ideia era ter uma base reutilizável com estrutura modular, sistema de fluxos e sessões por usuário.

O problema com a maioria dos tutoriais

Quase todo tutorial de bot de WhatsApp em Node.js mostra só isso:

client.on('message', message => {
    if (message.body === 'ping') {
        message.reply('pong');
    }
});

Funciona, mas não escala. Assim que você precisa de menus, submenus ou manter estado por usuário,
o código vira um espaguete de if/else.

A solução: fluxos + sessões

O template usa um roteador central que direciona cada mensagem para o fluxo correto,
e um Map de sessões que mantém o estado individual de cada usuário:

// Cada usuário tem seu próprio estado
const sessions = new Map();

// router.js decide para onde cada mensagem vai
async function router(message, sessions) {
    const body = message.body.toLowerCase().trim();
    const from = message.from;

    if (['oi', 'olá', 'menu', 'start'].includes(body)) {
        return mainMenu(message, sessions);
    }

    const session = sessions.get(from);
    if (session) {
        return mainMenu(message, sessions);
    }
}

Estrutura do projeto

src/
├── flows/
│   ├── router.js      # Toda mensagem passa por aqui
│   └── mainMenu.js    # Fluxo do menu com sessões por usuário
├── commands/
│   └── ping.js        # Exemplo de comando por palavra-chave
├── middlewares/
│   └── logger.js      # Log no terminal
└── utils/
    └── messages.js    # Todos os textos centralizados

Textos centralizados

Um detalhe que faz diferença na manutenção: todos os textos ficam em um único arquivo.

const MESSAGES = {
    mainMenu: `👋 Olá! Como posso ajudar?

*1* - Produtos
*2* - Suporte
*3* - Encerrar`,
};

Assim você nunca precisa caçar strings espalhadas pelo código quando o cliente quer mudar uma mensagem.

Integração com IA

A estrutura está preparada pra isso. É só criar um novo fluxo e registrar no router:

// src/flows/iaFlow.js
async function iaFlow(message) {
    const completion = await openai.chat.completions.create({
        model: 'gpt-4o-mini',
        messages: [{ role: 'user', content: message.body }],
    });
    return message.reply(completion.choices[0].message.content);
}

Como usar

git clone https://github.com/ericnacif/template-bot-whatsapp.git
cd template-bot-whatsapp
npm install
node index.js

Escaneia o QR Code no terminal com o WhatsApp. A sessão é salva localmente.