> ## 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 contactos

> Lista todos los contactos sincronizados o consulta un número específico

**Auth:** `TokenAccount` o `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** sí

## Descripción

Devuelve la lista de contactos sincronizados en el `ContactStore` de WhatsMeow, son los contactos provenientes de la agenda del teléfono principal: nombre, push name, nombre comercial y número telefónico parcialmente oculto.

Si se proporciona `?number=`, devuelve un solo contacto. Si el número no está en la agenda, la respuesta sigue siendo `200 OK` con `contact.found = false`.

<Info>
  Operación de **solo lectura** contra el store local, no genera tráfico de WhatsApp.
</Info>

## Ejemplos

### Listar todos

Sin parámetros de query, devuelve todos los contactos sincronizados en el `ContactStore` local de la instancia, con `total` indicando el tamaño de la 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` (teléfono internacional). Devuelve el objeto `contact` único, con `found=false` cuando el número no está en la 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

Acepta el JID completo en `?number=5511999999999@s.whatsapp.net` cuando ya tienes el identificador completo (de un webhook u otra respuesta de la API), evitando construir manualmente el sufijo.

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

## Respuesta exitosa

Sin `?number`, devuelve `contacts` (array) con todos los contactos sincronizados de la agenda + `total`. Con `?number=...`, devuelve solo `contact` (un único objeto). Cada item lleva `jid`, `lid` (cuando aplica), los nombres disponibles (`first_name`, `full_name`, `push_name`, `business_name`) y `redacted_phone` para casos donde solo conocemos el LID. El campo `found` indica si la entrada provino del store.

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

## Parámetros de ruta

<ParamField path="instance" type="string" required>
  Nombre de la instancia (por ejemplo, `$Instance_Name`).
</ParamField>

## Cabeceras

| Nombre  | Requerido              | Ejemplo        | Descripción                   |
| ------- | ---------------------- | -------------- | ----------------------------- |
| `token` | sí (o `Authorization`) | `a1b2c3d4-...` | TokenAccount o TokenInstance. |

## Parámetros de consulta

<ParamField query="number" type="string">
  Teléfono internacional (`5511999999999`) o JID (`5511999999999@s.whatsapp.net`, `...@lid`). Si se proporciona, devuelve solo este contacto.
</ParamField>

## Notas y precauciones

<Note>
  * `found=false` con `push_name` vacío y `redacted_phone` vacío usualmente significa que el número no tiene WhatsApp o nunca intercambió mensajes contigo.
  * `business_name` solo se llena para cuentas verificadas de WhatsApp Business.
  * Las operaciones que involucran más de mil contactos pueden tardar algunos segundos por el `context.WithTimeout(30s)` aplicado a `GetAllContacts`.
</Note>

## Respuestas de error

| HTTP | `error.message`                                                                         | Cuándo ocurre                                  |
| ---- | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
| 400  | `Instance name is required`                                                             | `:instance` vacío.                             |
| 401  | `Invalid token`                                                                         | Ver [Autenticación](/es/guide/authentication). |
| 404  | `Instance not found`                                                                    | La instancia no existe en la cuenta.           |
| 500  | `WhatsApp client not found for instance`                                                | Cliente desasignado.                           |
| 500  | `WhatsApp client is not connected`                                                      | Instancia desconectada.                        |
| 500  | `contact store not available (use a store that implements ContactStore, e.g. sqlstore)` | Store no soportado.                            |
| 500  | `invalid number: <...>`                                                                 | `?number=` malformado.                         |
| 500  | `failed to get contacts: <...>` / `failed to get contact: <...>`                        | Error interno de WhatsMeow.                    |

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