Pular para o conteúdo

Proxy e IP dedicado

Por onde cada número sai para o WhatsApp: o IP brasileiro compartilhado, um proxy seu por conexão ou um IP dedicado (PRO), e como verificar cada um.

Ver em Markdown

O WhatsApp vê o endereço IP de onde cada número se conecta. Milhares de sessões saindo de poucos IPs de datacenter são um sinal conhecido de automação, e por isso a apiwpp dá a cada conexão, sempre que pode, uma saída própria para a internet. O socket do WhatsApp, os uploads e os downloads de mídia da conexão, incluindo as buscas que a apiwpp faz nas URLs de mídia que você envia, saem todos pelo mesmo caminho.

As três saídas

SaídaComo se obtémQuem divide o IP
IP brasileiro compartilhadoAutomático no pareamento, quando o pool de proxies da apiwpp tem um IP brasileiro com espaço para o projeto.No máximo alguns outros números do mesmo projeto; nunca números de outro projeto.
Proxy próprioVocê informa um proxy seu na criação da conexão ou com PUT /connections/{id}/proxy.Quem você decidir.
IP dedicado (PRO)Contratado por número no painel.Ninguém: um IP fixo de provedor residencial brasileiro só para esse número.

O proxy próprio tem prioridade sobre os outros dois: uma conexão com proxy próprio nunca recebe um IP da apiwpp, nem mesmo o dedicado. O IP compartilhado é dado só no pareamento. Se nesse momento o pool não tem um IP com espaço para o projeto, o número pareia sem proxy da apiwpp e se conecta direto do IP do servidor do gateway; ele continua assim até ser pareado de novo. Para garantir a saída, use um proxy próprio ou um IP dedicado.

Um IP compartilhado não muda por baixo de um número já pareado, a não ser que o proxy dele pare de funcionar: a apiwpp verifica esses proxies periodicamente e move os números de um proxy que caiu para outro.

Proxy próprio

Use um proxy seu quando o número precisa sair de um IP que você controla, por exemplo o mesmo IP em que ele já opera fora da apiwpp. O corpo é o mesmo em todos os lugares que aceitam um proxy:

CampoTipoDescrição
urlstring, obrigatóriosocks5://, socks5h://, http:// ou https:// (os dois últimos usam HTTP CONNECT), com usuario:senha@ opcional. Até 2048 caracteres, só esquema, credenciais, host e porta: sem caminho, query ou fragmento. Com socks5:// e com socks5h://, é o proxy que resolve os nomes de host.
countrystring ou nullO país de onde o proxy precisa sair, em ISO 3166-1 alfa-2 (por exemplo, BR). Omitido ou null: qualquer país.

Na criação da conexão

O jeito mais seguro é informar o proxy ao criar a conexão: ele é verificado antes de qualquer coisa ser criada e gravado antes do primeiro socket, então nem o primeiro QR code sai por fora dele. Se a verificação falhar, a resposta é 400, 422 ou 503 e nenhuma conexão é criada.

curl -s -X POST https://api.apiwpp.com/connections \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "'$TENANT_ID'",
    "proxy": { "url": "socks5://usuario:[email protected]:1080", "country": "BR" }
  }'

POST /tenants/{id}/connections aceita o mesmo campo proxy (veja Criar conexão no projeto).

Numa conexão que já existe

PUT /connections/{id}/proxy define ou troca o proxy (escopo connections:write). Numa conexão ativa, ou a caminho de ficar ativa, um proxy novo provoca uma reconexão planejada por ele; uma conexão parada passa a usá-lo na próxima vez que conectar. Mandar de novo o mesmo proxy, mudando só o country, não reconecta nada.

curl -s -X PUT https://api.apiwpp.com/connections/$CONNECTION_ID/proxy \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "socks5://usuario:[email protected]:1080", "country": "BR"}'
200
{
  "proxy": {
    "scheme": "socks5",
    "host": "br.proxy.example.com",
    "port": 1080,
    "hasCredentials": true,
    "country": "BR",
    "exit": { "ip": "203.0.113.7", "country": "BR", "checkedAt": "2026-09-24T12:00:00.000Z" }
  },
  "reconnecting": true
}

exit é onde a última verificação viu o proxy sair: o IP em que o WhatsApp enxerga o número. reconnecting: true quer dizer que um socket novo, pelo proxy novo, está a caminho. false quer dizer que a conexão está parada e usa o proxy na próxima conexão, que o proxy é o mesmo de antes (só o país mudou), ou que a verificação antes do pareamento o recusou e a conexão foi parada; nesse último caso, o lastError da conexão diz por quê.

A verificação

Antes de gravar o proxy, a apiwpp confere que:

  1. o host do proxy é público (endereços privados e de rede local são recusados com 400);
  2. uma requisição feita através dele a um serviço que informa o IP de saída responde em até 10 segundos e diz de onde ele sai;
  3. com country, a saída fica nesse país.

A mesma verificação roda de novo antes de o número parear: nenhum QR code é mostrado a partir de uma saída não verificada. E uma conexão com proxy nunca se conecta por fora dele: se o proxy parar de funcionar, o socket não abre.

Quando a verificação falha, o 422 diz só o tipo de falha, nunca o que a rede respondeu. As três primeiras chegam como Proxy check failed for <proxy>: <motivo>:

FalhaMensagem
Inalcançávelthe proxy could not be reached, or did not reach the IP echo endpoint (inclui o tempo esgotado)
Credenciais recusadasthe proxy refused the credentials
Sem endereço de saídathe IP echo endpoint did not tell where the proxy exits
Outro paísThe proxy exits at <ip> in <país>, not in <country>: o IP e o país por onde o proxy sai, e o country que você pediu

Cada PUT é uma verificação, e cada organização tem até 60 verificações por hora. Passando disso, a resposta é 429 com Retry-After em segundos. Os proxies informados na criação da conexão não entram nessa conta.

Consultar e remover

GET /connections/{id}/proxy (escopo connections:read) devolve o mesmo objeto proxy sem as credenciais, ou {"proxy": null} quando a conexão não tem proxy próprio. DELETE /connections/{id}/proxy (escopo connections:write) remove o proxy e a conexão passa a se conectar diretamente: uma conexão ativa se reconecta sem ele, e a resposta é {"proxy": null, "reconnecting": true}. Remover quando não há proxy também responde 200.

bashConsultar e remover
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/proxy \
  -H "Authorization: Bearer $API_KEY"

curl -s -X DELETE https://api.apiwpp.com/connections/$CONNECTION_ID/proxy \
  -H "Authorization: Bearer $API_KEY"

Erros

StatusQuando
400A URL não é aceita: vazia, inválida, esquema não suportado, com caminho ou query, senha sem usuário, host que não é público, ou country que não tem duas letras.
404A conexão não existe ou é de outra organização.
422A verificação através do proxy falhou (tabela acima). Nada foi salvo.
429As 60 verificações de proxy da organização nesta hora acabaram, ou o limite de requisições por IP. Espere o Retry-After.
500Só no GET: o proxy gravado não pode ser aberto. É um problema do nosso lado: fale com o suporte.
501unsupported_by_provider: o provedor da conexão não usa proxy (as APIs oficiais não mantêm uma sessão própria).
503O gateway não consegue guardar segredos (nenhuma chave de criptografia configurada). Nada foi salvo.

A página Erros explica o formato do corpo e quando tentar de novo.

IP dedicado

Com o IP dedicado, o número sai por um IP fixo de provedor residencial brasileiro só dele, em vez do IP que divide com alguns outros números do mesmo projeto. Os donos e administradores da organização contratam o adicional no painel, na conexão: ele entra na assinatura mensal da organização, com o restante do mês cobrado de forma proporcional. A compra e o cancelamento não existem na API com chave.

Depois da contratação, o número passa para o IP dedicado em poucos minutos, numa reconexão planejada, ou assim que um IP é comprado para ele. Quando o adicional termina, o número volta para um IP compartilhado do projeto.

Pela API, GET /connections/{id}/dedicated-ip (escopo connections:read) diz em que pé está o adicional da conexão: o que está em uso (provisioning ou active) ou, se não houver, o mais recente. Sem nenhum, a resposta é {"dedicatedIp": null}.

bashVer na referência
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/dedicated-ip \
  -H "Authorization: Bearer $API_KEY"
200
{
  "dedicatedIp": {
    "id": "f5a6b7c8-d9e0-4f1a-8b2c-3d4e5f6a7b8c",
    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
    "status": "active",
    "waived": false,
    "lastError": null,
    "requestedAt": "2026-09-24T12:00:00.000Z",
    "paidAt": "2026-09-24T12:00:00.000Z",
    "activatedAt": "2026-09-24T12:00:00.000Z",
    "canceledAt": null
  }
}
statusO que quer dizer
awaiting_paymentA contratação ainda não foi paga.
provisioningPago; o número ainda não está no IP dedicado.
activeO número sai por um IP só dele.
canceledO adicional terminou; o número voltou para um IP compartilhado.

waived: true indica um adicional concedido pela nossa equipe, sem cobrança. Quando o adicional não está ativo, lastError diz por quê:

lastErrorO que quer dizer
waiting_for_proxyO IP dedicado do número está sendo comprado.
own_proxyA conexão usa um proxy próprio, que tem prioridade sobre o IP dedicado.
connection_deletedA conexão foi excluída.
duplicateUm segundo adicional foi pago para uma conexão que já tinha um.
unplacedO adicional terminou e ainda não há um IP compartilhado com espaço para o número.

A resposta nunca mostra o IP nem o proxy do adicional.

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026