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

# Listar contatos

> Lista todos os contatos sincronizados ou consulta um número específico

**Auth:** `TokenAccount` ou `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** sim

## Descrição

Retorna a lista de contatos sincronizados no `ContactStore` do WhatsMeow, são os contatos vindos da agenda do telefone principal: nome, push name, business name e telefone redacted.

Se `?number=` for fornecido, devolve um único contato. Caso o número não esteja na agenda, ainda assim a resposta é `200 OK` com `contact.found = false`.

<Info>
  Operação de **leitura pura** sobre o store local, não gera tráfego no WhatsApp.
</Info>

## Exemplos

### Listar todos

Sem query params, retorna todos os contatos sincronizados no `ContactStore` local da instância, com `total` indicando o tamanho da lista.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://ryzeapi.cloud/api/chat/contacts/${process.env.Instance_Name}`, {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

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

  requests.get(
      f"https://ryzeapi.cloud/api/chat/contacts/{os.environ['Instance_Name']}",
      headers={"token": os.environ["Token_Instance"]}
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/chat/contacts/"+os.Getenv("Instance_Name"), nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Número específico

Filtra por `?number=5511999999999` (telefone internacional). Retorna o objeto `contact` único, com `found=false` quando o número não está na agenda sincronizada.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name?number=5511999999999" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://ryzeapi.cloud/api/chat/contacts/${process.env.Instance_Name}?number=5511999999999`, {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

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

  requests.get(
      f"https://ryzeapi.cloud/api/chat/contacts/{os.environ['Instance_Name']}?number=5511999999999",
      headers={"token": os.environ["Token_Instance"]}
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/chat/contacts/"+os.Getenv("Instance_Name")+"?number=5511999999999", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### JID completo

Aceita o JID inteiro em `?number=5511999999999@s.whatsapp.net` quando você já possui o identificador completo (vindo de webhook ou outra resposta da API), evitando montar manualmente o sufixo.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name?number=5511999999999@s.whatsapp.net" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://ryzeapi.cloud/api/chat/contacts/${process.env.Instance_Name}?number=5511999999999@s.whatsapp.net`, {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

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

  requests.get(
      f"https://ryzeapi.cloud/api/chat/contacts/{os.environ['Instance_Name']}?number=5511999999999@s.whatsapp.net",
      headers={"token": os.environ["Token_Instance"]}
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/chat/contacts/"+os.Getenv("Instance_Name")+"?number=5511999999999@s.whatsapp.net", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

## Resposta de sucesso

Sem `?number`, retorna `contacts` (array) com todos os contatos sincronizados pela agenda + `total`. Com `?number=...`, retorna apenas `contact` (objeto único). Cada item traz `jid`, `lid` (quando aplicável), os nomes disponíveis (`first_name`, `full_name`, `push_name`, `business_name`) e `redacted_phone` para casos em que só conhecemos o LID. O campo `found` indica se a entrada veio do store.

```json 200 OK theme={null}
{
  "success": true,
  "message": "Contacts retrieved successfully",
  "contacts": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "lid": "",
      "first_name": "João",
      "full_name": "João Silva",
      "push_name": "João",
      "business_name": "",
      "redacted_phone": "+55 11 ..... 9999",
      "found": true
    },
    {
      "jid": "5511888888888@s.whatsapp.net",
      "full_name": "Maria",
      "push_name": "Maria S.",
      "found": true
    }
  ],
  "total": 42
}
```

## Parâmetros de rota

<ParamField path="instance" type="string" required>
  Nome da instância (ex.: `$Instance_Name`).
</ParamField>

## Headers

| Nome    | Obrigatório              | Exemplo        | Descrição                      |
| ------- | ------------------------ | -------------- | ------------------------------ |
| `token` | sim (ou `Authorization`) | `a1b2c3d4-...` | TokenAccount ou TokenInstance. |

## Query params

<ParamField query="number" type="string">
  Telefone internacional (`5511999999999`) ou JID (`5511999999999@s.whatsapp.net`, `...@lid`). Se fornecido, retorna apenas este contato.
</ParamField>

## Notas e gotchas

<Note>
  * `found=false` com `push_name` vazio e `redacted_phone` vazio normalmente significa que o número não tem WhatsApp ou nunca trocou mensagens com você.
  * `business_name` só é preenchido para contas WhatsApp Business verificadas.
  * Operações com mais de mil contatos podem demorar alguns segundos por causa do `context.WithTimeout(30s)` aplicado ao `GetAllContacts`.
</Note>

## Respostas de erro

| HTTP | `error.message`                                                                         | Quando ocorre                                 |
| ---- | --------------------------------------------------------------------------------------- | --------------------------------------------- |
| 400  | `Instance name is required`                                                             | `:instance` vazio.                            |
| 401  | `Invalid token`                                                                         | Ver [Autenticação](/pt/guide/authentication). |
| 404  | `Instance not found`                                                                    | Instância não existe na conta.                |
| 500  | `WhatsApp client not found for instance`                                                | Cliente desalocado.                           |
| 500  | `WhatsApp client is not connected`                                                      | Instância desconectada.                       |
| 500  | `contact store not available (use a store that implements ContactStore, e.g. sqlstore)` | Store sem suporte.                            |
| 500  | `invalid number: <...>`                                                                 | `?number=` malformado.                        |
| 500  | `failed to get contacts: <...>` / `failed to get contact: <...>`                        | Erro interno do WhatsMeow.                    |

```json Erro 400 theme={null}
{
  "success": false,
  "error": { "message": "Instance name is required" }
}
```