Evolution API, Baileys e WPPConnect: hospedar a própria API ou usar uma gerenciada
Evolution API, Baileys e WPPConnect são grátis, mas a operação não é. Veja o que hospedar a própria API do WhatsApp exige e quando uma gerenciada compensa.
Quem pesquisa como integrar o WhatsApp a um sistema sem passar pela API oficial da Meta logo encontra três nomes: Evolution API, Baileys e WPPConnect. São projetos open source, gratuitos, com comunidades ativas e tutoriais que prometem um servidor funcionando em uma tarde. A pergunta que vem em seguida é justa: se o software é grátis, por que pagar por uma API gerenciada?
A resposta curta é que o código é a parte barata. O que custa é manter um número conectado, enviando no ritmo certo e entregando eventos ao seu sistema todos os dias, inclusive no domingo em que o WhatsApp muda alguma coisa no protocolo. Esse trabalho existe nos dois caminhos; a diferença é quem faz.
Este guia explica o que é cada projeto, o que eles têm em comum com uma API gerenciada como a apiwpp, o que hospedar a própria API exige na prática e como decidir com base na sua equipe, no número de números e no tempo que você pode dedicar à operação. Sem apontar defeitos de projeto nenhum: todos resolvem bem o problema a que se propõem.
O que são Baileys, Evolution API e WPPConnect
Os três trabalham sobre o mesmo mecanismo: o protocolo do WhatsApp Web. O número é conectado como um aparelho conectado, da mesma forma que você conecta o WhatsApp no navegador do computador, lendo um QR code no celular. O que muda entre eles é a camada em que cada um se encaixa.
Baileys: a biblioteca
O Baileys é uma biblioteca open source em TypeScript que fala o protocolo do WhatsApp Web diretamente, por WebSocket, sem abrir um navegador. Ela entrega os blocos básicos: gerar o QR code, manter a sessão, enviar e receber mensagens e reagir a eventos da conexão.
Por ser uma biblioteca, e não um servidor, o Baileys não traz API HTTP, fila, painel nem webhooks. Você escreve o serviço em volta dele. É a escolha de quem quer controle total e tem equipe para construir o resto. O glossário sobre Baileys resume o termo.
Evolution API: um servidor pronto
A Evolution API é um servidor open source que expõe uma API REST para criar e controlar várias instâncias de WhatsApp. Ela usa o Baileys como motor do protocolo e acrescenta o que falta para um sistema externo conversar com ele: rotas HTTP, gerenciamento de instâncias, eventos enviados para uma URL e integrações com outras ferramentas.
Na prática, é o caminho mais comum de quem quer uma API própria sem escrever o servidor do zero. Você sobe o serviço, normalmente com Docker, configura o armazenamento e passa a chamar as rotas.
WPPConnect: biblioteca e servidor
O projeto WPPConnect mantém duas peças: a biblioteca wppconnect, que controla uma instância do WhatsApp Web dentro de um navegador automatizado, e o WPPConnect Server, uma API REST construída sobre ela. A abordagem com navegador é diferente da do Baileys, mas o resultado para quem integra é parecido: rotas HTTP para enviar e eventos para receber.
E onde a apiwpp entra
A apiwpp usa o mesmo protocolo do WhatsApp Web. A diferença não está na tecnologia de conexão, e sim no modelo: em vez de você hospedar e operar o servidor, a apiwpp opera tudo e entrega uma API pronta, cobrada por número conectado. Por isso a comparação honesta não é "qual é melhor", e sim "quem opera".
O que os três têm em comum com uma API gerenciada
Antes das diferenças, vale deixar claro o que não muda quando você troca de ferramenta.
- O protocolo é o mesmo. Nenhum desses projetos, nem a apiwpp, é a API oficial. Não há selo de conta verificada, aprovação da Meta nem templates oficiais. Se você precisa disso, o guia sobre API oficial ou não oficial explica quando a Cloud API é a escolha certa.
- O risco de restrição é o mesmo. O WhatsApp julga o comportamento do número: ritmo de envio, conversas com desconhecidos, denúncias. Trocar a biblioteca não muda isso. O que muda é se existe, entre o seu código e o WhatsApp, uma camada que controla o ritmo por você.
- O número continua sendo seu. Em qualquer um dos caminhos, o número é um WhatsApp comum conectado como aparelho. Sair de um e ir para outro exige desconectar e parear de novo.
Com isso em mente, a decisão deixa de ser técnica e vira operacional.
O que hospedar a própria API exige
Subir um servidor de teste leva pouco tempo. Manter números em produção é outra conta. Esta é a lista do que alguém da sua equipe passa a ser responsável por fazer.
Servidor, banco e armazenamento de sessão
Servidores como a Evolution API e o WPPConnect Server costumam rodar em contêineres, com um banco de dados para as instâncias e, conforme a configuração, Redis ou arquivos em disco para cache e sessões. Os requisitos mudam de versão para versão, então siga a documentação oficial de cada projeto.
O ponto crítico é a sessão. Ela é o que mantém o número conectado sem um novo QR code. Se o disco se perde, se o contêiner é recriado sem volume persistente ou se o banco é restaurado de um backup antigo, o número precisa ser pareado de novo. Guardar a sessão com segurança também é responsabilidade sua: ela dá acesso às conversas do número.
Atualizações do protocolo
O WhatsApp Web muda sem aviso público. Quando muda, as bibliotecas publicam correções e os servidores atualizam as dependências. Quem hospeda precisa acompanhar essas versões, testar e aplicar, às vezes com urgência, porque uma conexão que para de funcionar para o envio de todos os números ao mesmo tempo.
Proxies e endereços de IP
Um servidor em nuvem sai para a internet por um IP de data center, muitas vezes fora do Brasil, e vários números no mesmo IP compartilham a mesma reputação. Quem opera em escala costuma contratar proxies, distribuir os números entre eles, verificar se cada proxy está saudável e mover o número quando um deles cai.
Fila e ritmo de envio
Bibliotecas e servidores de protocolo enviam o que o seu sistema pede. Se o seu código dispara centenas de mensagens num laço, cabe a ele, e não ao WhatsApp, segurar o ritmo. Controlar o ritmo, limitar conversas com contatos novos e respeitar um período de aquecimento depois de conectar um número é código que você escreve e mantém. O guia como evitar o bloqueio do número mostra por que isso importa.
Webhooks confiáveis
Receber eventos em tempo real é simples; recebê-los sem perder nenhum é trabalho. Se o seu endpoint ficar fora do ar por alguns minutos, o que acontece com as mensagens recebidas nesse intervalo? Novas tentativas, registro de entregas, reenvio manual e assinatura para provar que o evento veio mesmo do seu servidor são peças que você pode precisar construir.
Monitoramento e plantão
Por fim, alguém precisa saber quando um número caiu, quando a sessão expirou ou quando o WhatsApp bloqueou temporariamente novas conversas, e agir. Isso significa alertas, painéis e uma pessoa de plantão para quando o alerta tocar.
O que uma API gerenciada entrega
Na apiwpp, cada item da lista acima já vem resolvido e incluído no preço por número. Estes são os pontos, todos em produção hoje:
- Sessão persistente e criptografada. A sessão fica salva no banco de dados, criptografada. Reinícios, atualizações e reconexões não pedem novo QR code, e o celular pode ficar desligado. A conexão é feita por QR code ou por um código de pareamento de 8 caracteres.
- Fila com ritmo anti-bloqueio. Cada número tem a própria fila: por padrão, 3 mensagens por minuto, 60 por hora e 200 por dia, com intervalo aleatório de 3 a 8 segundos e pelo menos 30 segundos entre duas mensagens para a mesma pessoa. Destinatários novos têm teto de 100 a cada 24 horas.
- Aquecimento de 14 dias. Um número recém-pareado começa com limites menores, que sobem por etapas. O aquecimento é aplicado sozinho.
- Webhooks assinados com novas tentativas. Os webhooks são assinados com HMAC-SHA256, entregues pelo menos uma vez, com até 6 tentativas, registro de cada entrega e reenvio das que falharam.
- Proxy brasileiro por número. Cada número sai por um IP brasileiro. Você também pode usar o próprio proxy, e o plano PRO permite um IP dedicado como adicional.
- Idempotência. Repetir um envio com o mesmo
clientRefdevolve o job original, sem enfileirar outra mensagem. Veja idempotência com clientRef. - Página de status pública. A status.apiwpp.com mostra a saúde dos componentes e um teste que envia mensagens reais entre dois números a cada 10 minutos.
Do lado do seu código, o envio vira uma chamada HTTP. O exemplo em Node.js trata os três desfechos que importam: enfileirado, repetido e barrado pelo teto de destinatários novos.
const API = 'https://api.apiwpp.com'
export async function enviar(connectionId: string, to: string, message: string, clientRef: string) {
const res = await fetch(`${API}/connections/${connectionId}/send`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.APIWPP_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to, message, clientRef }),
})
if (res.status === 429) {
// new_recipient_cap_reached: nada entrou na fila; reagende depois de Retry-After segundos
const { error } = await res.json()
return { status: 'reagendar' as const, error, esperarSegundos: Number(res.headers.get('Retry-After') ?? '60') }
}
if (!res.ok) throw new Error(`Envio recusado: ${res.status}`)
// 202: novo job na fila. 200 com duplicate: true: o mesmo clientRef já tinha sido aceito.
const job = await res.json() // { jobId, scheduledAt, position }
return { status: 'na-fila' as const, job }
}
A resposta 202 chega na hora, com o horário previsto e a posição na fila:
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }
A integração completa, com o webhook ao lado, está em API de WhatsApp para Node.js.
Self-hosted ou gerenciada: a tabela
A tabela compara modelos, não projetos. Os três projetos open source aparecem juntos porque, do ponto de vista da operação, quem hospeda assume as mesmas tarefas.
| Critério | Baileys (biblioteca) | Evolution API ou WPPConnect Server (self-hosted) | apiwpp (gerenciada) |
|---|---|---|---|
| O que você recebe | Código para falar o protocolo | Servidor com API REST | API pronta, painel e documentação |
| Quem hospeda | Você | Você | apiwpp |
| Custo do software | Grátis (open source) | Grátis (open source) | Por número conectado, por mês |
| Custo de infraestrutura | Servidor, banco, proxies | Servidor, banco, cache, proxies | Incluído; IP dedicado é adicional no PRO |
| Sessão salva | Você implementa | Configurável, você cuida do armazenamento | Salva e criptografada |
| Ritmo de envio e aquecimento | Você implementa | Você implementa ou configura | Fila por número e 14 dias de aquecimento |
| Webhooks com novas tentativas | Você implementa | Conforme o projeto e a versão | Assinados, 6 tentativas, registro e reenvio |
| Atualizações do protocolo | Você acompanha e aplica | Você acompanha e aplica | Aplicadas pela apiwpp |
| Monitoramento | Você monta | Você monta | Status por conexão e página de status pública |
| Controle sobre o código | Total | Total | Pela API e pela especificação OpenAPI 3.1 |
Nenhuma coluna ganha em tudo. O self-hosted dá controle total e custo de software zero; a gerenciada troca esse controle por operação resolvida e um preço previsível.
O custo total vai além do software grátis
Comparar "grátis" com "R$ por número" engana, porque o software é só uma linha da conta. Para estimar o custo real de hospedar, some:
- Infraestrutura: servidor, banco de dados, cache, backups e, se for o caso, proxies brasileiros.
- Tempo de engenharia para construir o que o projeto não traz: fila com ritmo, aquecimento, webhooks com novas tentativas, painel para a equipe.
- Tempo de engenharia para manter: atualizações do protocolo, dependências, incidentes, pareamentos refeitos.
- Plantão: quem responde quando um número cai fora do horário comercial.
Do outro lado, a apiwpp cobra por número conectado por mês, com mensagens ilimitadas dentro dos limites da fila e sem cobrança por mensagem. Os valores do LITE, do PRO e do IP dedicado estão na página de preços, com uma calculadora por quantidade de números. O guia sobre quanto custa uma API de WhatsApp compara os modelos de cobrança lado a lado.
Como decidir
Três perguntas resolvem a maior parte dos casos.
Quem vai operar?
Se existe uma equipe de infraestrutura com tempo para acompanhar mais um serviço crítico, hospedar é viável. Se o sistema é mantido por uma ou duas pessoas que já têm o produto principal para cuidar, cada hora gasta com sessão caída é uma hora a menos no que o cliente vê.
Quantos números?
Com um número de teste, qualquer caminho funciona. Com dezenas de números de clientes diferentes, entram na conta a separação por cliente, proxies distintos, chaves de acesso com escopo e cobrança organizada. Na apiwpp, cada cliente pode ser um projeto com as próprias chaves e o próprio webhook, e tudo sai numa fatura só por organização.
Quanto tempo até produção?
Se a integração precisa estar no ar nesta semana, uma API pronta elimina a etapa de construir fila, webhooks confiáveis e monitoramento. Se o WhatsApp é o núcleo do seu produto e você quer controlar cada detalhe do protocolo, construir sobre uma biblioteca pode fazer sentido a longo prazo.
Em resumo: hospedar faz sentido quando você precisa de controle total sobre o código, tem equipe para operar e aceita construir as camadas de proteção. A gerenciada faz sentido quando o objetivo é integrar o WhatsApp ao seu sistema e seguir para o próximo problema. Os comparativos Evolution API self-hosted ou gerenciada e WPPConnect e Baileys trazem os critérios em formato de consulta rápida.
Migrar de uma API self-hosted para a apiwpp
Se você já roda a Evolution API, o WPPConnect Server ou um serviço próprio sobre o Baileys, a troca é uma migração de integração, não de número:
- Conecte o número de novo. Desconecte a instância antiga no celular, em Aparelhos conectados, e pareie o número na apiwpp por QR code ou código de pareamento. O aquecimento de 14 dias começa a contar a partir desse pareamento.
- Troque o envio. Aponte o seu código para
POST /connections/{id}/send, com o destinatário emto(só dígitos, com país e DDD) e umclientRefestável para cada mensagem. - Troque o webhook. Os eventos chegam num envelope com
type,connectionId,tenantId,externalId,timestampedata. Valide a assinatura HMAC e processe cada tipo que você usa, comomessage.incomingemessage.delivery. O tutorial de webhooks do WhatsApp mostra a verificação em Node.js e PHP. - Remova o controle de ritmo que você mantinha. A fila da apiwpp já aplica os limites; o seu código passa a tratar a resposta
429e o eventomessage.send_failed.
Como começar hoje
- Liste o que a sua integração faz hoje: envio de texto, mídia, templates, recebimento de mensagens, eventos de entrega.
- Anote quanto tempo a equipe gastou no último mês com a operação: pareamentos refeitos, atualizações, incidentes.
- Estime o custo total do self-hosted com os quatro itens da seção de custos e compare com a calculadora em preços.
- Leia a integração com Node.js ou a documentação em docs.apiwpp.com para ver quanto do seu código muda.
- Crie sua conta na apiwpp e conecte um número de teste: são 7 dias com os recursos do PRO (exceto IP dedicado), sem cartão.
Perguntas frequentes
A Evolution API é gratuita?
O software é open source e pode ser usado sem pagar licença. O custo aparece na infraestrutura, como servidor, banco de dados e proxies, e no tempo da equipe para instalar, atualizar e monitorar. Para comparar com uma API gerenciada, some esses custos mensais em vez de olhar só o preço do software.
Qual a diferença entre Baileys e Evolution API?
O Baileys é uma biblioteca em TypeScript que fala o protocolo do WhatsApp Web; você escreve o serviço em volta dela. A Evolution API é um servidor que usa o Baileys e já entrega rotas HTTP e gerenciamento de instâncias. Em outras palavras, a Evolution API é uma aplicação construída sobre a biblioteca.
Hospedar a própria API reduz o risco de bloqueio?
Não por si só. O WhatsApp avalia o comportamento do número, como ritmo de envio, conversas com desconhecidos e denúncias, e não o servidor que você usa. O que reduz o risco é controlar o ritmo, aquecer números novos e falar com quem quer receber, algo que a apiwpp aplica por padrão e que, no self-hosted, fica com o seu código. Nenhuma ferramenta garante que um número nunca será restringido.
A apiwpp é a API oficial do WhatsApp?
Não. A apiwpp usa o protocolo do WhatsApp Web, como a Evolution API, o Baileys e o WPPConnect, e não tem vínculo com o WhatsApp nem com a Meta. A diferença está em quem opera: a apiwpp hospeda, atualiza e monitora a infraestrutura, e você usa a API.
Consigo migrar sem trocar de número?
Sim. O número continua o mesmo: você desconecta a instância antiga no celular e pareia o número na apiwpp por QR code ou código de pareamento. Depois disso, o aquecimento de 14 dias recomeça e o seu código passa a chamar as rotas e receber os webhooks da apiwpp.
Quando vale mais a pena hospedar a própria API?
Quando o WhatsApp é o núcleo do produto, você precisa de controle total sobre o código e tem uma equipe com tempo para operar o serviço, inclusive fora do horário comercial. Nesses casos, construir sobre uma biblioteca open source pode compensar. Se o objetivo é integrar o WhatsApp a um sistema que já existe, uma API gerenciada costuma levar menos tempo até produção.
Leia também: