Cek Nomor WhatsApp Aktif via API Sebelum Mengirim Pesan

Mengirim pesan ke nomor yang tidak terdaftar di WhatsApp membuang waktu, membuat log dipenuhi kegagalan, dan memberi pola pengiriman yang buruk. Masalahnya sering sederhana: nomor salah ketik, nomor lama sudah tidak aktif, atau daftar kontak hasil impor tidak pernah dibersihkan.

LoginWA menyediakan endpoint khusus untuk memeriksanya sebelum pesan dikirim:

POST /api/v1/numbers/check

Endpoint ini memeriksa hingga 20 nomor dalam satu request dan tidak memakai kuota pesan. Artikel ini menjelaskan format respons, contoh Node.js dan PHP, cara membersihkan daftar kontak, serta batas yang perlu dipahami agar hasil cek tidak disalahartikan.

Apa Arti “Nomor WhatsApp Aktif” di Endpoint Ini?

Hasil registered: true berarti nomor tersebut terdaftar sebagai akun WhatsApp dan LoginWA mengembalikan JID-nya. Hasil registered: false berarti nomor tidak ditemukan sebagai akun WhatsApp pada saat pemeriksaan.

Hasil itu tidak berarti:

• pemilik nomor bersedia menerima promosi;
• nomor sedang online;
• pesan pasti dibaca;
• nomor tidak akan pernah dibatasi WhatsApp;
• pemilik nomor adalah orang yang sama dengan data di CRM.

Pisahkan tiga hal ini dalam sistem: terdaftar, boleh dihubungi, dan berhasil menerima pesan. Cek nomor hanya menjawab hal pertama.

Format Request

Kirim array phones berisi nomor dengan kode negara. Untuk Indonesia, gunakan format yang dimulai dengan 62, bukan 08.

curl -X POST https://api.loginwa.com/api/v1/numbers/check \
  -H "Authorization: Bearer $LOGINWA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": [
      "6281234567890",
      "6289876543210"
    ]
  }'

Responsnya sejajar dengan urutan nomor yang dikirim:

{
  "device_id": "dev_abc123",
  "results": [
    {
      "phone": "6281234567890",
      "registered": true,
      "jid": "[email protected]"
    },
    {
      "phone": "6289876543210",
      "registered": false,
      "jid": null
    }
  ]
}

Setiap request dapat berisi maksimal 20 nomor. Jika daftar lebih besar, pecah menjadi beberapa batch dan beri jeda wajar antar-request.

Contoh Node.js

Contoh berikut membaca daftar nomor, memecahnya menjadi kelompok 20, lalu memisahkan nomor terdaftar dan tidak terdaftar.

const API_KEY = process.env.LOGINWA_API_KEY;

function chunk(items, size) {
  const result = [];
  for (let i = 0; i < items.length; i += size) {
    result.push(items.slice(i, i + size));
  }
  return result;
}

async function checkNumbers(phones) {
  const checked = [];

  for (const phonesBatch of chunk(phones, 20)) {
    const response = await fetch(
      "https://api.loginwa.com/api/v1/numbers/check",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ phones: phonesBatch }),
      },
    );

    if (!response.ok) {
      throw new Error(`Number check failed: HTTP ${response.status}`);
    }

    const data = await response.json();
    checked.push(...data.results);
  }

  return checked;
}

const results = await checkNumbers([
  "6281234567890",
  "6289876543210",
]);

const registered = results.filter((item) => item.registered);
const unregistered = results.filter((item) => !item.registered);

console.log({ registered, unregistered });

Simpan API key di server atau environment variable. Jangan menaruhnya di aplikasi browser atau mobile karena siapa pun yang mengambil key tersebut dapat memakai kuota akun.

Contoh PHP

Pola yang sama dapat ditulis dengan cURL:

<?php

function checkWhatsAppNumbers(array $phones): array
{
    $apiKey = getenv('LOGINWA_API_KEY');
    $results = [];

    foreach (array_chunk($phones, 20) as $batch) {
        $ch = curl_init('https://api.loginwa.com/api/v1/numbers/check');

        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $apiKey,
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode(['phones' => $batch]),
        ]);

        $body = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        curl_close($ch);

        if ($status < 200 || $status >= 300) {
            throw new RuntimeException("Number check failed: HTTP {$status}");
        }

        $decoded = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
        $results = [...$results, ...$decoded['results']];
    }

    return $results;
}

Di Laravel, tempatkan pemanggilan ini di job antrean bila daftar kontak besar. Jangan membuat checkout atau halaman admin menunggu ratusan batch selesai.

Normalisasi Nomor Sebelum Dicek

Banyak hasil palsu berasal dari format, bukan status WhatsApp. Bersihkan nomor dengan aturan konsisten:

1. Hapus spasi, tanda hubung, titik, dan tanda kurung.
2. Ubah awalan 0 Indonesia menjadi 62 hanya jika nomor memang nomor Indonesia.
3. Hapus tanda + untuk payload API.
4. Tolak nilai yang terlalu pendek, mengandung huruf, atau tidak memiliki kode negara.
5. Hilangkan duplikat sebelum dikirim ke API.

Jangan menebak kode negara untuk semua nomor. Nomor dari negara lain harus membawa kode negaranya sendiri. Jika sumber data tidak menyimpannya, tandai sebagai data tidak lengkap dan minta pengguna memperbaikinya.

Cara Menggunakan Hasilnya

Hasil pemeriksaan sebaiknya disimpan sebagai status dengan waktu pemeriksaan, misalnya:

Jangan langsung menghapus nomor yang tidak terdaftar. Tandai dulu sebagai unregistered, keluarkan dari antrean kirim, dan beri kesempatan untuk dikoreksi. Nomor dapat berubah kepemilikan atau didaftarkan kembali.

Untuk kampanye, jalankan pemeriksaan sebelum daftar masuk ke antrean broadcast. Itu mengurangi kiriman pasti gagal dan membuat laporan kampanye lebih bersih. Alur broadcast dari file kontak dibahas di tutorial broadcast WhatsApp dari CSV.

Cek Nomor Tidak Menggantikan Opt-In

Nomor terdaftar bukan izin pemasaran. Daftar hasil pembelian, scraping, atau impor lama tetap berisiko menghasilkan laporan spam. Pemeriksaan nomor hanya memastikan tujuan teknisnya ada.

Untuk pengiriman promosi:

• gunakan daftar yang memang memberikan persetujuan;
• sediakan cara berhenti menerima pesan;
• jangan mengirim ulang terus-menerus ke nomor yang gagal;
• beri jeda antar-pesan;
• mulai dari volume kecil saat nomor pengirim masih baru.

Praktik pengiriman yang lebih aman dibahas di panduan WhatsApp blast tanpa banned. Ingat istilahnya: praktik tersebut meminimalkan risiko, bukan menjamin nomor tidak akan dibatasi.

Kapan Harus Mengecek Ulang?

Nomor yang hari ini terdaftar dapat berhenti dipakai. Sebaliknya, nomor yang belum terdaftar dapat aktif kemudian. Frekuensi cek ulang tergantung jenis data:

• Saat pendaftaran: cek segera untuk memberi umpan balik pada pengguna.
• Sebelum impor kampanye: cek daftar baru sebelum masuk antrean.
• Kontak lama: cek ulang secara berkala atau sebelum kampanye besar.
• Setelah gagal kirim berulang: tandai dan cek ulang sebelum mencoba lagi.

Jangan menjalankan cek pada setiap pesan transaksional jika hasil terakhir masih baru. Simpan hasil dan waktu pemeriksaan agar API tidak dipanggil tanpa perlu.

Biaya dan Batasnya

Menurut dokumentasi saat artikel ini diterbitkan, pemeriksaan nomor tidak mengurangi kuota pesan. Batasnya adalah 20 nomor per request. Karena harga dan batas produk dapat berubah, cek dokumentasi API dan halaman harga untuk ketentuan terbaru.

Gunakan endpoint dari server dengan API key app yang benar. Jika aplikasi belum memiliki device online atau API key tidak valid, tangani respons error secara eksplisit dan jangan menganggap semua nomor otomatis tidak terdaftar. Kegagalan pemeriksaan berbeda dari hasil registered: false.

Alur Kerja yang Disarankan

Untuk daftar kontak, gunakan urutan berikut:

1. Normalisasi format dan hilangkan duplikat.
2. Pecah menjadi batch berisi maksimal 20 nomor.
3. Panggil /api/v1/numbers/check.
4. Simpan registered, jid, dan waktu cek.
5. Kirim hanya ke nomor terdaftar yang juga memiliki izin untuk dihubungi.
6. Tandai nomor gagal tanpa menghapus datanya secara permanen.

Mulai di LoginWA, ambil API key dari app, lalu uji dua atau tiga nomor yang kamu kenal. Setelah format respons terverifikasi di sistemmu, jalankan untuk daftar yang lebih besar melalui job latar belakang. Hasilnya bukan jaminan pesan dibaca, tetapi daftar penerima menjadi jauh lebih bersih sebelum kuota dipakai.