Pular para o conteúdo

Perfil do contato

GET/connections/{id}/profile/{phone}

Consulta o que o WhatsApp mostra do perfil de um contato para o número da conexão: o recado (o texto “sobre”) e a URL da foto do perfil. Escopo necessário: messages:send.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador da conexão (o número) que faz a consulta.

phonestringobrigatório

O contato: um número de telefone com código do país e DDD (por exemplo, 5511988887777; só os dígitos são lidos) ou um JID (…@s.whatsapp.net, …@lid), usado como veio.

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200O perfil: phone (só os dígitos do contato consultado), status (o recado do perfil) e pictureUrl (a URL da foto do perfil). status e pictureUrl não vêm quando o contato os esconde ou quando o WhatsApp não os informa.
400FST_ERR_VALIDATIONO id do caminho não é um UUID. message diz o que está errado.
400A conexão não está open (Connection not ready (status: …)): o número precisa estar pareado e conectado.
401Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}.
402subscription_inactiveA organização não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Regularize o pagamento no painel para voltar a usar o número.
403A chave não tem o escopo messages:send; a mensagem cita o escopo (This credential lacks the messages:send scope).
404A conexão não existe ou não é de quem chama: o recurso de outra pessoa responde exatamente como um que não existe ({"error": "Connection not found"}).
429Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After
500A consulta do perfil falhou por inteiro (Failed to get profile). Nada muda: repita depois.
501unsupported_by_providerO provedor da conexão não faz esta consulta. O corpo é {"error": "unsupported_by_provider"}.
503A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere os segundos de Retry-After e tente de novo.Cabeçalho: Retry-After

Detalhes

Um campo que o contato esconde nas configurações de privacidade dele não vem na resposta, e o mesmo acontece quando o WhatsApp não responde a parte dele: a consulta do recado e a da foto são independentes, e a falha de uma não derruba a outra. name faz parte do schema, mas hoje o gateway não o preenche.

Esta consulta não diz se o número está no WhatsApp: um número sem conta responde 200 só com phone. Para saber, use Verificar números.

Com um número de telefone, o gateway monta o endereço a partir dos dígitos (<dígitos>@s.whatsapp.net) e não pergunta ao WhatsApp em qual endereço a conta está registrada. Para uma conta brasileira registrada antes do nono dígito, passe em phone o jid que POST /connections/{id}/contacts/check respondeu.

A consulta usa a sessão de WhatsApp do número, como um envio: por isso pede o escopo messages:send, a conexão open e a organização em dia. Se ela falhar por inteiro, a resposta é 500 ({"error": "Failed to get profile"}).

Guia: Enviar mensagens

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