Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Enviar e receber

Contatos pela API de WhatsApp: verificar números, ver perfil e foto

Como conferir se um telefone tem WhatsApp, ver nome, foto e perfil comercial e listar contatos pela API, com os tetos diários de consulta.

6 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Use POST /contacts/check com até 50 telefones para saber quais têm WhatsApp; a resposta traz o number na forma que existe (com ou sem o nono dígito). O teto é de 300 números por dia. Perfil, foto e perfil comercial têm teto de 120 consultas por dia.

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/v1 e a chave vai no cabeçalho apikey.

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.

bash
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"]}'
json
{ "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 e exists diz 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 number devolvido é 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.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999" -H "apikey: SUA_CHAVE"
json
{ "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:

json
{ "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átis

Como 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 /contacts lista os contatos que a instância conhece, com jid, phone e name.
  • GET /profile/privacy mostra 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/name com name (até 25 caracteres) troca o nome que aparece para quem não tem você nos contatos.
  • PUT /profile/avatar com media (uma imagem JPEG ou PNG, por url ou base64) 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:

python
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

Í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.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp