Evolution API vs WaSphere: uma comparação honesta

A Evolution API é, com folga, o projeto de API de WhatsApp open-source mais usado no Brasil. Se você está lendo isto, provavelmente já a instalou — ou está prestes a instalar — e quer saber se existe algo diferente.

Este texto é escrito por quem mantém a WaSphere, então parta do princípio de que temos um lado. O que podemos fazer é ser precisos: onde a Evolution API é melhor, dizemos que é melhor. Comparações que só elogiam quem as escreveu não ajudam ninguém a decidir.

O que a Evolution API é

A Evolution API é um servidor open-source que expõe o WhatsApp como uma API REST. Ela nasceu no ecossistema brasileiro, cresceu junto com a comunidade de automação (n8n, Typebot, Chatwoot, Dify) e hoje tem uma base instalada que nenhum concorrente direto chega perto.

Os pontos fortes reais:

• Ecossistema de integrações nativas. Typebot, Chatwoot, Dify, n8n e filas (RabbitMQ, SQS) são suportados dentro do próprio produto. Você liga uma chave e funciona.
• Suporte a múltiplos backends. Além da conexão não-oficial baseada em Baileys, há suporte à Cloud API oficial da Meta — o que é raro em projetos open-source.
• Comunidade e material em português. Tutoriais no YouTube, grupos, threads, gente que já resolveu o seu problema às 2 da manhã. Isso tem valor prático enorme e não se compra.
• Maturidade. É um projeto com anos de estrada e milhares de deploys em produção.

Se o seu problema é "preciso disparar e receber mensagens e plugar num Typebot", a Evolution API resolve, e resolve bem. Não vamos fingir o contrário.

Onde a WaSphere é diferente

A WaSphere não tenta ser uma Evolution API com outro nome. A diferença de fundo é esta: a Evolution API é um gateway — um serviço que fala WhatsApp e devolve JSON. A WaSphere é um gateway mais uma aplicação: um dashboard com caixa de entrada em tempo real, usuários humanos, papéis e permissões, e uma camada de segurança pensada para times, não só para scripts.

1. Caixa de entrada real, não um painel de instâncias

A WaSphere inclui um Inbox de duas colunas dentro do dashboard: lista de conversas à esquerda, thread à direita, atualizando ao vivo por Server-Sent Events (sem polling, sem F5). Ele envia e recebe imagem, vídeo, áudio e documento inline, mostra reações, e descriptografa votos individuais de enquete — ou seja, você sabe qual contato escolheu qual opção, não só o total agregado. Há tags por conversa, notas privadas e busca full-text.

Isso importa porque a maioria dos projetos de WhatsApp não morre na API — morre quando alguém do time de atendimento precisa responder um cliente e não existe tela para isso. A resposta usual é "instale um Chatwoot ao lado". É uma resposta válida, e a WaSphere também se integra ao Chatwoot. Mas ter a caixa de entrada dentro do mesmo processo, com o mesmo banco, é um serviço a menos para operar.

2. Papéis e permissões para pessoas

A WaSphere tem workspaces com três níveis de autoridade — OWNER, ADMIN e MEMBER — e, para os membros, papéis nomeados e reutilizáveis que o dono define. Um agente de atendimento vê o Inbox e os contatos; ele não vê as chaves de API nem consegue apagar uma sessão.

Se a sua operação tem uma pessoa só, isso é irrelevante. Se tem oito atendentes, é a diferença entre delegar e não delegar.

3. Webhooks assinados, múltiplos e com retentativa

Cada webhook na WaSphere é um registro próprio com URL, filtro de eventos, segredo de assinatura, e política de retentativa. Toda entrega chega assim:

POST /webhooks/wasphere HTTP/1.1
X-WaSphere-Event: message.received
X-WaSphere-Signature: v1,sha256=<hmac-hex>
X-WaSphere-Timestamp: 1748168400
Content-Type: application/json

A assinatura é HMAC-SHA256 sobre {timestamp}.{rawBody}. Você valida antes de confiar no payload, e rejeita qualquer timestamp fora de uma janela de ±5 minutos para bloquear replay. São 11 tipos de evento — message.sent, message.delivered, message.read, message.failed, message.received, poll.vote, session.connected, session.disconnected, session.qr, session.failed e webhook.test — e você assina só os que quer, por webhook.

Falhas são contadas: o padrão é 3 retentativas, e um webhook que acumula 50 falhas consecutivas é desativado automaticamente em vez de ficar martelando um endpoint morto. Os detalhes estão em Webhooks.

O ponto não é "a Evolution API não tem webhook" — tem. O ponto é que aqui a assinatura HMAC é obrigatória por design e documentada como parte do contrato, e você pode ter vários destinos com escopos diferentes: um para o n8n, outro para o seu ERP, outro para o log.

4. Chaves de API com escopo fino

Chaves têm o prefixo wsk_ e carregam 12 escopos de permissão:

messages:send      messages:send_bulk   messages:read
sessions:read      sessions:write       sessions:delete
webhooks:read      webhooks:write       webhooks:delete
workspace:read     workspace:write      audit:read

Uma chave para o seu bot de disparo pode ter só messages:send. Se ela vazar, o estrago é limitado — quem a tiver não consegue ler o histórico, nem apagar sessões, nem reapontar webhooks. Uma chave também pode ser presa a uma única sessão, retornando 403 para qualquer coisa fora do escopo — útil em cenários multi-cliente onde cada cliente tem o próprio número. Ver Chaves de API.

5. Uma stack, um banco

A WaSphere sobe com um docker compose up -d e são quatro serviços: Postgres, WA Server, Dashboard API, Dashboard UI. Sem Redis, sem MongoDB, sem broker de mensagens, sem Traefik embutido (você põe o seu proxy reverso na frente). Backup é pg_dump mais o volume de sessões.

Isso é uma escolha, não uma superioridade. Menos peças significa menos coisas para operar — e também menos flexibilidade se você precisa de uma fila real entre o gateway e o consumidor. Se o seu volume exige RabbitMQ, a Evolution API já tem isso pronto e a WaSphere não.

6. Licença MIT

A WaSphere é MIT. Você pode ler, forkar, auditar, embutir num produto comercial e não deve nada a ninguém. Antes de assumir a licença de qualquer projeto — inclusive concorrentes — abra o arquivo LICENSE da versão exata que você vai implantar. Licenças mudam entre versões maiores, e essa é uma das poucas coisas que dão trabalho de desfazer depois.

Tabela resumida

	Evolution API	WaSphere
Tipo	Gateway API	Gateway + dashboard
Caixa de entrada para atendentes	Via integração (ex.: Chatwoot)	Nativa, tempo real (SSE)
Usuários e permissões	—	OWNER / ADMIN / MEMBER + papéis nomeados
Escopos de chave de API	—	12 escopos, opcionalmente presa a 1 sessão
Webhooks	Sim	Múltiplos, assinados com HMAC, retentativa + auto-desativação
Backend oficial da Meta	Sim (Cloud API)	Adaptador Cloud API disponível
Filas (RabbitMQ/SQS)	Sim	Não
Integrações nativas	Muitas (Typebot, Chatwoot, Dify, n8n…)	REST + webhooks (n8n, Chatwoot via guia)
Banco	Postgres ou MongoDB	Postgres
Comunidade em português	Muito grande	Pequena
Licença	Verifique no repositório da versão	MIT

Migrar: o que esperar

Não existe importação de sessão entre projetos. A conexão do WhatsApp é um estado criptográfico ligado ao dispositivo; ela não é portátil entre implementações. Migrar significa, na prática:

1. Subir a WaSphere ao lado (Quick Start) — sem desligar nada.
2. Ler um QR code novo e conectar o número na WaSphere. Um número só pode estar ativo em um gateway por vez — no momento em que você conecta aqui, a sessão anterior cai.
3. Reapontar os webhooks. Os nomes de evento e o formato do payload são diferentes; você vai adaptar o consumidor.
4. Trocar as chamadas de envio. O formato da WaSphere é:

curl -X POST \
  "https://api.seudominio.com/workspaces/{workspaceId}/proxy/api/sessions/{sessionId}/messages/text" \
  -H "Authorization: Bearer wsk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5511999999999", "text": "Olá!" }'

O caminho é sempre .../sessions/{sessionId}/messages/{tipo} — troque text por image, document, location, poll, buttons, list e assim por diante. A referência completa está em Enviar mensagens.

Faça isso primeiro com um número de teste. Sempre.

Preço: as duas são gratuitas, e isso não é o custo

Nenhuma das duas cobra por mensagem. O custo real de qualquer gateway self-hosted é o mesmo: um servidor, o tempo de quem mantém, e o risco de operar uma conexão não-oficial do WhatsApp. Isso vale para as duas, e vale para todas as outras. Detalhamos essa conta em preços da API do WhatsApp vs self-hosting.

E o aviso que todo projeto sério deveria dar: conexões não-oficiais podem ter o número bloqueado. Aquecer números novos, respeitar ritmo de envio e só mandar mensagem para quem pediu reduz muito o risco, mas nenhum projeto — este incluído — pode garantir que não acontece.

Qual escolher

Fique na Evolution API se você já está rodando e funciona; se depende das integrações nativas com Typebot, Dify ou filas; ou se o suporte da comunidade em português é parte do seu plano de contingência. São razões boas e suficientes.

Considere a WaSphere se você precisa que pessoas — não só scripts — atendam clientes, com papéis e permissões; se a segurança da integração precisa ser auditável (webhooks assinados, chaves com escopo, log de auditoria); ou se você quer uma stack menor e uma licença MIT sem asteriscos.

E se ainda estiver em dúvida: as duas são gratuitas e sobem em Docker. Rode as duas por uma tarde com um número de teste. Uma tarde de experiência vale mais que qualquer tabela — inclusive esta.

Comece pelo Quick Start, ou veja o código no GitHub. Para o panorama completo da categoria, incluindo WPPConnect, Venom e WAHA, leia o cenário das APIs de WhatsApp open-source em 2026.