Evolution API v2 vs v3 no WhatsApp: o que mudou e como migrar sua instância

A Evolution API v3 introduziu breaking changes significativos na estrutura de endpoints, autenticação e gerenciamento de sessões do WhatsApp. Instâncias que rodam a v2 em VPS precisam revisar variáveis de ambiente, atualizar chamadas de API e, em alguns casos, recriar sessões para manter a compatibilidade.

TL;DR: A v3 mudou a estrutura de rotas (de /instance/create para /v3/instance), removeu suporte a alguns headers legados e exige token JWT no formato Bearer. Instâncias antigas continuam funcionando até você atualizar o container — mas integrações novas já exigem os novos endpoints.

O que mudou da v2 para a v3?

A Evolution API v3 reestruturou a arquitetura de rotas e a forma como sessões do WhatsApp são autenticadas e gerenciadas no servidor.

Estrutura de endpoints

Na v2, todos os endpoints ficavam sob /instance/, /message/ e /webhook/. A v3 consolidou tudo sob o prefixo /v3/, com nomenclatura mais consistente:

• Criar instância: de POST /instance/create para POST /v3/instance
• Listar instâncias: de GET /instance/fetchInstances para GET /v3/instance/list
• Enviar mensagem de texto: de POST /message/sendText/:instance para POST /v3/message/:instance/text
• Status da conexão: de GET /instance/connectionState/:instance para GET /v3/instance/:instance/state

Essa mudança força revisão de todas as chamadas em integrações existentes — especialmente em fluxos no n8n, Typebot ou scripts que consumam a API diretamente.

Autenticação e tokens

A v2 aceitava o apikey tanto no header apikey quanto em query string. A v3 exige autenticação Bearer no header Authorization:

Authorization: Bearer SEU_API_KEY_AQUI

Tokens legados no formato de header customizado (apikey: xyz) deixam de funcionar após a migração. Se você usa n8n para automações com Evolution API, é necessário atualizar todos os nós HTTP Request que chamam a Evolution.

Gerenciamento de sessões e reconexão

A v3 introduziu controle explícito de sessões persistentes. Na v2, se o container reiniciasse, a sessão do WhatsApp se perdia — era necessário escanear o QR Code novamente.

A v3 permite configurar armazenamento de sessão em Redis ou banco PostgreSQL, eliminando a necessidade de reconexão manual após restart do container. A configuração exige novas variáveis de ambiente:

SESSION_STORE=redis
REDIS_URI=redis://usuario:senha@host:6379

Sem essa configuração, o comportamento padrão continua sendo in-memory — ou seja, igual à v2.

Webhooks e eventos

A v3 renomeou eventos de webhook e adicionou novos. Eventos como qrcode.updated, connection.update e messages.upsert permaneceram, mas agora retornam payloads com estrutura JSON diferente.

Se você envia eventos para Chatwoot ou outro CRM, é preciso revisar o parser de webhook.

Por que migrar da v2 para a v3?

A v2 ainda recebe correções de segurança até meados de 2026, mas não terá novos recursos. A v3 traz:

• Melhor performance em instâncias com múltiplas sessões simultâneas (redução de ~30% no uso de memória por sessão, segundo testes internos da comunidade)
• Suporte nativo a filas de mensagens via RabbitMQ ou BullMQ, evitando rate limit do WhatsApp
• API REST mais consistente e auto-documentada (Swagger integrado por padrão em /v3/docs)
• Preparação para integrações oficiais futuras (Meta anunciou suporte a provedores de solução em 2026, e a v3 já implementa parte dos requisitos de compliance)

Instâncias que atendem alto volume (acima de 10 mil mensagens/dia) se beneficiam diretamente da gestão de fila e da persistência de sessão.

Como migrar sua instância Evolution API de v2 para v3

A migração pode ser feita sem downtime se você rodar as duas versões em paralelo durante a transição. O processo depende de como a instância está hospedada.

Pré-requisitos

Antes de iniciar, garanta que você tem:

• Acesso SSH ao VPS onde a Evolution API roda
• Backup das variáveis de ambiente (arquivo .env ou configuração do docker-compose.yml)
• Lista de todas as integrações ativas (n8n, Typebot, Chatwoot, scripts custom)
• Pelo menos 2 GB de RAM livre no servidor (a v3 + v2 rodarão lado a lado temporariamente)

Se você usa VPS para n8n com Evolution pré-instalada, o ambiente já vem configurado com Docker Compose — basta seguir os passos abaixo.

Passo 1: Subir a v3 em paralelo

Clone o repositório atualizado e crie um novo container para a v3, sem parar a v2:

cd /opt
git clone https://github.com/EvolutionAPI/evolution-api.git evolution-v3
cd evolution-v3
git checkout v3.0.0  # use a tag da versão estável mais recente

Copie o .env da v2 e ajuste as portas e o prefixo de instância:

cp /opt/evolution-api/.env /opt/evolution-v3/.env
nano /opt/evolution-v3/.env

Altere as variáveis:

PORT=8081  # v2 roda na 8080, deixe a v3 em outra porta
INSTANCE_PREFIX=v3_  # diferencia as instâncias novas
SESSION_STORE=redis  # se quiser persistência
REDIS_URI=redis://localhost:6379

Inicie o container:

docker compose up -d

Valide que a v3 subiu corretamente:

curl http://localhost:8081/v3/health

Resposta esperada: {"status":"ok","version":"3.x.x"}.

Passo 2: Atualizar integrações para os novos endpoints

Mapeie todas as chamadas de API ativas e atualize os endpoints. Se você usa n8n:

1. Abra cada workflow que chama a Evolution API
2. Localize os nós HTTP Request
3. Atualize a URL base de http://seu-vps:8080/instance/ para http://seu-vps:8081/v3/instance/
4. Adicione o header Authorization: Bearer {{$env.EVOLUTION_APIKEY}}
5. Remova o header legado apikey

Teste o workflow em modo de execução manual antes de ativar.

Para scripts Python, Node ou PHP, atualize as chamadas HTTP de forma equivalente. Exemplo em Python:

import requests

headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.post(
    "http://seu-vps:8081/v3/instance",
    json={"instanceName": "teste_v3"},
    headers=headers
)
print(response.json())

Passo 3: Recriar instâncias do WhatsApp na v3

As sessões ativas na v2 não migram automaticamente. Você precisa:

1. Criar a instância na v3 (endpoint POST /v3/instance)
2. Escanear o QR Code novamente no WhatsApp
3. Configurar o webhook (endpoint POST /v3/webhook/:instance)
4. Validar envio e recebimento de mensagens

Apenas depois de confirmar que a nova instância está estável, desligue a v2:

cd /opt/evolution-api
docker compose down

Se você configurou Redis ou PostgreSQL para persistência de sessão, a instância v3 sobrevive a restarts sem precisar reescanear o QR Code.

Passo 4: Redirecionar tráfego e remover a v2

Com todas as integrações funcionando na v3, atualize o proxy reverso (Nginx, Traefik ou Caddy) para apontar o domínio principal para a porta 8081:

location / {
    proxy_pass http://localhost:8081;
}

Recarregue o Nginx:

sudo systemctl reload nginx

Remova o container da v2:

cd /opt/evolution-api
docker compose down
rm -rf /opt/evolution-api  # opcional, após backup completo

Tabela comparativa: v2 vs v3

Principais aprendizados

• A Evolution API v3 não é retrocompatível — endpoints, autenticação e estrutura de eventos mudaram completamente
• Rodar v2 e v3 em paralelo elimina downtime durante a migração
• Persistência de sessão via Redis ou PostgreSQL é o maior ganho operacional da v3 — QR Code só uma vez
• Integrações com n8n, Typebot ou Chatwoot exigem revisão manual de todos os nós que chamam a API
• A v3 consome cerca de 30% menos memória por sessão ativa — relevante em VPS com múltiplas instâncias

Perguntas frequentes

Evolution API v2 vai parar de funcionar?

Não imediatamente. A v2 recebe correções de segurança até meados de 2026, mas novos recursos só chegam na v3. Instâncias antigas continuam operando, mas sem atualizações de funcionalidade.

Posso migrar sem reescanear o QR Code do WhatsApp?

Não diretamente. As sessões da v2 ficam em memória e não são compatíveis com a estrutura de persistência da v3. É necessário criar a instância do zero e escanear o QR novamente — mas, uma vez configurada com Redis ou PostgreSQL, a sessão persiste entre restarts.

A v3 exige mais recursos de servidor?

Não — consome menos. Testes mostram redução de ~30% no uso de RAM por sessão ativa. O ganho vem da otimização do gerenciamento de conexões WebSocket e do uso de filas para envio de mensagens.

Preciso atualizar o n8n ou Typebot junto com a Evolution?

Não necessariamente, mas você precisa revisar os workflows. As ferramentas continuam funcionando, mas os nós HTTP Request que chamam a Evolution API precisam apontar para os novos endpoints e usar autenticação Bearer.

Quanto tempo leva a migração completa?

Para uma instância com 1-3 sessões e poucas integrações, entre 30 e 60 minutos. Ambientes com múltiplas sessões, webhooks complexos e integrações em produção podem levar meio dia, especialmente se você optar por rodar v2 e v3 em paralelo para validar tudo antes de desligar a versão antiga.

Precisa de ajuda para migrar sua Evolution API ou quer uma instância gerenciada com n8n, Chatwoot e Evolution v3 pré-configurada? Fale com a equipe técnica da Rollin Host — migramos a infra, você foca na automação.