Pular para o conteúdo

Definir proxy

PUT/connections/{id}/proxy

Traga o seu próprio proxy: a partir de agora, o socket de WhatsApp da conexão e os uploads e downloads de mídia (os dela e as buscas que o gateway faz nas URLs das suas mídias) saem por ele, nunca por fora dele. Escopo necessário: connections:write.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador da conexão (o número).

Corpo da requisição

urlstringobrigatório

URL do proxy: socks5://, socks5h:// (nos dois, é o proxy que resolve os nomes de host), http:// ou https:// (os dois últimos por HTTP CONNECT), com usuario:senha@ opcional. Só esquema, credenciais, host e porta, sem caminho, query ou fragmento; o host precisa ser público. É gravada criptografada e nunca volta em nenhuma resposta.

de 1 a 2048 caracteres
countrystring | null

País de onde o proxy precisa sair, em ISO 3166-1 alfa-2 (por exemplo, BR). Omitido ou null: qualquer país.

formato `^[A-Za-z]{2}$`

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200O proxy como foi salvo (proxy, sem as credenciais, com a saída verificada em exit) e reconnecting: true quando um socket novo pelo proxy está a caminho; false quando a conexão está parada e usa o proxy na próxima conexão, quando o proxy é o mesmo de antes (só o país mudou), ou quando a verificação antes do pareamento o recusou e a conexão foi parada (o lastError dela diz por quê).
400A URL do proxy não é aceita: não é uma URL, o esquema não é socks5, socks5h, http ou https, tem caminho, query ou fragmento, tem senha sem usuário, o host não é público, ou country não tem duas letras.
400FST_ERR_VALIDATIONA requisição não segue o schema da operação (por exemplo, um id que não é um UUID); message diz o que está errado.
401Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}.
403A chave não tem o escopo connections:write; a mensagem de erro cita o escopo que falta.
404A conexão não existe ou não é de quem chama: a de outra pessoa responde exatamente como uma que não existe (Connection not found).
422A verificação pelo proxy falhou, e a mensagem diz só como: o proxy não foi alcançado ou não alcançou o serviço que informa o IP de saída (the proxy could not be reached…, inclusive por tempo esgotado), recusou as credenciais (the proxy refused the credentials), não disse de onde sai (the IP echo endpoint did not tell where the proxy exits) ou sai em outro país que não o de country.
429As verificações de proxy da organização nesta hora acabaram (Too many proxy checks: at most 60 an hour…), ou o limite por IP de origem: espere os segundos de Retry-After.
501unsupported_by_providerO provedor da conexão não faz esta operação: o provedor dela não guarda uma sessão do WhatsApp e não usa proxy.
503Este gateway não consegue guardar URLs de proxy, porque nenhuma chave de criptografia está configurada. Nada é salvo.

Detalhes

Antes de ser salvo, o host do proxy precisa ser público, e uma requisição por ele precisa dizer por onde ele sai (e, com country, sair nesse país). A mesma verificação roda de novo antes de o número parear, e nenhum QR code é mostrado a partir de uma saída não verificada.

Numa conexão ativa, ou a caminho de ficar ativa, um proxy novo é uma reconexão planejada por ele (reconnecting: true). Uma conexão parada passa a usá-lo na próxima vez que conectar. O mesmo proxy de novo, só com um country novo, não reconecta nada.

Cada PUT é uma verificação, e cada organização tem até 60 verificações por hora (429 com Retry-After depois disso). Para uma conexão nova usar um proxy desde o primeiro socket, informe-o ao criar a conexão.

Guia: Proxy e IP dedicado

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