Evolution API: o que é e como funciona

Se você pesquisou sobre API de WhatsApp não oficial nos últimos anos, provavelmente encontrou menções à Evolution API. Ela se tornou referência entre desenvolvedores brasileiros e internacionais por ser open source, extensível e compatível com o protocolo Baileys — a biblioteca que emula o WhatsApp Web.

Mas o que exatamente a Evolution API faz? Como ela se encaixa na stack de produtos como a Zapixo? E quais cuidados você precisa ter ao operá-la em produção? Este artigo responde tudo isso de forma técnica e prática.

O que é a Evolution API?

A Evolution API é um servidor HTTP escrito em Node.js/TypeScript que expõe endpoints REST para:

• Criar e gerenciar instâncias (sessões de WhatsApp)
• Conectar números via QR Code ou código de pareamento
• Enviar e receber texto, mídia, áudio, documentos e localização
• Configurar webhooks para eventos em tempo real
• Integrar com Chatwoot, Typebot, RabbitMQ, S3 e outros conectores

Por baixo dos panos, ela usa a biblioteca Baileys para manter uma sessão WebSocket com os servidores do WhatsApp, da mesma forma que o WhatsApp Web faz no navegador. Isso significa que não há parceria oficial com a Meta — é uma integração baseada no protocolo do cliente web.

Arquitetura em camadas

Para entender o funcionamento, visualize três camadas:

┌─────────────────────────────────────┐
│  Sua aplicação (CRM, bot, n8n...)   │
└──────────────┬──────────────────────┘
               │ REST / Webhooks
┌──────────────▼──────────────────────┐
│  Evolution API (ou SaaS como Zapixo)│
│  - Autenticação                     │
│  - Multi-instância                  │
│  - Fila de mensagens                │
└──────────────┬──────────────────────┘
               │ Baileys (WebSocket)
┌──────────────▼──────────────────────┐
│  Servidores WhatsApp (não oficial)  │
└─────────────────────────────────────┘

Quando você envia um POST para /message/sendText, a Evolution API enfileira a operação, o Baileys serializa no formato protobuf do WhatsApp e transmite via WebSocket. Quando uma mensagem chega, o fluxo inverte: Baileys dispara um evento interno, a Evolution API normaliza o payload e, se configurado, faz POST no seu webhook.

Conceito central: a instância

Na Evolution API, cada número conectado é uma instance. Ao criar uma instância, você define:

• instanceName — identificador único (ex.: loja-sp)
• Token de API — credencial para autenticar requests
• Webhook URL — destino dos eventos

O ciclo de vida típico:

1. POST /instance/create — cria registro da instância
2. GET /instance/connect/{instanceName} — retorna QR Code base64
3. Usuário escaneia com o WhatsApp do celular
4. Status muda para open (conectado)
5. Mensagens fluem bidirecionalmente até desconexão ou logout

Instâncias desconectadas não enviam mensagens. Reconexão automática depende de sessão persistida (arquivos de auth ou banco de dados, conforme configuração).

Principais endpoints e eventos

Envio de mensagens

curl -X POST "https://sua-api.exemplo.com/message/sendText/minha-loja" \
  -H "apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511987654321",
    "text": "Pedido #1234 confirmado!"
  }'

Endpoints comuns:

| Endpoint | Função | |----------|--------| | /message/sendText | Texto simples | | /message/sendMedia | Imagem, vídeo, documento | | /message/sendWhatsAppAudio | Áudio PTT | | /message/sendList | Lista interativa | | /message/sendButtons | Botões de resposta rápida |

Webhooks

Configure na instância quais eventos deseja receber:

• MESSAGES_UPSERT — mensagem nova (entrada ou saída)
• MESSAGES_UPDATE — ack, leitura, edição
• CONNECTION_UPDATE — conectado, desconectado, QR expirado
• PRESENCE_UPDATE — digitando, online (quando disponível)

Exemplo de payload recebido:

{
  "event": "messages.upsert",
  "instance": "minha-loja",
  "data": {
    "key": {
      "remoteJid": "5511987654321@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB0XXXX"
    },
    "message": {
      "conversation": "Quero rastrear meu pedido"
    },
    "messageTimestamp": 1740000000
  }
}

Sua aplicação deve responder com HTTP 200 rapidamente e processar de forma assíncrona se a lógica for pesada.

Evolution API self-hosted vs SaaS gerenciado

Rodar a Evolution API no seu VPS é possível e gratuito em termos de licença (open source). Porém, produção exige:

• Infraestrutura — Docker, Redis, Postgres ou MongoDB, dependendo da versão
• Atualizações — WhatsApp muda protocolo com frequência; Baileys e Evolution precisam de patches
• Monitoramento — instâncias caem, QR expira, memória vaza em sessões longas
• Segurança — API exposta na internet precisa de firewall, rate limit e tokens rotacionados
• Backup de sessão — perder auth state = reconectar manualmente

É aqui que entram plataformas como a Zapixo. Ela opera a stack Evolution/Baileys em infraestrutura otimizada, oferecendo:

• Dashboard em português para criar instâncias e ver QR Code
• Webhooks configuráveis sem editar .env
• Suporte técnico quando WhatsApp quebra compatibilidade
• Planos previsíveis sem você gerenciar VPS

Para MVPs e PMEs, o SaaS costuma ser mais barato que o custo oculto de manter servidores. Para equipes com DevOps maduro e requisitos de compliance extremos, self-hosted ainda faz sentido.

Integrações nativas da Evolution

Versões recentes da Evolution API incluem conectores que reduzem código customizado:

• Chatwoot — sync bidirecional de conversas para atendimento humano
• Typebot — fluxos conversacionais visuais
• RabbitMQ / SQS — filas para alto volume
• S3 / MinIO — armazenamento de mídia recebida
• OpenAI / Dify — bots com IA (use com moderação e políticas claras)

Na Zapixo, muitas dessas capacidades estão disponíveis via API REST padronizada, permitindo que você plugue n8n, Make, seu backend Node.js ou qualquer cliente HTTP.

Limitações e riscos que você precisa conhecer

A Evolution API não é a API oficial da Meta (Cloud API / Business Platform). Implicações:

1. Termos de uso — automação via WhatsApp Web pode violar os ToS da Meta; existe risco de banimento do número.
2. Sem selo verde — você não obtém conta Business verificada por este caminho.
3. Instabilidade pontual — atualizações do app WhatsApp podem derrubar sessões até patch da comunidade.
4. Sem templates HSM pagos — mensagens proativas seguem regras diferentes da Cloud API oficial.

Mitigue riscos com: número dedicado, opt-in, volume gradual, conteúdo relevante e monitoramento de métricas de entrega.

Comparativo rápido: Evolution vs Cloud API oficial

| Aspecto | Evolution API | Cloud API (Meta) | |---------|---------------|------------------| | Custo por conversa | Fixo (infra/SaaS) | Cobrança por janela 24h | | Setup | QR Code, minutos | Verificação business, semanas | | Flexibilidade | Alta (qualquer número) | Restrições de template | | Estabilidade legal | Não oficial | Contrato com Meta | | Ideal para | PMEs, bots, MVPs | Enterprise, escala global |

Muitas empresas brasileiras começam com Evolution via Zapixo e migram números críticos para Cloud API quando o volume e compliance exigem.

Como começar na prática

Se você quer experimentar sem montar servidor:

1. Acesse zapixo.com.br e crie uma conta
2. Crie uma instância e escaneie o QR Code
3. Configure webhook apontando para seu backend ou n8n
4. Teste envio com curl ou Postman
5. Implemente lógica de negócio na sua camada de aplicação

A Zapixo abstrai a complexidade operacional da Evolution, mas os conceitos — instância, webhook, sendText — permanecem os mesmos. Documentação compatível facilita migrar de self-hosted para managed quando fizer sentido.

Conclusão

A Evolution API democratizou o acesso programático ao WhatsApp ao empaquetar o Baileys em endpoints REST bem definidos. Entender instâncias, webhooks e o modelo de sessão WebSocket é fundamental para qualquer integração séria.

Seja rodando no seu Docker ou via Zapixo, trate a camada de mensageria como infraestrutura crítica: monitore conexões, versione integrações e projete fallbacks para desconexões. Com essa base, você constrói automações robustas sobre uma das stacks mais usadas do ecossistema WhatsApp no Brasil.