Ki\u015filer

Ki\u015filer API’si, telefon numaralar\u0131n\u0131 WhatsApp \u00fczerinde do\u011frulaman\u0131za, ki\u015fi bilgilerini alman\u0131za ve profil resimlerini getirmenize olanak tan\u0131r. Mesaj g\u00f6ndermeden \u00f6nce numaralar\u0131 do\u011frulamak ve ki\u015fi verilerinizi zenginle\u015ftirmek i\u00e7in \u00f6zellikle kullan\u0131\u015fl\u0131d\u0131r. T\u00fcm ki\u015fi ucu noktalar\u0131 belirli bir \u00f6rnekle s\u0131n\u0131rl\u0131d\u0131r:

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

Numara Varl\u0131\u011f\u0131n\u0131 Kontrol Etme

Mesaj g\u00f6ndermeden \u00f6nce bir telefon numaras\u0131n\u0131n WhatsApp’a kay\u0131tl\u0131 olup olmad\u0131\u011f\u0131n\u0131 do\u011frulay\u0131n. Bu, ba\u015far\u0131s\u0131z teslimatlar\u0131 ve gereksiz API \u00e7a\u011fr\u0131lar\u0131n\u0131 \u00f6nler.

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

Yan\u0131t (numara mevcut):

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

Yan\u0131t (numara mevcut de\u011fil):

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

Mesaj g\u00f6ndermeden \u00f6nce numaralar\u0131 do\u011frulamak i\u00e7in bu ucu noktas\u0131n\u0131 kullan\u0131n. Mesaj kotas\u0131ndan tasarruf sa\u011flar ve message.failed webhook olaylar\u0131n\u0131 \u00f6nler.

T\u00fcm Ki\u015fileri Alma

Ba\u011fl\u0131 WhatsApp hesab\u0131n\u0131n tam ki\u015fi listesini al\u0131n.

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

Yan\u0131t:

{
  "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
    }
  ]
}

Ki\u015fi Alanlar\u0131

Alan	A\u00e7\u0131klama
`id`	Ki\u015finin WhatsApp kimli\u011fi (telefon numaras\u0131 + `@s.whatsapp.net`).
`name`	Telefonun rehberinde kay\u0131tl\u0131 ki\u015fi ad\u0131. Kay\u0131tl\u0131 de\u011filse `null` olabilir.
`short_name`	Rehberdeki k\u0131sa ad.
`push_name`	Ki\u015finin WhatsApp’ta kendisi i\u00e7in belirledi\u011fi ad.
`is_business`	Bunun bir WhatsApp Business hesab\u0131 olup olmad\u0131\u011f\u0131.

name alan\u0131 telefonunuzun rehberinden gelir. Ki\u015fi kay\u0131tl\u0131 de\u011filse yaln\u0131zca push_name (ki\u015finin kendisi taraf\u0131ndan belirlenen) kullan\u0131labilir olacakt\u0131r.

Ki\u015fi Bilgisi Alma

Belirli bir ki\u015fi hakk\u0131nda ayr\u0131nt\u0131l\u0131 bilgi al\u0131n.

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

Yan\u0131t:

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

Profil Resmi Alma

Bir ki\u015finin WhatsApp profil resmi URL’sini al\u0131n.

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

Yan\u0131t:

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

Profil resmi URL’leri ge\u00e7icidir ve bir s\u00fcre sonra s\u00fcresi dolar. Kal\u0131c\u0131 olarak saklamay\u0131n — ihtiyac\u0131n\u0131z oldu\u011funda yeni bir URL al\u0131n.

Ki\u015finin profil resmi yoksa veya gizlilik ayarlar\u0131nda g\u00f6r\u00fcn\u00fcrl\u00fc\u011f\u00fc k\u0131s\u0131tlanm\u0131\u015fsa, profile_picture_url de\u011feri null olacakt\u0131r:

{
  "data": {
    "profile_picture_url": null
  }
}

Yayg\u0131n Kullan\u0131m Desenleri

G\u00f6ndermeden \u00d6nce Do\u011frulama

Gereksiz ba\u015far\u0131s\u0131zl\u0131klar\u0131 \u00f6nlemek i\u00e7in mesaj g\u00f6ndermeden \u00f6nce numaran\u0131n WhatsApp’ta olup olmad\u0131\u011f\u0131n\u0131 her zaman kontrol edin:

async function sendMessageSafely(instanceId, phone, text) {
  // Ad\u0131m 1: Numaran\u0131n WhatsApp'ta olup olmad\u0131\u011f\u0131n\u0131 kontrol edin
  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;
  }

  // Ad\u0131m 2: Onaylanan chat_id ile mesaj g\u00f6nderin
  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();
}

Ki\u015fi Rehberi Olu\u015fturma

T\u00fcm ki\u015fileri al\u0131n ve profil resimleriyle zenginle\u015ftirin:

async function buildContactDirectory(instanceId) {
  // T\u00fcm ki\u015fileri al\u0131n
  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();

  // Profil resimleriyle zenginle\u015ftirin (h\u0131z s\u0131n\u0131r\u0131na dikkat ederek gecikmeli toplu i\u015flem)
  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,
    });

    // H\u0131z s\u0131n\u0131rlar\u0131na uymak i\u00e7in k\u00fc\u00e7\u00fck gecikme
    await new Promise((r) => setTimeout(r, 200));
  }

  return enriched;
}

\u00c7ok say\u0131da ki\u015fi i\u00e7in profil resimleri al\u0131rken, h\u0131z s\u0131n\u0131rlar\u0131 i\u00e7inde kalmak i\u00e7in istekler aras\u0131na gecikme ekleyin. Yukar\u0131daki \u00f6rnekte 200ms gecikme kullan\u0131lm\u0131\u015ft\u0131r.

Ucu Noktas\u0131 Referans\u0131

Y\u00f6ntem	Ucu Noktas\u0131	A\u00e7\u0131klama
`GET`	`/api/instances/{id}/contacts`	T\u00fcm ki\u015fileri listele
`GET`	`/api/instances/{id}/contacts/check?phone={phone}`	Numaran\u0131n WhatsApp’ta olup olmad\u0131\u011f\u0131n\u0131 kontrol et
`GET`	`/api/instances/{id}/contacts/{contactId}`	Ki\u015fi bilgisi al
`GET`	`/api/instances/{id}/contacts/{contactId}/profile-picture`	Profil resmi al

Hata Y\u00f6netimi

Durum Kodu	A\u00e7\u0131klama
`400`	Ge\u00e7ersiz telefon numaras\u0131 format\u0131. Yaln\u0131zca rakam kullan\u0131n, \u00fclke kodu ile birlikte (orn. `5511999998888`).
`404`	\u00d6rnek bulunamad\u0131 veya ki\u015fi bulunamad\u0131.
`429`	H\u0131z s\u0131n\u0131r\u0131 a\u015f\u0131ld\u0131. H\u0131z S\u0131n\u0131rlar\u0131 sayfas\u0131na bak\u0131n.

Başlangıç

Kılavuzlar

Kişiler

Ki\u015filer

Numara Varl\u0131\u011f\u0131n\u0131 Kontrol Etme

T\u00fcm Ki\u015fileri Alma

Ki\u015fi Alanlar\u0131

Ki\u015fi Bilgisi Alma

Profil Resmi Alma

Yayg\u0131n Kullan\u0131m Desenleri

G\u00f6ndermeden \u00d6nce Do\u011frulama

Ki\u015fi Rehberi Olu\u015fturma

Ucu Noktas\u0131 Referans\u0131

Hata Y\u00f6netimi

​Ki\u015filer

​Numara Varl\u0131\u011f\u0131n\u0131 Kontrol Etme

​T\u00fcm Ki\u015fileri Alma

​Ki\u015fi Alanlar\u0131

​Ki\u015fi Bilgisi Alma

​Profil Resmi Alma

​Yayg\u0131n Kullan\u0131m Desenleri

​G\u00f6ndermeden \u00d6nce Do\u011frulama

​Ki\u015fi Rehberi Olu\u015fturma

​Ucu Noktas\u0131 Referans\u0131

​Hata Y\u00f6netimi

Ki\u015filer

Numara Varl\u0131\u011f\u0131n\u0131 Kontrol Etme

T\u00fcm Ki\u015fileri Alma

Ki\u015fi Alanlar\u0131

Ki\u015fi Bilgisi Alma

Profil Resmi Alma

Yayg\u0131n Kullan\u0131m Desenleri

G\u00f6ndermeden \u00d6nce Do\u011frulama

Ki\u015fi Rehberi Olu\u015fturma

Ucu Noktas\u0131 Referans\u0131

Hata Y\u00f6netimi