Pular para o conteúdo
apiwpp

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.

Equipe apiwpp · 14 min de leitura

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.

O que fica com a sua equipe quando a API é hospedada por você: cada camada precisa de alguém para instalar, atualizar e acompanhar.

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 clientRef devolve 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érioBaileys (biblioteca)Evolution API ou WPPConnect Server (self-hosted)apiwpp (gerenciada)
O que você recebeCódigo para falar o protocoloServidor com API RESTAPI pronta, painel e documentação
Quem hospedaVocêVocêapiwpp
Custo do softwareGrátis (open source)Grátis (open source)Por número conectado, por mês
Custo de infraestruturaServidor, banco, proxiesServidor, banco, cache, proxiesIncluído; IP dedicado é adicional no PRO
Sessão salvaVocê implementaConfigurável, você cuida do armazenamentoSalva e criptografada
Ritmo de envio e aquecimentoVocê implementaVocê implementa ou configuraFila por número e 14 dias de aquecimento
Webhooks com novas tentativasVocê implementaConforme o projeto e a versãoAssinados, 6 tentativas, registro e reenvio
Atualizações do protocoloVocê acompanha e aplicaVocê acompanha e aplicaAplicadas pela apiwpp
MonitoramentoVocê montaVocê montaStatus por conexão e página de status pública
Controle sobre o códigoTotalTotalPela 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:

  1. Infraestrutura: servidor, banco de dados, cache, backups e, se for o caso, proxies brasileiros.
  2. Tempo de engenharia para construir o que o projeto não traz: fila com ritmo, aquecimento, webhooks com novas tentativas, painel para a equipe.
  3. Tempo de engenharia para manter: atualizações do protocolo, dependências, incidentes, pareamentos refeitos.
  4. 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:

  1. 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.
  2. Troque o envio. Aponte o seu código para POST /connections/{id}/send, com o destinatário em to (só dígitos, com país e DDD) e um clientRef estável para cada mensagem.
  3. Troque o webhook. Os eventos chegam num envelope com type, connectionId, tenantId, externalId, timestamp e data. Valide a assinatura HMAC e processe cada tipo que você usa, como message.incoming e message.delivery. O tutorial de webhooks do WhatsApp mostra a verificação em Node.js e PHP.
  4. 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 429 e o evento message.send_failed.

Como começar hoje

  1. Liste o que a sua integração faz hoje: envio de texto, mídia, templates, recebimento de mensagens, eventos de entrega.
  2. Anote quanto tempo a equipe gastou no último mês com a operação: pareamentos refeitos, atualizações, incidentes.
  3. Estime o custo total do self-hosted com os quatro itens da seção de custos e compare com a calculadora em preços.
  4. Leia a integração com Node.js ou a documentação em docs.apiwpp.com para ver quanto do seu código muda.
  5. 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:

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.