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.

curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/check?phone=5511999998888" \
  -H "X-Api-Key: YOUR_API_KEY"

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");
}

Odpowiedz (numer istnieje):

{
  "data": {
    "exists": true,
    "phone": "5511999998888",
    "chat_id": "5511999998888@s.whatsapp.net"
  }
}

Odpowiedz (numer nie istnieje):

{
  "data": {
    "exists": false,
    "phone": "5511999998888",
    "chat_id": null
  }
}

Uzyj tego endpointu do walidacji numerow przed wysylaniem wiadomosci. Oszczedza to limit wiadomosci i zapobiega zdarzeniom webhook message.failed.

Pobieranie wszystkich kontaktow

Pobierz pelna liste kontaktow dla polaczonego konta WhatsApp.

curl https://api.wappfy.io/api/instances/inst_abc123/contacts \
  -H "X-Api-Key: YOUR_API_KEY"

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

Odpowiedz:

{
  "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.

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

Informacje o kontakcie

Pobierz szczegolowe informacje o konkretnym kontakcie.

curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Odpowiedz:

{
  "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.

curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net/profile-picture" \
  -H "X-Api-Key: YOUR_API_KEY"

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");
}

Odpowiedz:

{
  "data": {
    "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/..."
  }
}

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

Jesli kontakt nie ma zdjecia profilowego lub ograniczyl widocznosc w ustawieniach prywatnosci, profile_picture_url bedzie rowne 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:

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:

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

Przy pobieraniu zdjec profilowych dla wielu kontaktow dodaj opoznienie miedzy zapytaniami, aby nie przekroczyc limitow zapytan. Powyzszy przyklad uzywa opoznienia 200ms.

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.

Pierwsze Kroki

Przewodniki

Kontakty

Kontakty

Sprawdzanie istnienia numeru

Pobieranie wszystkich kontaktow

Pola kontaktu

Informacje o kontakcie

Zdjecie profilowe

Typowe wzorce

Walidacja przed wyslaniem

Budowanie katalogu kontaktow

Informacje o endpointach

Obsluga bledow

​Kontakty

​Sprawdzanie istnienia numeru

​Pobieranie wszystkich kontaktow

​Pola kontaktu

​Informacje o kontakcie

​Zdjecie profilowe

​Typowe wzorce

​Walidacja przed wyslaniem

​Budowanie katalogu kontaktow

​Informacje o endpointach

​Obsluga bledow

Kontakty

Sprawdzanie istnienia numeru

Pobieranie wszystkich kontaktow

Pola kontaktu

Informacje o kontakcie

Zdjecie profilowe

Typowe wzorce

Walidacja przed wyslaniem

Budowanie katalogu kontaktow

Informacje o endpointach

Obsluga bledow