> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wappfy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Contatos

> Consulte contatos, verifique números de telefone e recupere fotos de perfil antes de enviar mensagens.

# Contatos

A API de Contatos permite verificar números de telefone no WhatsApp, recuperar informações de contatos e buscar fotos de perfil. Isso é especialmente útil para validar números antes de enviar mensagens e enriquecer seus dados de contato.

Todos os endpoints de contatos são vinculados a uma instância específica:

```
/api/instances/{instanceId}/contacts/...
```

***

## Verificar se um Número Existe

Verifique se um número de telefone está registrado no WhatsApp antes de enviar uma mensagem. Isso previne entregas falhas e chamadas de API desperdiçadas.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/check?phone=5511999998888" \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/contacts/check?phone=5511999998888",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  if (data.exists) {
    console.log(`Número existe no WhatsApp: ${data.chat_id}`);
  } else {
    console.log("Número não está no WhatsApp");
  }
  ```
</CodeGroup>

**Resposta (número existe):**

```json theme={null}
{
  "data": {
    "exists": true,
    "phone": "5511999998888",
    "chat_id": "5511999998888@s.whatsapp.net"
  }
}
```

**Resposta (número não existe):**

```json theme={null}
{
  "data": {
    "exists": false,
    "phone": "5511999998888",
    "chat_id": null
  }
}
```

<Tip>
  Use este endpoint para validar números antes de enviar mensagens. Isso economiza cota de mensagens e previne eventos `message.failed` no webhook.
</Tip>

***

## Listar Todos os Contatos

Recupere a lista completa de contatos da conta WhatsApp conectada.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/contacts \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/contacts",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  console.log(`Total de contatos: ${data.length}`);
  ```
</CodeGroup>

### Campos do Contato

| Campo         | Descrição                                                                  |
| ------------- | -------------------------------------------------------------------------- |
| `id`          | ID do contato no WhatsApp (número + `@s.whatsapp.net`).                    |
| `name`        | Nome do contato salvo na agenda do telefone. Pode ser `null` se não salvo. |
| `short_name`  | Nome curto da agenda.                                                      |
| `push_name`   | Nome que o contato definiu para si mesmo no WhatsApp.                      |
| `is_business` | Se é uma conta WhatsApp Business.                                          |

<Note>
  O campo `name` vem da agenda do telefone. Se o contato não está salvo, apenas `push_name` (definido pelo próprio contato) estará disponível.
</Note>

***

## Informações do Contato

Recupere informações detalhadas sobre um contato específico.

```bash theme={null}
curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net" \
  -H "X-Api-Key: YOUR_API_KEY"
```

***

## Foto de Perfil

Recupere a URL da foto de perfil do WhatsApp de um contato.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net/profile-picture" \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net/profile-picture",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  if (data.profile_picture_url) {
    console.log(`Foto de perfil: ${data.profile_picture_url}`);
  } else {
    console.log("Sem foto de perfil definida");
  }
  ```
</CodeGroup>

<Note>
  URLs de fotos de perfil são temporárias e expiram após algum tempo. Não as armazene permanentemente — busque uma URL nova quando necessário.
</Note>

***

## Padrões Comuns

### Validar Antes de Enviar

Sempre verifique se um número existe no WhatsApp antes de enviar uma mensagem:

```javascript theme={null}
async function enviarMensagemComSeguranca(instanceId, phone, text) {
  // Passo 1: Verificar se o número está no WhatsApp
  const checkResponse = await fetch(
    `https://api.wappfy.io/api/instances/${instanceId}/contacts/check?phone=${phone}`,
    { headers: { "X-Api-Key": "YOUR_API_KEY" } }
  );
  const { data: checkResult } = await checkResponse.json();

  if (!checkResult.exists) {
    console.log(`${phone} não está no WhatsApp, pulando`);
    return null;
  }

  // Passo 2: Enviar a mensagem usando o chat_id confirmado
  const sendResponse = await fetch(
    `https://api.wappfy.io/api/instances/${instanceId}/messages/send`,
    {
      method: "POST",
      headers: {
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: checkResult.chat_id,
        type: "text",
        text,
      }),
    }
  );

  return sendResponse.json();
}
```

<Warning>
  Ao buscar fotos de perfil para muitos contatos, adicione um atraso entre as requisições para respeitar os [limites de taxa](/pt-BR/rate-limits). Recomendamos 200ms entre chamadas.
</Warning>

***

## Referência de Endpoints

| Método | Endpoint                                                   | Descrição                              |
| ------ | ---------------------------------------------------------- | -------------------------------------- |
| `GET`  | `/api/instances/{id}/contacts`                             | Listar todos os contatos               |
| `GET`  | `/api/instances/{id}/contacts/check?phone={phone}`         | Verificar se número existe no WhatsApp |
| `GET`  | `/api/instances/{id}/contacts/{contactId}`                 | Informações do contato                 |
| `GET`  | `/api/instances/{id}/contacts/{contactId}/profile-picture` | Foto de perfil                         |

***

## Tratamento de Erros

| Código | Descrição                                                                                 |
| ------ | ----------------------------------------------------------------------------------------- |
| `400`  | Formato de número inválido. Use apenas dígitos, com código do país (ex: `5511999998888`). |
| `404`  | Instância ou contato não encontrado.                                                      |
| `429`  | Limite de taxa excedido. Veja [Limites de Taxa](/pt-BR/rate-limits).                      |