Baileys, whatsapp-web.js ou API oficial: como escolher

Quem quer criar um bot de WhatsApp esbarra logo numa escolha: usar uma biblioteca da comunidade ou a API oficial. As duas bibliotecas mais citadas, Baileys e whatsapp-web.js, conectam sem aprovação da Meta e funcionam em qualquer número. A Cloud API exige conta comercial, mas é o caminho que o WhatsApp autoriza.

Não existe vencedor universal: um bot pessoal, o atendimento de uma empresa e um serviço de notificações pedem soluções diferentes.

O que é o Baileys?#

O Baileys é uma biblioteca TypeScript que fala direto com os servidores do WhatsApp por WebSocket, como um dispositivo vinculado ao seu número. Não abre navegador. É código aberto (MIT), mantido pela comunidade WhiskeySockets.

A versão 7 trouxe mudanças incompatíveis com a 6.x (a linha antiga ganhou a tag legacy no npm), então tutoriais antigos podem não rodar. Confira a versão atual no npm antes de seguir um exemplo. O projeto avisa que não tem vínculo com o WhatsApp e que não apoia uso que viole os termos do serviço. Para o código completo de um bot com sessão persistente, veja como hospedar um bot de WhatsApp 24/7.

O que é o whatsapp-web.js?#

O whatsapp-web.js usa o Puppeteer para controlar uma instância real do WhatsApp Web dentro de um Chromium e chamar as funções internas dela. Exige uma versão recente do Node.js. Mantenha a biblioteca atualizada, porque ela precisa acompanhar as mudanças do WhatsApp Web.

Como roda um navegador completo, consome mais memória e CPU que o Baileys, e a instalação baixa o Chromium. Em compensação, a API é direta e a comunidade é grande. O README é claro: o WhatsApp não permite bots nem clientes não oficiais, então a biblioteca não deve ser considerada totalmente segura.

Um bot mínimo, com npm install whatsapp-web.js qrcode-terminal:

const { Client, LocalAuth } = require("whatsapp-web.js");
const qrcode = require("qrcode-terminal");

const client = new Client({
  authStrategy: new LocalAuth({ dataPath: process.env.AUTH_DIR ?? ".wwebjs_auth" }),
  // Em servidor sem interface gráfica, o Chromium precisa destas flags.
  puppeteer: { args: ["--no-sandbox", "--disable-setuid-sandbox"] },
});

client.on("qr", (qr) => qrcode.generate(qr, { small: true }));
client.on("ready", () => console.log("Conectado ao WhatsApp."));
client.on("message", async (msg) => {
  if (msg.body.trim().toLowerCase() === "!ping") await msg.reply("pong");
});

client.initialize();

Na primeira execução, escaneie o QR do terminal em Dispositivos conectados no celular. O LocalAuth grava a sessão na pasta .wwebjs_auth (ou no dataPath), então ela só sobrevive a reinícios se o disco for persistente. Para vários clientes, use um clientId por sessão.

O que é a Cloud API oficial?#

A Cloud API é a interface hospedada pela Meta. Você precisa de um portfólio empresarial, de uma conta do WhatsApp Business e de um número de telefone comercial. Não há sessão nem pareamento: você chama a Graph API com um token para enviar, e recebe mensagens e status de entrega por webhook, que exige uma URL pública com HTTPS válido.

Duas regras moldam o uso. A primeira é a janela de atendimento de 24 horas: ela abre quando o usuário escreve, e 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, e texto livre dentro da janela não é cobrado. Os valores variam por categoria e país, então confira a página de preços da Meta. O guia como fazer um bot de WhatsApp mostra a implementação, e quanto custa a API do WhatsApp Business detalha as contas.

A Meta também limita o ritmo: há um teto de mensagens por segundo para cada número comercial e um intervalo mínimo entre mensagens para o mesmo usuário. Confira os valores atuais na documentação da Cloud API.

Como as três se comparam?#

O risco de banimento é o mesmo para as duas bibliotecas, porque as duas se passam por um cliente que o WhatsApp não autorizou. Veja também por que um bot de WhatsApp é banido e por que ele desconecta.

Quando escolher cada uma?#

• Bot pessoal, estudo ou projeto de baixo risco: Baileys, se você quer pouca memória e aceita ler documentação em evolução. whatsapp-web.js, se prefere a API mais simples e tem RAM de sobra.
• Automação no seu número pessoal: só as bibliotecas não oficiais atendem, já que a Cloud API exige número comercial. Aceite que o número pode ser banido e não use o seu principal.
• Atendimento de empresa, vendas ou notificações: Cloud API. O custo por modelo é previsível, e o número não corre o risco de banimento por usar cliente não oficial.
• Disparo em massa: não use biblioteca não oficial. Mensagens automatizadas em volume são justamente o que leva ao banimento. Na Cloud API, o envio fica sujeito aos limites e à qualidade dos modelos.

Se ainda estiver em dúvida, pergunte: o número é de um negócio que não pode ficar fora do ar? Se sim, Cloud API.

Como fazer isso na Square Cloud#

Qualquer que seja a escolha, o bot precisa de um processo ligado o tempo todo. A Square Cloud é hospedagem self-service: você faz o deploy e controla memória, variáveis e reinícios no painel. Ela suporta Baileys, WPPConnect, whatsapp-web.js e a Cloud API oficial, então a decisão continua sua.

A pasta de autenticação fica no disco da aplicação, então a sessão do Baileys ou do whatsapp-web.js continua conectada depois de um restart. Os containers ficam sempre ligados, sem modo de suspensão, com reinício automático (ligado por padrão no deploy pelo painel) quando o processo encerra com erro. Como o whatsapp-web.js roda um Chromium, teste o consumo e ajuste a RAM da aplicação nas configurações. Para a Cloud API, a aplicação web ganha um subdomínio squareweb.app com HTTPS, que pode servir de URL para o webhook.

Todos os planos são pagos e cobrados em reais. O Hobby começa em R$ 12,49 por mês, com 1 GB de RAM compartilhado entre as suas aplicações. O mínimo é de 256 MB por aplicação de fundo, como um bot, e de 512 MB por aplicação web. O deploy pode ser por ZIP, CLI, GitHub ou extensão do VS Code. Veja a página de hospedagem de bots de WhatsApp.