# Perfil do contato

Fonte: https://apiwpp.com/docs/api/contatos/perfil-do-contato
Seção: Contatos
Atualizado em: 2026-09-28

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

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador da conexão (o número) que faz a consulta. |
| `phone` | `string` | sim | 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. |

## Exemplo de requisição

### cURL

```bash
curl https://api.apiwpp.com/connections/$CONNECTION_ID/profile/$PHONE \
  -H "Authorization: Bearer $API_KEY"
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/profile/${phone}`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->get("https://api.apiwpp.com/connections/{$connectionId}/profile/{$phone}");
```

### Python

```python
import requests

response = requests.get(
    f"https://api.apiwpp.com/connections/{connection_id}/profile/{phone}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
```

## Respostas

| Código | Erro | 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_VALIDATION` | O `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_inactive` | A 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](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |
| 500 |  | A consulta do perfil falhou por inteiro (`Failed to get profile`). Nada muda: repita depois. |
| 501 | `unsupported_by_provider` | O 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çalhos: `Retry-After`. |

### 200 OK

```json
{
  "phone": "5511988887777",
  "status": "Available",
  "pictureUrl": "https://pps.whatsapp.net/v/t61.24694-24/profile.jpg"
}
```

## 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](https://apiwpp.com/docs/api/contatos/verificar-numeros).

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](https://apiwpp.com/docs/guias/enviar-mensagens).
