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.

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

Respons (nomor ada):

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

Respons (nomor tidak ada):

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

Gunakan endpoint ini untuk memvalidasi nomor sebelum mengirim pesan. Ini menghemat kuota pesan dan mencegah event webhook message.failed.

Mendapatkan Semua Kontak

Ambil seluruh daftar kontak untuk akun WhatsApp yang terhubung.

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

Respons:

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

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

Mendapatkan Info Kontak

Ambil informasi detail tentang kontak tertentu.

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

Respons:

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

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

Respons:

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

URL foto profil bersifat sementara dan kedaluwarsa setelah beberapa waktu. Jangan menyimpannya secara permanen — ambil URL baru saat diperlukan.

Jika kontak tidak memiliki foto profil atau telah membatasi visibilitas di pengaturan privasi, profile_picture_url akan bernilai 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:

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:

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

Saat mengambil foto profil untuk banyak kontak, tambahkan jeda antar permintaan agar tetap dalam batas laju. Contoh di atas menggunakan jeda 200ms.

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.

Memulai

Panduan

Kontak

Kontak

Memeriksa Keberadaan Nomor

Mendapatkan Semua Kontak

Field Kontak

Mendapatkan Info Kontak

Mendapatkan Foto Profil

Pola Umum

Validasi Sebelum Mengirim

Membangun Direktori Kontak

Referensi Endpoint

Penanganan Error

​Kontak

​Memeriksa Keberadaan Nomor

​Mendapatkan Semua Kontak

​Field Kontak

​Mendapatkan Info Kontak

​Mendapatkan Foto Profil

​Pola Umum

​Validasi Sebelum Mengirim

​Membangun Direktori Kontak

​Referensi Endpoint

​Penanganan Error

Kontak

Memeriksa Keberadaan Nomor

Mendapatkan Semua Kontak

Field Kontak

Mendapatkan Info Kontak

Mendapatkan Foto Profil

Pola Umum

Validasi Sebelum Mengirim

Membangun Direktori Kontak

Referensi Endpoint

Penanganan Error