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

# Kişiler

> Mesaj göndermeden önce kişileri arayın, telefon numaralarını doğrulayın ve profil resimlerini alın.

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

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

**Yan\u0131t (numara mevcut):**

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

**Yan\u0131t (numara mevcut de\u011fil):**

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

<Tip>
  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.
</Tip>

***

## T\u00fcm Ki\u015fileri Alma

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

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

**Yan\u0131t:**

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

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

<Note>
  `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.
</Note>

***

## Ki\u015fi Bilgisi Alma

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

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

**Yan\u0131t:**

```json theme={null}
{
  "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.

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

**Yan\u0131t:**

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

<Note>
  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.
</Note>

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:

```json theme={null}
{
  "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:

```javascript theme={null}
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:

```javascript theme={null}
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;
}
```

<Warning>
  \u00c7ok say\u0131da ki\u015fi i\u00e7in profil resimleri al\u0131rken, [h\u0131z s\u0131n\u0131rlar\u0131](/tr/rate-limits) i\u00e7inde kalmak i\u00e7in istekler aras\u0131na gecikme ekleyin. Yukar\u0131daki \u00f6rnekte 200ms gecikme kullan\u0131lm\u0131\u015ft\u0131r.
</Warning>

***

## 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](/tr/rate-limits) sayfas\u0131na bak\u0131n.    |