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

# Kontak

> Cari kontak, verifikasi nomor telepon, dan ambil foto profil sebelum mengirim pesan.

# Kontak

API Kontak memungkinkan Anda memverifikasi nomor telepon di WhatsApp, mengambil informasi kontak, dan mendapatkan foto profil. Ini sangat berguna untuk memvalidasi nomor sebelum mengirim pesan dan memperkaya data kontak Anda.

Semua endpoint kontak terikat pada instance tertentu:

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

***

## Memeriksa Keberadaan Nomor

Verifikasi apakah nomor telepon terdaftar di WhatsApp sebelum mengirim pesan. Ini mencegah pengiriman gagal dan panggilan API yang sia-sia.

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

**Respons (nomor ada):**

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

**Respons (nomor tidak ada):**

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

<Tip>
  Gunakan endpoint ini untuk memvalidasi nomor sebelum mengirim pesan. Ini menghemat kuota pesan dan mencegah event webhook `message.failed`.
</Tip>

***

## Mendapatkan Semua Kontak

Ambil seluruh daftar kontak untuk akun WhatsApp yang terhubung.

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

**Respons:**

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

### Field Kontak

| Field         | Deskripsi                                                                          |
| ------------- | ---------------------------------------------------------------------------------- |
| `id`          | ID WhatsApp kontak (nomor telepon + `@s.whatsapp.net`).                            |
| `name`        | Nama kontak yang tersimpan di buku alamat ponsel. Bisa `null` jika tidak disimpan. |
| `short_name`  | Nama pendek dari buku alamat.                                                      |
| `push_name`   | Nama yang ditetapkan kontak untuk diri mereka sendiri di WhatsApp.                 |
| `is_business` | Apakah ini adalah akun WhatsApp Business.                                          |

<Note>
  Field `name` berasal dari buku alamat ponsel Anda. Jika kontak tidak disimpan, hanya `push_name` (ditetapkan oleh kontak itu sendiri) yang akan tersedia.
</Note>

***

## Mendapatkan Info Kontak

Ambil informasi detail tentang kontak tertentu.

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

**Respons:**

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

***

## Mendapatkan Foto Profil

Ambil URL foto profil WhatsApp kontak.

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

**Respons:**

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

<Note>
  URL foto profil bersifat sementara dan kedaluwarsa setelah beberapa waktu. Jangan menyimpannya secara permanen -- ambil URL baru saat diperlukan.
</Note>

Jika kontak tidak memiliki foto profil atau telah membatasi visibilitas di pengaturan privasi, `profile_picture_url` akan bernilai `null`:

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

***

## Pola Umum

### Validasi Sebelum Mengirim

Selalu periksa apakah nomor ada di WhatsApp sebelum mengirim pesan untuk menghindari kegagalan yang tidak perlu:

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

### Membangun Direktori Kontak

Ambil semua kontak dan perkaya dengan foto profil:

```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>
  Saat mengambil foto profil untuk banyak kontak, tambahkan jeda antar permintaan agar tetap dalam [batas laju](/id/rate-limits). Contoh di atas menggunakan jeda 200ms.
</Warning>

***

## Referensi Endpoint

| Method | Endpoint                                                   | Deskripsi                              |
| ------ | ---------------------------------------------------------- | -------------------------------------- |
| `GET`  | `/api/instances/{id}/contacts`                             | Melihat daftar semua kontak            |
| `GET`  | `/api/instances/{id}/contacts/check?phone={phone}`         | Memeriksa apakah nomor ada di WhatsApp |
| `GET`  | `/api/instances/{id}/contacts/{contactId}`                 | Mendapatkan info kontak                |
| `GET`  | `/api/instances/{id}/contacts/{contactId}/profile-picture` | Mendapatkan foto profil                |

***

## Penanganan Error

| Kode Status | Deskripsi                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `400`       | Format nomor telepon tidak valid. Gunakan angka saja, dengan kode negara (misalnya, `5511999998888`). |
| `404`       | Instance tidak ditemukan atau kontak tidak ditemukan.                                                 |
| `429`       | Batas laju terlampaui. Lihat [Batas Laju](/id/rate-limits).                                           |