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

# Listar Contatos

> Lista os contatos do dispositivo WhatsApp conectado ao canal

# Listar Contatos

O comando **Contatos** retorna a lista de contatos salvos no dispositivo WhatsApp conectado ao canal.
Você pode filtrar os resultados usando o campo `query`.

## Requisição

```
POST /api/v1/message/SendCommand
```

```json theme={null}
{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "CONTACTS",
    "commandType": "CONTACTS",
    "query": "João"
  }
}
```

### Campos

| Campo   | Tipo     | Obrigatório | Descrição                                                                  |
| ------- | -------- | ----------- | -------------------------------------------------------------------------- |
| `query` | `string` | Não         | Filtro de busca por nome do contato. Se omitido, retorna todos os contatos |

## Resposta da API

```json theme={null}
{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

## Webhook de resposta

O resultado é entregue via webhook do tipo `CONTACTS_RESPONSE`:

```json theme={null}
{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "uuid-do-canal",
  "content": {
    "type": "CONTACTS_RESPONSE",
    "contacts": [
      {
        "businessName": "Loja do João",
        "fullName": "João da Silva",
        "jid": "5511999887766@s.whatsapp.net",
        "lid": "12345678901234:56@lid",
        "name": "João",
        "pushName": "João Silva"
      },
      {
        "businessName": "",
        "fullName": "João Pedro Santos",
        "jid": "5521988776655@s.whatsapp.net",
        "lid": "98765432109876:78@lid",
        "name": "João Pedro",
        "pushName": "JP Santos"
      }
    ],
    "count": 2
  }
}
```

### Campos da resposta

| Campo                     | Tipo      | Descrição                                        |
| ------------------------- | --------- | ------------------------------------------------ |
| `contacts`                | `array`   | Lista de contatos encontrados                    |
| `contacts[].businessName` | `string`  | Nome comercial (para contas Business)            |
| `contacts[].fullName`     | `string`  | Nome completo do contato                         |
| `contacts[].jid`          | `string`  | Identificador único do contato no WhatsApp (JID) |
| `contacts[].lid`          | `string`  | Identificador LID do contato                     |
| `contacts[].name`         | `string`  | Nome salvo na agenda                             |
| `contacts[].pushName`     | `string`  | Nome definido pelo proprio contato no WhatsApp   |
| `count`                   | `integer` | Total de contatos retornados                     |

## Exemplo completo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-dev.messagefy.io/api/v1/message/SendCommand \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: sua-api-key" \
    -d '{
      "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": {
        "type": "CONTACTS",
        "commandType": "CONTACTS",
        "query": "João"
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api-dev.messagefy.io/api/v1/message/SendCommand",
      headers={
          "Content-Type": "application/json",
          "X-API-KEY": "sua-api-key"
      },
      json={
          "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "content": {
              "type": "CONTACTS",
              "commandType": "CONTACTS",
              "query": "João"
          }
      }
  )

  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api-dev.messagefy.io/api/v1/message/SendCommand",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "sua-api-key",
      },
      body: JSON.stringify({
        channelId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        content: {
          type: "CONTACTS",
          commandType: "CONTACTS",
          query: "João",
        },
      }),
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

<Tip>
  Para obter informações detalhadas de um contato específico (como foto de perfil),
  use o comando [Info do Contato](/comandos/info-contato).
</Tip>