Perfil do contato
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.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador da conexão (o número) que faz a consulta.
phonestringobrigatórioO 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
| Código | Erro e descrição |
|---|---|
| 200 | O 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. |
| 400 | FST_ERR_VALIDATIONO id do caminho não é um UUID. message diz o que está errado. |
| 400 | A conexão não está open (Connection not ready (status: …)): o número precisa estar pareado e conectado. |
| 401 | Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}. |
| 402 | subscription_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. |
| 403 | A chave não tem o escopo messages:send; a mensagem cita o escopo (This credential lacks the messages:send scope). |
| 404 | A 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"}). |
| 429 | Requisiçõ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 |
| 500 | A consulta do perfil falhou por inteiro (Failed to get profile). Nada muda: repita depois. |
| 501 | unsupported_by_providerO provedor da conexão não faz esta consulta. O corpo é {"error": "unsupported_by_provider"}. |
| 503 | A 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