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

# Contacts

> Recherchez des contacts, verifiez des numeros de telephone et recuperez les photos de profil avant d'envoyer des messages.

# Contacts

L'API Contacts vous permet de verifier les numeros de telephone sur WhatsApp, de recuperer les informations de contact et d'obtenir les photos de profil. C'est particulierement utile pour valider les numeros avant d'envoyer des messages et pour enrichir vos donnees de contact.

Tous les endpoints de contacts sont limites a une instance specifique :

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

***

## Verifier si un numero existe

Verifiez si un numero de telephone est enregistre sur WhatsApp avant d'envoyer un message. Cela evite les echecs de livraison et les appels API inutiles.

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

**Reponse (le numero existe) :**

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

**Reponse (le numero n'existe pas) :**

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

<Tip>
  Utilisez cet endpoint pour valider les numeros avant d'envoyer des messages. Cela economise le quota de messages et evite les evenements webhook `message.failed`.
</Tip>

***

## Obtenir tous les contacts

Recuperez la liste complete des contacts du compte WhatsApp connecte.

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

**Reponse :**

```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
    }
  ]
}
```

### Champs du contact

| Champ         | Description                                                                                           |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| `id`          | L'identifiant WhatsApp du contact (numero de telephone + `@s.whatsapp.net`).                          |
| `name`        | Nom du contact tel qu'enregistre dans le repertoire du telephone. Peut etre `null` si non enregistre. |
| `short_name`  | Nom court du repertoire.                                                                              |
| `push_name`   | Le nom que le contact a defini pour lui-meme sur WhatsApp.                                            |
| `is_business` | Indique s'il s'agit d'un compte WhatsApp Business.                                                    |

<Note>
  Le champ `name` provient du repertoire de votre telephone. Si le contact n'est pas enregistre, seul `push_name` (defini par le contact lui-meme) sera disponible.
</Note>

***

## Obtenir les informations d'un contact

Recuperez les informations detaillees d'un contact specifique.

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

**Reponse :**

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

***

## Obtenir la photo de profil

Recuperez l'URL de la photo de profil WhatsApp d'un contact.

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

**Reponse :**

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

<Note>
  Les URL des photos de profil sont temporaires et expirent apres un certain temps. Ne les stockez pas de maniere permanente -- recuperez une URL fraiche lorsque necessaire.
</Note>

Si le contact n'a pas de photo de profil ou a restreint la visibilite dans ses parametres de confidentialite, `profile_picture_url` sera `null` :

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

***

## Schemas courants

### Valider avant d'envoyer

Verifiez toujours si un numero existe sur WhatsApp avant d'envoyer un message pour eviter les echecs inutiles :

```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();
}
```

### Construire un repertoire de contacts

Recuperez tous les contacts et enrichissez-les avec les photos de profil :

```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>
  Lors de la recuperation des photos de profil pour de nombreux contacts, ajoutez un delai entre les requetes pour rester dans les [limites de debit](/fr/rate-limits). L'exemple ci-dessus utilise un delai de 200 ms.
</Warning>

***

## Reference des endpoints

| Methode | Endpoint                                                   | Description                               |
| ------- | ---------------------------------------------------------- | ----------------------------------------- |
| `GET`   | `/api/instances/{id}/contacts`                             | Lister tous les contacts                  |
| `GET`   | `/api/instances/{id}/contacts/check?phone={phone}`         | Verifier si un numero existe sur WhatsApp |
| `GET`   | `/api/instances/{id}/contacts/{contactId}`                 | Obtenir les infos d'un contact            |
| `GET`   | `/api/instances/{id}/contacts/{contactId}/profile-picture` | Obtenir la photo de profil                |

***

## Gestion des erreurs

| Code de statut | Description                                                                                                                 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `400`          | Format de numero de telephone invalide. Utilisez uniquement des chiffres, avec l'indicatif pays (par ex., `5511999998888`). |
| `404`          | Instance ou contact non trouve.                                                                                             |
| `429`          | Limite de debit depassee. Voir [Limites de debit](/fr/rate-limits).                                                         |