API de foto de perfil do WhatsApp: Análise de avatar em tempo real por número de telefone

Um guia para desenvolvedores sobre APIs de foto de perfil do WhatsApp: o que as ferramentas baseadas apenas em URL retornam, como as solicitações de avatar do WhatsApp em tempo real e síncronas do AvatarLookup diferem, e como armazenar e repetir resultados.

Uma API de foto de perfil do WhatsApp recebe um número de telefone e retorna informações sobre a foto de perfil pública associada a ele. Muitas ferramentas param em uma URL de imagem temporária que você deve baixar e interpretar por conta própria. A Análise de foto de perfil do WhatsApp do AvatarLookup retorna um resultado estruturado: uma verificação única em tempo real via POST /api/v1/check ou uma verificação múltipla síncrona via POST /api/v1/batch-check com 1–100 números por solicitação. Os atributos de aparência no resultado são estimativas algorítmicas. Apenas avatares públicos são analisados; portanto, um contato que limita sua foto a contatos salvos não mostra uma imagem pública, e um resultado Indeterminado deve ser verificado novamente mais tarde, em vez de ser interpretado como um veredito sobre a conta.

Três tipos de API de foto de perfil do WhatsApp

Os resultados de pesquisa para este termo misturam três coisas diferentes, e escolher a errada desperdiça tempo de integração.

As configurações comerciais oficiais são para a foto da sua própria conta, não para consultar outros números. Ferramentas apenas de URL retornam links que geralmente expiram, fazendo com que as equipes acabem baixando, armazenando e rotulando imagens por conta própria. A análise de avatar pula a etapa de manipulação de imagem e retorna dados que se encaixam em um registro de contato. Todos os três são limitados pela mesma regra: a foto deve estar visível publicamente.

Verificação única em tempo real com POST /api/v1/check

Use a verificação única quando um número precisar de uma resposta dentro de um fluxo interativo, como um agente de suporte abrindo um registro de contato.

1. Normalize o número. Converta-o para o formato internacional com o código do país, seguindo a estrutura da ITU-T Recommendation E.164, e remova espaços, traços e colchetes.
2. Envie uma solicitação autenticada para POST /api/v1/check nomeando o produto de avatar do WhatsApp e o número. Siga a documentação da API para o corpo da solicitação exato; não tente adivinhar nomes de campos.
3. Leia a resposta uma vez e armazene-a com a data da verificação e um rótulo de origem do WhatsApp.
4. Ramifique com base no resultado: Foto de perfil disponível, Sem foto de perfil ou Indeterminado.

Mantenha a chamada fora de qualquer caminho de bloqueio que o cliente precise aguardar. Se a verificação for lenta ou Indeterminada, o registro ainda deve ser salvo, com os campos de avatar deixados vazios e um sinalizador de que uma verificação posterior é necessária. Números da China continental, Hong Kong e Macau são suportados apenas por meio de verificações únicas em tempo real, portanto, direcione-os para cá em vez de arquivos em lote.

Verificação múltipla síncrona com POST /api/v1/batch-check

A verificação múltipla lida com uma lista curta em uma única chamada. Cada solicitação aceita 1–100 identificadores de um tipo de produto e retorna resultados como JSON ordenado, correspondendo à ordem enviada.

Regras práticas para solicitações múltiplas:

• Não misture produtos. Envie números do WhatsApp em uma solicitação e endereços Gmail, Yandex ou Mail.ru suportados em outra.
• Confie na ordem, depois verifique. Os resultados seguem a ordem de entrada; ainda assim, faça a correspondência de cada resultado com seu número de entrada antes de gravar em seu banco de dados.
• Divida listas maiores. Divida uma lista de 350 números em quatro solicitações de até 100.
• Use tarefas em lote para arquivos grandes. Quando uma lista for muito maior, o produto em lote assíncrono do WhatsApp aceita um arquivo TXT ou CSV e retorna um CSV para a tarefa.

Equipes não técnicas podem usar o painel, que aceita até 500 identificadores e os processa um por um. De qualquer forma, apenas o WhatsApp e os domínios de e-mail suportados possuem verificações em tempo real e múltiplas; Telegram, Viber, MAX, LINE e Zalo são apenas para processamento em lote.

Lidando com resultados Indeterminados e Sem foto de perfil

A maioria dos erros de integração vem da fusão de resultados diferentes em um único valor vazio. Mantenha-os separados:

• Resultado produzido. A resposta múltipla marca cada item onde um resultado foi produzido. Esse sinalizador significa que um resultado existe para a solicitação, não que a conta do WhatsApp exista.
• Resultado não produzido. Isso cobre itens inválidos, Indeterminados ou com falha. Não é um veredito negativo sobre a conta ou seu avatar, portanto, agende uma nova tentativa mais tarde em vez de excluir o contato.
• Sem foto de perfil. Um resultado concluído pode mostrar que nenhuma imagem pública está disponível. As configurações de privacidade do WhatsApp permitem que os usuários mostrem sua foto de perfil para Todos, Meus contatos, Meus contatos, exceto... ou Ninguém, portanto, uma imagem pública ausente geralmente é apenas uma escolha de privacidade.

Grave cada estado em seu próprio valor, como público, nenhum ou repetir, e registre o motivo das novas tentativas. Um modelo de estado limpo também torna os relatórios honestos: uma contagem no painel de "Sem foto de perfil" nunca deve incluir itens que foram simplesmente Indeterminados.

Armazenando resultados como estimativas

Atributos de aparência, como tipo de imagem, faixa etária ou cor de cabelo, descrevem a imagem, não a pessoa por trás do número. Um desenho animado, um animal de estimação, um logotipo ou uma foto de grupo podem ser fotos de perfil válidas, e uma análise delas ainda é uma resposta concluída.

Um padrão de armazenamento simples:

Mantenha esses campos fora de decisões de elegibilidade, crédito, contratação ou preços, e fora de qualquer triagem que trate as pessoas de forma diferente por idade ou gênero estimados. Um avatar público é um sinal de dados de contato; ele não verifica identidade, propriedade da conta ou consentimento para contato. Defina um intervalo de revisão, pois os usuários alteram suas fotos, e exclua estimativas obsoletas de acordo com sua política de retenção normal.

Perguntas frequentes

Como as equipes podem obter o arquivo de imagem real em vez de campos de análise?

A análise de avatar foi projetada para retornar resultados estruturados sobre o avatar público, não para atuar como um downloader de imagens. Se um fluxo de trabalho realmente precisar exibir imagens, considere se isso é necessário para o propósito e como os arquivos seriam armazenados e excluídos. Muitos fluxos de trabalho de dados de contato só precisam saber se um avatar público existe e que tipo de imagem é, o que a análise já responde.

Como os desenvolvedores devem repetir verificações Indeterminadas do WhatsApp?

Colete números Indeterminados em uma fila de repetição em vez de reenviá-los imediatamente em um loop. Verifique-os novamente mais tarde em uma solicitação única ou múltipla e limite o número de tentativas por número para que uma falha persistente não seja executada para sempre. Após a tentativa final, mantenha o registro como Indeterminado em vez de convertê-lo para Sem foto de perfil, pois esses resultados significam coisas diferentes.

Como as equipes podem verificar uma imagem que já possuem em vez de um número de telefone?

Use a Análise de perfil por imagem. Ela aceita arquivos JPEG, PNG, WebP ou GIF e é chamada por meio do endpoint de perfil de imagem documentado com um upload de arquivo multipart. Ela descreve a própria imagem, retornando o tipo de imagem e atributos de aparência como estimativas algorítmicas, sem envolver número de telefone ou conta. Isso é adequado para imagens que um cliente enviou diretamente, como uma foto de perfil enviada por meio de um formulário.

Saiba mais

Escolha as informações do produto que se encaixam na próxima etapa do seu fluxo de trabalho.

• Visite o site do produto →