Como criar um bot de WhatsApp (e as opções que existem)

Criar um bot de WhatsApp é mais uma decisão do que um tutorial. O WhatsApp não tem um portal aberto para qualquer número, como o Discord tem. Existem dois caminhos: bibliotecas da comunidade que se passam por um aparelho vinculado ao seu número, e a Cloud API oficial da Meta, feita para empresas.

A escolha define o que vem depois: que número você usa, se há risco de banimento, quanto custa e se você precisa de um domínio com HTTPS. Este guia compara as opções, monta um bot funcional com Baileys e mostra o primeiro envio pela Cloud API.

Quais são as opções para criar um bot de WhatsApp?#

Os mantenedores do Baileys avisam que o projeto não tem vínculo com o WhatsApp e que não apoia uso que viole os Termos de Serviço. Por isso, notificações em volume ou o número de uma empresa que não pode ficar fora do ar pedem a Cloud API. Para o comparativo completo, veja Baileys, whatsapp-web.js ou API oficial.

Regra prática: para bot pessoal, estudo ou grupo de amigos, use uma biblioteca com um chip separado. Para atendimento, vendas ou qualquer coisa que gere receita, use a Cloud API.

O que você precisa antes de começar?#

• A versão LTS ativa do Node.js, que atende ao mínimo do campo engines do Baileys 7.
• Um número de WhatsApp dedicado ao bot, de preferência um chip que não seja o seu principal.
• O WhatsApp instalado no celular desse número.
• Para a Cloud API: uma conta de desenvolvedor na Meta, um app com o produto WhatsApp e, para receber mensagens, uma URL pública com HTTPS.

Como criar um bot de WhatsApp com Baileys?#

Crie o projeto. O Baileys 7 é um módulo ES, por isso o type=module:

npm init -y
npm pkg set type=module
npm install baileys

O código abaixo usa a API do Baileys 7. Confira no npm para qual versão a tag latest aponta antes de instalar; a série 6.x continua publicada como legacy e tem API diferente, então tutoriais antigos podem não rodar.

Defina WA_PHONE com o número do bot, só dígitos e com código do país (por exemplo 5562999999999). Crie o index.js:

import makeWASocket, {
  DisconnectReason,
  useMultiFileAuthState,
} from "baileys";

const AUTH_DIR = process.env.AUTH_DIR ?? "auth_info";
const PHONE = process.env.WA_PHONE;

async function start() {
  const { state, saveCreds } = await useMultiFileAuthState(AUTH_DIR);
  const sock = makeWASocket({ auth: state });
  let pairingRequested = false;

  sock.ev.on("creds.update", saveCreds);

  sock.ev.on("connection.update", async ({ connection, lastDisconnect, qr }) => {
    // Primeira execução: sem sessão salva, pede um código de pareamento.
    // O evento qr se repete; o código é pedido uma vez por conexão.
    if (qr && !pairingRequested && !sock.authState.creds.registered) {
      if (!PHONE) return console.error("Defina WA_PHONE para parear.");
      pairingRequested = true;
      console.log("Código de pareamento:", await sock.requestPairingCode(PHONE));
    }

    if (connection === "open") console.log("Conectado ao WhatsApp.");

    if (connection === "close") {
      const code = lastDisconnect?.error?.output?.statusCode;
      if (code === DisconnectReason.loggedOut) {
        console.error("Sessão encerrada pelo celular. Apague a pasta e pareie de novo.");
        process.exit(1);
      }
      start(); // queda de rede ou reinício pedido pelo WhatsApp: reconecta
    }
  });

  sock.ev.on("messages.upsert", async ({ messages, type }) => {
    if (type !== "notify") return;
    for (const msg of messages) {
      if (msg.key.fromMe || !msg.message) continue;
      const text =
        msg.message.conversation ?? msg.message.extendedTextMessage?.text;
      if (text?.trim().toLowerCase() === "!ping") {
        await sock.sendMessage(msg.key.remoteJid, { text: "pong" });
      }
    }
  });
}

start();

Rode com WA_PHONE=5562999999999 node index.js. No celular do bot, abra Dispositivos conectados, vincule com número de telefone e digite o código que apareceu no log. Se preferir QR code, ele chega no campo qr do evento connection.update: a opção printQRInTerminal das versões antigas foi descontinuada e não imprime mais o QR.

Como verificar que funcionou?#

O log mostra "Conectado ao WhatsApp." Mande !ping de outro número para o bot e espere pong. Pare o processo e rode de novo: ele deve conectar sozinho, sem pedir código, porque a sessão está na pasta auth_info.

Trate essa pasta como uma senha. Não a coloque no Git e não a apague num deploy, ou o bot vira um aparelho novo e precisa parear de novo. Para o passo seguinte, veja como manter o bot online 24/7.

E o whatsapp-web.js?#

O whatsapp-web.js controla um WhatsApp Web real dentro de um Chromium via Puppeteer. A API é simples (client.on("message", ...) e msg.reply(...)) e você entra escaneando um QR. O custo é memória: um navegador inteiro roda junto com o bot. Em servidores e containers, sobretudo rodando como root, o Chromium costuma precisar de flags como --no-sandbox. Se o bot é pequeno e você quer pouca RAM, o Baileys costuma ser mais leve.

Como enviar a primeira mensagem pela Cloud API?#

Na Cloud API não há pareamento. No painel de desenvolvedores da Meta, crie um app com o produto WhatsApp e, em API Setup, selecione o número de teste e copie o ID dele. O token temporário gerado ali expira rápido. Para produção, crie um usuário de sistema nas configurações da empresa e gere um token permanente com as permissões business_management, whatsapp_business_messaging e whatsapp_business_management.

O envio é uma chamada HTTP. A versão da Graph API vai na URL, aqui na variável GRAPH_VERSION (no formato vXX.0); use a mais recente listada no changelog de versões da Graph API:

curl -X POST "https://graph.facebook.com/$GRAPH_VERSION/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $WA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5562999999999",
    "type": "text",
    "text": { "body": "Olá do meu bot!" }
  }'

Duas regras definem o uso. A primeira é a janela de atendimento: quando um usuário escreve para você, abre-se uma janela de 24 horas, renovada a cada nova mensagem dele. Dentro dela você responde com texto livre; fora dela, só com modelos (templates) pré-aprovados. A segunda é o preço: desde 1º de julho de 2025, a Meta cobra por mensagem de modelo entregue. Veja a página de preços da Meta e quanto custa a API oficial.

Para receber mensagens, a Meta chama o seu webhook. Ela confirma o endpoint com um GET contendo hub.mode, hub.verify_token e hub.challenge: se o token bater, responda 200 com o hub.challenge. Os POST vêm assinados em X-Hub-Signature-256 (HMAC-SHA256 do corpo bruto com o segredo do app). O certificado precisa ser válido: autoassinado não funciona. O servidor completo está em como hospedar um bot de WhatsApp 24/7.

Quais são os erros mais comuns?#

• Pedir código de novo a cada reinício: a pasta de autenticação foi apagada ou não é persistente. Veja bot de WhatsApp desconectando.
• Duas instâncias com a mesma sessão: uma derruba a outra. Rode só uma.
• Seguir um tutorial antigo do Baileys: printQRInTerminal e imports antigos mudaram na versão 7. Fixe a versão no npm install.
• Texto recusado na Cloud API: a janela de 24 horas fechou. Use um modelo aprovado.
• Webhook que a Meta não valida: URL sem HTTPS válido, ou hub.verify_token diferente do configurado.
• Número banido: bibliotecas não oficiais, sobretudo com envio em massa, arriscam o número. Use um chip separado.

Como fazer isso na Square Cloud#

Na Square Cloud, a hospedagem é self-service: você faz o deploy e controla memória, variáveis e reinícios. Baileys, WPPConnect, whatsapp-web.js e a Cloud API oficial são suportados, então a escolha entre eles continua sua.

Para o bot deste guia, envie o projeto por ZIP no painel, pela CLI, pelo GitHub ou pela extensão do VS Code, e defina WA_PHONE e as demais variáveis nas configurações da aplicação. A pasta de autenticação fica no disco da aplicação, então a sessão continua conectada depois de um restart. Os containers ficam sempre ligados, com reinício automático (ligado por padrão no deploy pelo painel) quando o processo encerra com erro. Se você escolher a Cloud API, a aplicação web ganha um subdomínio squareweb.app com HTTPS, que pode servir de URL do webhook.

Todos os planos são pagos, em reais. O Hobby custa R$ 12,49 por mês, com 1 GB de RAM compartilhado entre as suas aplicações; o mínimo é 256 MB por aplicação de fundo, como um bot, e 512 MB por aplicação web. Veja a página de hospedagem de bots de WhatsApp.