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.
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ída | Como se obtém | Quem divide o IP |
|---|---|---|
| IP brasileiro compartilhado | Automá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óprio | Você 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:
| Campo | Tipo | Descrição |
|---|---|---|
url | string, obrigatório | socks5://, 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. |
country | string ou null | O 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" }
}'const res = await fetch('https://api.apiwpp.com/connections', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
tenantId: process.env.TENANT_ID,
proxy: { url: process.env.PROXY_URL, country: 'BR' },
}),
})
const { connectionId } = await res.json()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"}'const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/proxy`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ url: process.env.PROXY_URL, country: 'BR' }),
})
if (res.status === 429) {
const wait = Number(res.headers.get('retry-after'))
// Espere `wait` segundos antes da próxima verificação.
}
const { proxy, reconnecting } = await res.json(){
"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:
- o host do proxy é público (endereços privados e de rede local são recusados com
400); - 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;
- 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>:
| Falha | Mensagem |
|---|---|
| Inalcançável | the proxy could not be reached, or did not reach the IP echo endpoint (inclui o tempo esgotado) |
| Credenciais recusadas | the proxy refused the credentials |
| Sem endereço de saída | the IP echo endpoint did not tell where the proxy exits |
| Outro país | The 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.
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
| Status | Quando |
|---|---|
400 | A 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. |
404 | A conexão não existe ou é de outra organização. |
422 | A verificação através do proxy falhou (tabela acima). Nada foi salvo. |
429 | As 60 verificações de proxy da organização nesta hora acabaram, ou o limite de requisições por IP. Espere o Retry-After. |
500 | Só no GET: o proxy gravado não pode ser aberto. É um problema do nosso lado: fale com o suporte. |
501 | unsupported_by_provider: o provedor da conexão não usa proxy (as APIs oficiais não mantêm uma sessão própria). |
503 | O 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}.
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/dedicated-ip \
-H "Authorization: Bearer $API_KEY"{
"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
}
}status | O que quer dizer |
|---|---|
awaiting_payment | A contratação ainda não foi paga. |
provisioning | Pago; o número ainda não está no IP dedicado. |
active | O número sai por um IP só dele. |
canceled | O 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ê:
lastError | O que quer dizer |
|---|---|
waiting_for_proxy | O IP dedicado do número está sendo comprado. |
own_proxy | A conexão usa um proxy próprio, que tem prioridade sobre o IP dedicado. |
connection_deleted | A conexão foi excluída. |
duplicate | Um segundo adicional foi pago para uma conexão que já tinha um. |
unplaced | O 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
- Definir proxy, Consultar proxy e Remover proxy: os campos e as respostas completos.
- Parear um número: o QR code, o código de pareamento e os status da conexão.
- Limites de envio: o ritmo e o aquecimento que protegem o número, qualquer que seja o IP.
- Projetos e conexões: criar, reconectar e excluir conexões.