WPPConnect e Baileys: montar a própria API ou usar a apiwpp
WPPConnect e Baileys resolvem o protocolo, mas a fila, os webhooks com novas tentativas, o multi-tenant e o painel ficam com você. Compare com a apiwpp.
Atualizado em
Quem tem uma equipe de desenvolvimento e precisa do WhatsApp no sistema costuma considerar construir a própria API. Os pontos de partida mais comuns são dois projetos open source: o Baileys, uma biblioteca em TypeScript que fala o protocolo do WhatsApp Web por WebSocket, e o WPPConnect, que mantém uma biblioteca que controla o WhatsApp Web num navegador automatizado e um servidor REST construído sobre ela.
Os dois resolvem a parte mais difícil de entender: falar com o WhatsApp. Mas a distância entre "consigo enviar uma mensagem" e "tenho uma API em produção para os meus clientes" é grande. Esta página mostra o que fica faltando, compara os modelos em uma tabela e ajuda a decidir entre construir e usar uma API pronta como a apiwpp. Não é uma avaliação dos projetos, que são mantidos por comunidades ativas e fazem bem o que prometem.
O que Baileys e WPPConnect entregam
Baileys é uma biblioteca. Ela gera o QR code, mantém a sessão, envia e recebe mensagens e emite eventos da conexão. Não traz API HTTP, fila, painel nem webhooks: você escreve o serviço em volta dela. O glossário sobre Baileys resume o termo.
WPPConnect tem duas camadas. A biblioteca wppconnect controla uma instância do WhatsApp Web num navegador, e o WPPConnect Server expõe rotas REST para enviar mensagens e envia eventos para uma URL. É um passo além de uma biblioteca pura, mas continua sendo um software que você hospeda e opera.
Nos dois casos, a conexão é a mesma que a apiwpp usa: o número entra como aparelho conectado, pelo protocolo do WhatsApp Web.
Mesmo protocolo, mesmos riscos
Vale deixar isso claro antes de qualquer tabela: trocar de ferramenta não muda o que o WhatsApp vê. Baileys, WPPConnect e apiwpp não são a API oficial, não dão selo de conta oficial e não usam modelos aprovados pela Meta. O WhatsApp julga o comportamento do número, e o risco de restrição existe nos três caminhos.
A diferença está na operação: quem controla o ritmo de envio, quem guarda a sessão, quem percebe que o número caiu e quem garante que os eventos chegam ao seu sistema. Com uma biblioteca, tudo isso é código seu. Com a apiwpp, já vem pronto.
O que falta construir em cima
Estas são as camadas que uma API em produção precisa e que uma biblioteca de protocolo não entrega sozinha.
Fila com ritmo por número
Sem uma fila, o seu código envia tão rápido quanto o laço roda, e é justamente esse comportamento que chama a atenção do WhatsApp. Na apiwpp, cada número tem uma fila anti-bloqueio com limites padrão de 3 mensagens por minuto, 60 por hora e 200 por dia, intervalo aleatório de 3 a 8 segundos, pelo menos 30 segundos entre duas mensagens para a mesma pessoa e teto de 100 destinatários novos a cada 24 horas. Números recém-pareados passam por um aquecimento de 14 dias, com limites que sobem por etapa.
Webhooks com novas tentativas
Encaminhar um evento para uma URL é fácil. O difícil é o que acontece quando a URL está fora do ar. Os webhooks da apiwpp são assinados com HMAC-SHA256, entregues pelo menos uma vez, com até 6 tentativas em intervalos crescentes, pausa automática para um endpoint que está falhando, registro de cada entrega e reenvio das que falharam.
Idempotência
Se o seu sistema repete uma requisição depois de um timeout, a mensagem não pode sair duas vezes. Na apiwpp, o clientRef resolve isso: a repetição devolve o job original com "duplicate": true. Veja idempotência com clientRef.
Multi-tenant e chaves de acesso
Se você atende vários clientes, precisa separar números, eventos e credenciais de cada um. Na apiwpp, cada projeto tem o próprio webhook e as próprias chaves de API, com escopos, validade, revogação e rotação sem interrupção.
Painel, logs e cobrança
A sua equipe vai precisar ver o que aconteceu com uma mensagem, parear números por QR code sem abrir um terminal e cobrar os seus clientes. A apiwpp inclui painel com projetos, conexões, chaves e logs de mensagens e webhooks, e cobra por número conectado numa fatura só por organização.
Sessão, proxy e monitoramento
A sessão precisa ser guardada com segurança e sobreviver a reinícios; os números precisam de IPs com boa reputação; alguém precisa ser avisado quando uma conexão cai. Na apiwpp, a sessão fica salva e criptografada, cada número sai por um proxy brasileiro, e a status.apiwpp.com é alimentada por verificações de cada componente e por um teste que envia mensagens reais a cada 10 minutos.
Tabela por modelo
| Camada | Baileys (biblioteca) | WPPConnect Server (self-hosted) | apiwpp (gerenciada) |
|---|---|---|---|
| Conexão pelo protocolo | Sim | Sim | Sim |
| API HTTP | Você escreve | Incluída | Incluída, com OpenAPI 3.1 |
| Fila com ritmo e aquecimento | Você escreve | Você escreve ou configura | Incluída por número |
| Webhooks com novas tentativas e reenvio | Você escreve | Conforme o projeto e a versão | Assinados, 6 tentativas, registro e reenvio |
| Idempotência de envio | Você escreve | Você escreve | clientRef |
| Separação por cliente | Você escreve | Você configura | Projetos com chaves e webhook próprios |
| Painel e logs | Você escreve | Conforme o projeto | Incluídos |
| Cobrança dos seus clientes | Você escreve | Você escreve | Uma fatura por organização, por número |
| Hospedagem e atualizações | Você | Você | apiwpp |
| Controle sobre o código | Total | Total | Pela API |
A tabela compara modelos, não a qualidade dos projetos. Recursos de servidores open source mudam entre versões; confira a documentação de cada um.
Construir ou usar pronto
Construa sobre Baileys ou WPPConnect se
- o WhatsApp é o núcleo do seu produto e você quer controlar cada detalhe;
- tem equipe para construir e manter fila, webhooks, painel e monitoramento;
- precisa de algo que uma API pronta não oferece.
Use a apiwpp se
- o WhatsApp é um canal do seu produto, não o produto;
- quer integrar em dias, com uma chamada HTTP e um webhook;
- prefere pagar por número a manter mais uma infraestrutura.
Com a apiwpp, o envio é uma chamada HTTP, e a resposta 202 já diz quando a mensagem vai sair e em que posição da fila ela está:
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/send`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.APIWPP_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ to: '5511999998888', message: 'Olá! Seu horário está confirmado.', clientRef: 'agenda-8812' }),
})
if (res.status === 429) {
// Teto de destinatários novos: nada entrou na fila. Tente de novo depois de Retry-After segundos.
console.log('Reagendar em', res.headers.get('Retry-After'), 's')
} else {
console.log(await res.json()) // { jobId, scheduledAt, position }
}
O guia Evolution API, Baileys e WPPConnect aprofunda o custo total de hospedar, e o comparativo Evolution API self-hosted ou gerenciada traz a mesma análise para um servidor pronto.
Perguntas frequentes
A apiwpp é mais segura contra bloqueio do que Baileys ou WPPConnect?
O protocolo é o mesmo, então o WhatsApp avalia o número da mesma forma. A diferença é que a apiwpp já aplica fila, aquecimento de 14 dias e teto de destinatários novos em todo número; com uma biblioteca, esse controle depende do código que você escrever. Nenhum dos caminhos garante que um número nunca será restringido.
Dá para usar a apiwpp como base do meu próprio produto?
Sim. Cada cliente do seu produto pode ser um projeto, com chaves de API e webhook próprios, e o QR code de pareamento pode ser exibido dentro do seu sistema pela API. A cobrança é uma fatura só por organização, por número conectado.
Vou perder o controle sobre o código?
Você não edita o código do servidor, mas integra por uma API documentada em OpenAPI 3.1, com clientes TypeScript e PHP gerados da especificação. Se o seu caso exige alterar o próprio protocolo, construir sobre uma biblioteca é o caminho.
Como migro um número que hoje roda no Baileys ou no WPPConnect?
Desconecte o aparelho antigo no celular, pareie o número na apiwpp por QR code ou código de pareamento de 8 caracteres e troque o envio e o webhook no seu código. O aquecimento de 14 dias começa a partir do novo pareamento.
Outros comparativos
Todos: Comparativos →A Evolution API é um servidor open source que você hospeda e opera; a apiwpp é uma API gerenciada cobrada por número. Veja o custo total de cada modelo, o que a apiwpp opera por você e quando hospedar faz sentido.
Os critérios para comparar APIs de WhatsApp gerenciadas, como cobrança, fila anti-bloqueio, webhooks assinados, idempotência, proxy e documentação, com a posição da apiwpp em cada um e um roteiro de migração.
A Cloud API da Meta exige conta comercial e templates aprovados e cobra por mensagem; a apiwpp conecta o número como aparelho conectado, sem aprovação, e cobra por número. Cada uma vence em cenários diferentes.