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

# Kontakte

> Kontakte nachschlagen, Telefonnummern verifizieren und Profilbilder abrufen, bevor Sie Nachrichten senden.

# Kontakte

Die Kontakte-API ermoeglicht es Ihnen, Telefonnummern auf WhatsApp zu verifizieren, Kontaktinformationen abzurufen und Profilbilder zu laden. Dies ist besonders nuetzlich, um Nummern vor dem Senden von Nachrichten zu validieren und Ihre Kontaktdaten anzureichern.

Alle Kontakt-Endpunkte beziehen sich auf eine bestimmte Instanz:

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

***

## Pruefen, ob eine Nummer existiert

Ueberpruefen Sie, ob eine Telefonnummer auf WhatsApp registriert ist, bevor Sie eine Nachricht senden. Dies verhindert fehlgeschlagene Zustellungen und unnoetige API-Aufrufe.

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

**Antwort (Nummer existiert):**

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

**Antwort (Nummer existiert nicht):**

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

<Tip>
  Verwenden Sie diesen Endpunkt, um Nummern vor dem Senden von Nachrichten zu validieren. Das spart Nachrichtenkontingent und verhindert `message.failed`-Webhook-Ereignisse.
</Tip>

***

## Alle Kontakte abrufen

Rufen Sie die vollstaendige Kontaktliste des verbundenen WhatsApp-Kontos ab.

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

**Antwort:**

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

### Kontaktfelder

| Feld          | Beschreibung                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------- |
| `id`          | Die WhatsApp-ID des Kontakts (Telefonnummer + `@s.whatsapp.net`).                                 |
| `name`        | Kontaktname wie im Adressbuch des Telefons gespeichert. Kann `null` sein, wenn nicht gespeichert. |
| `short_name`  | Kurzname aus dem Adressbuch.                                                                      |
| `push_name`   | Der Name, den der Kontakt fuer sich selbst auf WhatsApp festgelegt hat.                           |
| `is_business` | Ob es sich um ein WhatsApp-Business-Konto handelt.                                                |

<Note>
  Das Feld `name` stammt aus dem Adressbuch Ihres Telefons. Wenn der Kontakt nicht gespeichert ist, ist nur `push_name` (vom Kontakt selbst festgelegt) verfuegbar.
</Note>

***

## Kontaktinformationen abrufen

Rufen Sie detaillierte Informationen zu einem bestimmten Kontakt ab.

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

**Antwort:**

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

***

## Profilbild abrufen

Rufen Sie die WhatsApp-Profilbild-URL eines Kontakts ab.

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

**Antwort:**

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

<Note>
  Profilbild-URLs sind temporaer und laufen nach einiger Zeit ab. Speichern Sie sie nicht dauerhaft -- rufen Sie bei Bedarf eine aktuelle URL ab.
</Note>

Wenn der Kontakt kein Profilbild hat oder die Sichtbarkeit in seinen Datenschutzeinstellungen eingeschraenkt hat, ist `profile_picture_url` `null`:

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

***

## Haeufige Muster

### Vor dem Senden validieren

Pruefen Sie immer, ob eine Nummer auf WhatsApp existiert, bevor Sie eine Nachricht senden, um unnoetige Fehler zu vermeiden:

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

### Kontaktverzeichnis erstellen

Rufen Sie alle Kontakte ab und reichern Sie sie mit Profilbildern an:

```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>
  Wenn Sie Profilbilder fuer viele Kontakte abrufen, fuegen Sie eine Verzoegerung zwischen den Anfragen hinzu, um innerhalb der [Ratenlimits](/de/rate-limits) zu bleiben. Das obige Beispiel verwendet eine Verzoegerung von 200ms.
</Warning>

***

## Endpunkt-Referenz

| Methode | Endpunkt                                                   | Beschreibung                                   |
| ------- | ---------------------------------------------------------- | ---------------------------------------------- |
| `GET`   | `/api/instances/{id}/contacts`                             | Alle Kontakte auflisten                        |
| `GET`   | `/api/instances/{id}/contacts/check?phone={phone}`         | Pruefen, ob eine Nummer auf WhatsApp existiert |
| `GET`   | `/api/instances/{id}/contacts/{contactId}`                 | Kontaktinformationen abrufen                   |
| `GET`   | `/api/instances/{id}/contacts/{contactId}/profile-picture` | Profilbild abrufen                             |

***

## Fehlerbehandlung

| Statuscode | Beschreibung                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------ |
| `400`      | Ungueltiges Telefonnummernformat. Verwenden Sie nur Ziffern mit Laendervorwahl (z.B. `5511999998888`). |
| `404`      | Instanz nicht gefunden oder Kontakt nicht gefunden.                                                    |
| `429`      | Ratenlimit ueberschritten. Siehe [Ratenlimits](/de/rate-limits).                                       |