Provado em aparelho real em 10/11/2026: lista de contatos, dados de um contato, foto e privacidade. Beta: pode mudar: verificar números, perfil comercial e mudar nome e foto do seu número. A base é
https://proxybox.com.br/api/whatsapp/v1e a chave vai no cabeçalhoapikey.
Atualização de 12/11/2026 (provado em aparelho real): a verificação de números pela rota da Evolution (
whatsappNumbers) foi provada.
Uma lista de clientes sempre tem telefone digitado errado, linha fixa e gente sem WhatsApp. Verificar o número antes de enviar poupa mensagens que falhariam e deixa a sua base mais limpa. Este guia mostra a verificação e as demais consultas de contato.
Como verifico se o número tem WhatsApp?
Com POST /contacts/check e uma lista numbers de 1 a 50 telefones.
POST /contacts/check recebe numbers, uma lista de 1 a 50 telefones.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/contacts/check" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"numbers":["+55 47 99999-9999","5511988887777"]}'
{ "ok": true, "data": { "results": [
{ "input": "+55 47 99999-9999", "exists": true, "number": "5547999999999", "jid": "[email protected]" },
{ "input": "5511988887777", "exists": false, "number": "5511988887777", "jid": null }
] } }
inputé o que você mandou,numberé o telefone normalizado eexistsdiz se há WhatsApp.- No Brasil, algumas contas antigas não têm o nono dígito. A API já resolve isso: quando existe só a forma sem o 9 (ou só a com o 9), o
numberdevolvido é a forma que existe. Use esse valor nos envios. - A API consulta um número por vez, com intervalo de 0,3 segundo entre eles. Uma chamada com 50 números pode levar mais de 15 segundos; configure um prazo de resposta (timeout) de pelo menos 60 segundos.
- O teto padrão é de 300 números por dia por instância.
Por que há teto? Consultar milhares de números que nunca falaram com você pode parecer varredura para o WhatsApp. Verifique a lista que você vai usar, não uma faixa de números sorteados.
Como vejo o perfil de um telefone?
Com GET /contacts/{phone}, que devolve nome, recado, verified_name e se a conta é comercial.
curl "https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999" -H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "name": "Maria", "status": "Disponível", "picture_id": "1730000000", "verified_name": null, "business": false } }
status é o recado do perfil, verified_name aparece em contas comerciais verificadas, e business diz se a conta é do WhatsApp Business.
Como pego a foto do perfil?
Com GET /contacts/{phone}/avatar. Quando a foto não está disponível, a resposta traz url nulo e o motivo.
GET /contacts/{phone}/avatar devolve data.url com o endereço da foto. Use ?preview=true para a versão pequena.
Quando a foto não está disponível, a resposta continua sendo sucesso, com o motivo:
{ "ok": true, "data": { "url": null, "reason": "hidden" } }
hidden: a pessoa configurou a foto para não aparecer para você.not_set: a pessoa não tem foto.
O endereço devolvido pode expirar. Baixe e guarde a imagem se precisar dela depois.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisComo vejo o perfil comercial?
Com GET /contacts/{phone}/business, que devolve e-mail, endereço, categorias e horários quando a conta é comercial.
GET /contacts/{phone}/business devolve email, address, categories (lista) e hours (lista de horários) quando o número é uma conta comercial. Para uma conta comum, o retorno pode vir vazio ou com o erro not_found.
Como listo os contatos e vejo a privacidade do número?
Com GET /contacts (os contatos que a instância conhece) e GET /profile/privacy (a configuração do seu número).
GET /contactslista os contatos que a instância conhece, comjid,phoneename.GET /profile/privacymostra como o seu número está configurado: quem pode ver "visto por último", recado, foto e confirmação de leitura, e quem pode te adicionar a grupos.
Como mudo o nome e a foto do meu número?
Com PUT /profile/name (até 25 caracteres) e PUT /profile/avatar (imagem JPEG ou PNG).
PUT /profile/namecomname(até 25 caracteres) troca o nome que aparece para quem não tem você nos contatos.PUT /profile/avatarcommedia(uma imagem JPEG ou PNG, porurloubase64) troca a foto.
Ambas são ações leves, com teto de 60 por minuto, mas trocar nome e foto toda hora é comportamento incomum. Faça uma vez, com calma.
Quais são os limites das consultas?
Verificar número: 300 por dia. Perfil, foto e perfil comercial: 120 por dia. Intervalo mínimo de 0,3 segundo entre consultas.
| Consulta | Teto por instância |
|---|---|
| Verificar número | 300 por dia |
| Perfil, foto e perfil comercial | 120 por dia |
| Intervalo mínimo entre consultas | 0,3 segundo |
| Listar contatos e ver privacidade | 120 por minuto |
Passou do teto: 429 com daily_limit ou rate_limited e o retry_after. A tabela completa está em erros e limites.
Como verifico antes de enviar, no n8n ou em código?
Planilha, depois POST /contacts/check, depois um filtro por exists, e só então o envio.
Uma sequência simples: planilha, nó HTTP Request em /contacts/check, nó IF em exists, e só então o envio. O fluxo pronto está em WhatsApp no n8n. Em código, o mesmo cabe em poucas linhas:
import os, requests
base = "https://proxybox.com.br/api/whatsapp/v1"
h = {"apikey": os.environ["WA_KEY"]}
r = requests.post(f"{base}/contacts/check", headers=h, json={"numbers": ["5547999999999"]}, timeout=90).json()
for item in r["data"]["results"]:
if item["exists"]:
requests.post(f"{base}/messages/text", headers=h,
json={"to": item["number"], "text": "Olá! Seu pedido está pronto."}, timeout=30)
Veja também
- Nono dígito e @lid na API de WhatsApp
- Não perturbe e recusar chamadas: API de WhatsApp
- Criar e administrar grupos de WhatsApp pela API
- Erros e limites da API de WhatsApp
Índice completo: documentação. Sobre o produto: conheça a API de WhatsApp da ProxyBox.
Autoria: equipe técnica da ProxyBox. Revisado em 11/11/2026 contra a versão 1.1 da API.