Preciso de um proxy por instância?

É a configuração que faz sentido. Concentrar vários números em um único endereço anula o motivo de usar proxy dedicado — se um número gera problema, todos compartilham a mesma origem de rede.

HTTP ou SOCKS5 para Evolution API?

SOCKS5. A Evolution mantém conexões WebSocket longas com o serviço do WhatsApp, e o SOCKS5 lida melhor com esse tipo de conexão persistente que um proxy HTTP.

O proxy resolve problema de número desconectando?

Só se a causa for a origem de rede. Desconexão também acontece por versão desatualizada da biblioteca, sessão corrompida e limite do próprio WhatsApp. O proxy remove uma variável, não todas.

Proxy brasileiro é obrigatório para número brasileiro?

Não é obrigatório, mas é coerente. Um número com DDI brasileiro conectando de um datacenter na Europa é uma combinação incomum, e coerência de origem reduz atrito.

Como configurar proxy na Evolution API

Quem sobe Evolution API em VPS enfrenta um problema que raramente é diagnosticado corretamente: o IP do provedor de nuvem é compartilhado por centenas de projetos e costuma carregar histórico ruim.

Este guia mostra como rotear as instâncias por um IP dedicado brasileiro.

O problema do IP da VPS

Quando você sobe a Evolution API em um provedor de nuvem, o IP público daquela máquina pertence a um bloco de datacenter. Dois fatos decorrem disso:

O bloco é compartilhado. Outros clientes do mesmo provedor usam endereços vizinhos, e o histórico daquela faixa não é construído só pelo seu uso.
A geolocalização aponta o datacenter. Se a VPS está na Europa ou nos Estados Unidos, um número brasileiro está conectando de fora do Brasil.

Rotear por um proxy dedicado brasileiro resolve os dois: a saída passa a ser um endereço exclusivo seu, com geolocalização coerente com o número.

Antes de começar

Do painel, copie host, porta SOCKS5, usuário e senha.

Monte a string de conexão:

socks5://usuario:[email protected]:1080

Se a senha contém @, :, / ou #, codifique o caractere — @ vira %40, por exemplo. Dentro de uma URL, o @ é justamente o separador entre credencial e host, então uma senha com @ quebra a string.

Opção 1 — Proxy por instância (recomendado)

Esta é a configuração correta para operações com mais de um número: cada instância sai por um endereço próprio.

Ao criar a instância, informe os campos de proxy no corpo da requisição:

curl -X POST https://sua-evolution.com/instance/create \
  -H "apikey: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "cliente-a",
    "integration": "WHATSAPP-BAILEYS",
    "proxyHost": "p1.exemplo.com",
    "proxyPort": "1080",
    "proxyProtocol": "socks5",
    "proxyUsername": "seu-usuario",
    "proxyPassword": "sua-senha"
  }'

Para atualizar o proxy de uma instância que já existe:

curl -X POST https://sua-evolution.com/proxy/set/cliente-a \
  -H "apikey: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "host": "p1.exemplo.com",
    "port": "1080",
    "protocol": "socks5",
    "username": "seu-usuario",
    "password": "sua-senha"
  }'

Os nomes exatos dos campos variam entre versões da Evolution. Confirme na documentação da versão que você roda — a estrutura conceitual (host, porta, protocolo, usuário, senha) é sempre a mesma.

Opção 2 — Proxy global por variável de ambiente

Se todas as instâncias devem sair pelo mesmo endereço — cenário de um único cliente, por exemplo — defina no ambiente:

PROXY_HOST=p1.exemplo.com
PROXY_PORT=1080
PROXY_PROTOCOL=socks5
PROXY_USERNAME=seu-usuario
PROXY_PASSWORD=sua-senha

Em Docker Compose:

services:
  evolution-api:
    image: atendai/evolution-api:latest
    environment:
      - PROXY_HOST=p1.exemplo.com
      - PROXY_PORT=1080
      - PROXY_PROTOCOL=socks5
      - PROXY_USERNAME=seu-usuario
      - PROXY_PASSWORD=sua-senha

Cuidado com esta opção quando você atende múltiplos clientes: todos os números passam a compartilhar a mesma origem de rede, o que é exatamente o que você queria evitar.

Verifique antes de conectar o número

Valide o proxy antes de gerar o QR Code. Do próprio servidor onde a Evolution roda:

curl -x socks5h://usuario:[email protected]:1080 https://ipinfo.io/json

O retorno deve mostrar o IP contratado e país BR. Se mostrar o IP da VPS, o proxy não está sendo aplicado e não faz sentido conectar o número ainda.

Dimensionamento: quantos IPs

Cenário	Configuração
1 número	1 IPv4 dedicado
Vários números, mesmo cliente	1 IP por número, ou 1 IP compartilhado se são da mesma operação
Vários clientes	1 IP por cliente, no mínimo
Agência com muitos números	1 IP por número nos casos críticos

A conta é simples: o custo de um IP dedicado é uma fração do custo de perder um número em produção.

Problemas comuns

Instância não conecta depois de configurar o proxy — teste o proxy com curl do próprio servidor. Se o curl falha, é credencial ou porta. Se funciona, é a configuração na Evolution.

QR Code não aparece — a Evolution não conseguiu estabelecer a conexão de saída. Verifique se você usou a porta do SOCKS5 e não a do HTTP.

Número conecta e cai em minutos — pode ser sessão corrompida (apague e recrie a instância), versão desatualizada da biblioteca, ou uso simultâneo do proxy acima do contratado.

Erro de autenticação no proxy — senha com caractere especial não codificado dentro da string de conexão.

O que o proxy resolve aqui

O proxy controla a origem da conexão: endereço exclusivo, geolocalização brasileira e independência entre instâncias.

Ele não controla as políticas do WhatsApp, limites de envio, qualidade do número, conteúdo das mensagens ou reclamações de destinatários. Número bloqueado por padrão de envio não é problema de rede — e nenhum proxy corrige isso.

Se você roda Baileys diretamente, sem a Evolution, veja o guia de Baileys.

Proxy na Evolution API