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

# Kontakty

> Wyszukiwanie kontaktow, weryfikacja numerow telefonow i pobieranie zdjec profilowych przed wysylaniem wiadomosci.

# Kontakty

API Kontaktow umozliwia weryfikacje numerow telefonow na WhatsApp, pobieranie informacji o kontaktach i pobieranie zdjec profilowych. Jest to szczegolnie przydatne do walidacji numerow przed wysylaniem wiadomosci i wzbogacania danych kontaktowych.

Wszystkie endpointy kontaktow sa przypisane do konkretnej instancji:

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

***

## Sprawdzanie istnienia numeru

Zweryfikuj, czy numer telefonu jest zarejestrowany na WhatsApp przed wyslaniem wiadomosci. Zapobiega to nieudanym dostarczeniom i zmarnowanym wywolaniom API.

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

**Odpowiedz (numer istnieje):**

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

**Odpowiedz (numer nie istnieje):**

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

<Tip>
  Uzyj tego endpointu do walidacji numerow przed wysylaniem wiadomosci. Oszczedza to limit wiadomosci i zapobiega zdarzeniom webhook `message.failed`.
</Tip>

***

## Pobieranie wszystkich kontaktow

Pobierz pelna liste kontaktow dla polaczonego konta WhatsApp.

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

**Odpowiedz:**

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

### Pola kontaktu

| Pole          | Opis                                                                                            |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `id`          | Identyfikator WhatsApp kontaktu (numer telefonu + `@s.whatsapp.net`).                           |
| `name`        | Nazwa kontaktu zapisana w ksiazce adresowej telefonu. Moze byc `null`, jesli nie jest zapisany. |
| `short_name`  | Krotka nazwa z ksiazki adresowej.                                                               |
| `push_name`   | Nazwa, ktora kontakt sam ustawil na WhatsApp.                                                   |
| `is_business` | Czy jest to konto WhatsApp Business.                                                            |

<Note>
  Pole `name` pochodzi z ksiazki adresowej Twojego telefonu. Jesli kontakt nie jest zapisany, dostepna bedzie tylko wartosc `push_name` (ustawiona przez samego kontaktu).
</Note>

***

## Informacje o kontakcie

Pobierz szczegolowe informacje o konkretnym kontakcie.

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

**Odpowiedz:**

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

***

## Zdjecie profilowe

Pobierz URL zdjecia profilowego WhatsApp kontaktu.

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

**Odpowiedz:**

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

<Note>
  Adresy URL zdjec profilowych sa tymczasowe i wygasaja po pewnym czasie. Nie przechowuj ich na stale — pobieraj swiezy URL, gdy jest potrzebny.
</Note>

Jesli kontakt nie ma zdjecia profilowego lub ograniczyl widocznosc w ustawieniach prywatnosci, `profile_picture_url` bedzie rowne `null`:

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

***

## Typowe wzorce

### Walidacja przed wyslaniem

Zawsze sprawdzaj, czy numer istnieje na WhatsApp przed wyslaniem wiadomosci, aby uniknac niepotrzebnych niepowodzen:

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

### Budowanie katalogu kontaktow

Pobierz wszystkie kontakty i wzbogac je o zdjecia profilowe:

```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>
  Przy pobieraniu zdjec profilowych dla wielu kontaktow dodaj opoznienie miedzy zapytaniami, aby nie przekroczyc [limitow zapytan](/pl/rate-limits). Powyzszy przyklad uzywa opoznienia 200ms.
</Warning>

***

## Informacje o endpointach

| Metoda | Endpoint                                                   | Opis                                    |
| ------ | ---------------------------------------------------------- | --------------------------------------- |
| `GET`  | `/api/instances/{id}/contacts`                             | Lista wszystkich kontaktow              |
| `GET`  | `/api/instances/{id}/contacts/check?phone={phone}`         | Sprawdz, czy numer istnieje na WhatsApp |
| `GET`  | `/api/instances/{id}/contacts/{contactId}`                 | Informacje o kontakcie                  |
| `GET`  | `/api/instances/{id}/contacts/{contactId}/profile-picture` | Zdjecie profilowe                       |

***

## Obsluga bledow

| Kod statusu | Opis                                                                                         |
| ----------- | -------------------------------------------------------------------------------------------- |
| `400`       | Nieprawidlowy format numeru telefonu. Uzyj samych cyfr, z kodem kraju (np. `5511999998888`). |
| `404`       | Instancja nie znaleziona lub kontakt nie znaleziony.                                         |
| `429`       | Przekroczono limit zapytan. Zobacz [Limity zapytan](/pl/rate-limits).                        |