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

# Contactos

> Busca contactos, verifica numeros de telefono y obtiene fotos de perfil antes de enviar mensajes.

# Contactos

La API de Contactos te permite verificar numeros de telefono en WhatsApp, recuperar informacion de contacto y obtener fotos de perfil. Esto es especialmente util para validar numeros antes de enviar mensajes y enriquecer tus datos de contacto.

Todos los endpoints de contactos estan asociados a una instancia especifica:

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

***

## Verificar si un numero existe

Verifica si un numero de telefono esta registrado en WhatsApp antes de enviar un mensaje. Esto evita entregas fallidas y llamadas a la API innecesarias.

<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(`Number exists on WhatsApp: ${data.chat_id}`);
  } else {
    console.log("Number is not on WhatsApp");
  }
  ```
</CodeGroup>

**Respuesta (el numero existe):**

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

**Respuesta (el numero no existe):**

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

<Tip>
  Usa este endpoint para validar numeros antes de enviar mensajes. Ahorra cuota de mensajes y previene eventos de webhook `message.failed`.
</Tip>

***

## Obtener todos los contactos

Recupera la lista completa de contactos de la cuenta de 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 contacts: ${data.length}`);
  ```
</CodeGroup>

**Respuesta:**

```json theme={null}
{
  "data": [
    {
      "id": "5511999998888@s.whatsapp.net",
      "name": "Maria Silva",
      "short_name": "Maria",
      "push_name": "Mari",
      "is_business": false
    },
    {
      "id": "5511888887777@s.whatsapp.net",
      "name": "Carlos Oliveira",
      "short_name": "Carlos",
      "push_name": "Carlos",
      "is_business": true
    }
  ]
}
```

### Campos de contacto

| Campo         | Descripcion                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------- |
| `id`          | El ID de WhatsApp del contacto (numero de telefono + `@s.whatsapp.net`).                      |
| `name`        | Nombre del contacto guardado en la agenda del telefono. Puede ser `null` si no esta guardado. |
| `short_name`  | Nombre corto de la agenda.                                                                    |
| `push_name`   | El nombre que el contacto ha configurado para si mismo en WhatsApp.                           |
| `is_business` | Si esta es una cuenta de WhatsApp Business.                                                   |

<Note>
  El campo `name` proviene de la agenda de tu telefono. Si el contacto no esta guardado, solo estara disponible `push_name` (configurado por el propio contacto).
</Note>

***

## Obtener informacion de un contacto

Recupera informacion detallada sobre un contacto especifico.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net" \
    -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",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  console.log(`Contact: ${data.push_name || data.name}`);
  ```
</CodeGroup>

**Respuesta:**

```json theme={null}
{
  "data": {
    "id": "5511999998888@s.whatsapp.net",
    "name": "Maria Silva",
    "short_name": "Maria",
    "push_name": "Mari",
    "is_business": false
  }
}
```

***

## Obtener foto de perfil

Recupera la URL de la foto de perfil de WhatsApp de un contacto.

<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(`Profile picture: ${data.profile_picture_url}`);
  } else {
    console.log("No profile picture set");
  }
  ```
</CodeGroup>

**Respuesta:**

```json theme={null}
{
  "data": {
    "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/..."
  }
}
```

<Note>
  Las URLs de fotos de perfil son temporales y expiran despues de un tiempo. No las almacenes de forma permanente -- obtiene una URL nueva cuando la necesites.
</Note>

Si el contacto no tiene foto de perfil o ha restringido la visibilidad en su configuracion de privacidad, `profile_picture_url` sera `null`:

```json theme={null}
{
  "data": {
    "profile_picture_url": null
  }
}
```

***

## Patrones comunes

### Validar antes de enviar

Siempre verifica si un numero existe en WhatsApp antes de enviar un mensaje para evitar fallas innecesarias:

```javascript theme={null}
async function sendMessageSafely(instanceId, phone, text) {
  // Step 1: Check if the number is on 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} is not on WhatsApp, skipping`);
    return null;
  }

  // Step 2: Send the message using the confirmed chat_id
  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();
}
```

### Construir un directorio de contactos

Obtiene todos los contactos y enriquecelos con fotos de perfil:

```javascript theme={null}
async function buildContactDirectory(instanceId) {
  // Get all contacts
  const contactsRes = await fetch(
    `https://api.wappfy.io/api/instances/${instanceId}/contacts`,
    { headers: { "X-Api-Key": "YOUR_API_KEY" } }
  );
  const { data: contacts } = await contactsRes.json();

  // Enrich with profile pictures (batch with delay to avoid rate limits)
  const enriched = [];
  for (const contact of contacts) {
    const picRes = await fetch(
      `https://api.wappfy.io/api/instances/${instanceId}/contacts/${contact.id}/profile-picture`,
      { headers: { "X-Api-Key": "YOUR_API_KEY" } }
    );
    const { data: pic } = await picRes.json();

    enriched.push({
      ...contact,
      profile_picture_url: pic.profile_picture_url,
    });

    // Small delay to respect rate limits
    await new Promise((r) => setTimeout(r, 200));
  }

  return enriched;
}
```

<Warning>
  Al obtener fotos de perfil de muchos contactos, agrega un retraso entre solicitudes para mantenerte dentro de los [limites de tasa](/es/rate-limits). El ejemplo anterior usa un retraso de 200ms.
</Warning>

***

## Referencia de endpoints

| Metodo | Endpoint                                                   | Descripcion                               |
| ------ | ---------------------------------------------------------- | ----------------------------------------- |
| `GET`  | `/api/instances/{id}/contacts`                             | Listar todos los contactos                |
| `GET`  | `/api/instances/{id}/contacts/check?phone={phone}`         | Verificar si un numero existe en WhatsApp |
| `GET`  | `/api/instances/{id}/contacts/{contactId}`                 | Obtener informacion del contacto          |
| `GET`  | `/api/instances/{id}/contacts/{contactId}/profile-picture` | Obtener foto de perfil                    |

***

## Manejo de errores

| Codigo de estado | Descripcion                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| `400`            | Formato de numero de telefono invalido. Usa solo digitos, con codigo de pais (por ejemplo, `5511999998888`). |
| `404`            | Instancia no encontrada o contacto no encontrado.                                                            |
| `429`            | Limite de tasa excedido. Consulta [Limites de tasa](/es/rate-limits).                                        |