API Pemeriksa WhatsApp: Memeriksa Pendaftaran dari Backend Anda

Cara tim backend memanggil API pemeriksa WhatsApp, memilih antara pemeriksaan pendaftaran, avatar, dan akun bisnis, serta menangani hasil yang tidak dapat ditentukan.

API pemeriksa WhatsApp mengambil nomor telepon dari server Anda dan mengembalikan, dalam respons yang sama, apakah akun WhatsApp terdaftar pada nomor tersebut pada saat pemeriksaan dilakukan. Di WA Lookup, satu nomor dikirim ke POST /api/v1/check dengan kunci di header X-API-Key dan service_type yang memilih pemeriksaan pendaftaran, avatar, atau akun bisnis, sementara POST /api/v1/batch-check menerima hingga 100 nomor dalam satu permintaan sinkron. Pemeriksaan yang tidak dapat ditentukan akan mengembalikan kode bisnis bukan nol, yang harus diperlakukan oleh kode backend sebagai "coba lagi nanti" dan bukan sebagai jawaban tidak terdaftar.

Apa yang diberikan API pemeriksa WhatsApp kepada backend

Hasil pencarian untuk kueri ini sebagian besar adalah daftar marketplace dan pembungkus API yang menampilkan parameter telepon dan jawaban benar atau salah. Beberapa di antaranya menjalankan pemeriksaan melalui sesi WhatsApp yang terhubung, sehingga API berhenti merespons saat telepon tersebut offline. Sedikit yang menjelaskan apa arti jawaban tersebut bagi kode yang mengonsumsinya, atau cara menangani kasus di mana tidak ada jawaban yang mungkin.

Untuk pekerjaan backend, model mental yang berguna itu sederhana. API pemeriksa WhatsApp menjawab satu pertanyaan per nomor: apakah akun WhatsApp terdaftar pada nomor ini saat pemeriksaan dijalankan? Itu adalah sinyal keberadaan akun untuk satu platform. Ini adalah input yang baik untuk:

• memilih apakah WhatsApp layak dicoba untuk kontak sebelum menggunakan saluran lain;
• membersihkan kolom telepon di CRM atau basis data prospek;
• menambahkan konteks ke antrean tinjauan pendaftaran atau onboarding.

Ini bukan pernyataan tentang siapa yang memegang nomor tersebut atau apakah mereka setuju untuk dihubungi. Simpan catatan persetujuan dan riwayat kontak Anda sebagai input terpisah, dan simpan tanggal setiap pemeriksaan agar nilainya dapat diperbarui nanti.

Cara memanggil API pemeriksa WhatsApp untuk satu nomor

Panggilan satu nomor adalah satu permintaan HTTPS dengan satu respons. Tidak ada pekerjaan untuk dibuat, tidak ada yang perlu di-poll, dan tidak ada URL callback untuk diekspos.

1. Normalisasi ke E.164. Kirim nomor dengan tanda plus, kode panggilan negara, dan nomor nasional, mengikuti rencana penomoran ITU-T E.164. Hapus spasi, tanda kurung, dan awalan trunk nasional. Nomor ponsel Jerman yang ditulis secara lokal sebagai 0151 2345 6789 menjadi +4915123456789. libphonenumber dari Google mengurai input mentah dengan wilayah default dan lebih aman daripada aturan string yang ditulis tangan.
2. Pilih pemeriksaan. Atur service_type ke ws, ws_avatar, atau ws_business tergantung pada keputusan yang akan didorong oleh hasil tersebut.
3. Autentikasi dari server. Kirim kunci di header X-API-Key. Muat dari penyimpanan rahasia atau konfigurasi lingkungan, dan jangan pernah menempatkannya di kode browser, bundel aplikasi seluler, atau repositori publik.
4. Kirim POST /api/v1/check. Hasil untuk nomor tersebut tiba dalam respons terhadap permintaan yang sama.
5. Cabang berdasarkan hasil. Hasil yang selesai membawa jawaban untuk pemeriksaan yang dipilih. Kode bisnis bukan nol berarti pemeriksaan tidak dapat ditentukan untuk saat ini.

Bangun badan permintaan dan penguraian respons dari dokumentasi API WA Lookup saat ini. Payload dari contoh penyedia lain berbeda, dan menyalinnya adalah sumber umum bug integrasi.

Memilih jenis pemeriksaan: ws, ws_avatar, atau ws_business

Nilai service_type menentukan sinyal mana yang kembali. Pilih pemeriksaan tersempit yang menjawab pertanyaan yang diajukan kode Anda, karena setiap pemeriksaan yang selesai akan dikenakan biaya baik jawabannya terdaftar maupun tidak terdaftar.

ws

Pemeriksaan pendaftaran. Ini memberi tahu backend apakah nomor yang dikirimkan memiliki akun WhatsApp terdaftar pada saat pemeriksaan. Ini adalah default untuk keputusan saluran, pembersihan daftar, dan tinjauan pendaftaran.

ws_avatar

Pemeriksaan avatar. Selain pendaftaran, ini melaporkan apakah foto profil tersedia dan, jika ada, tautan ke foto tersebut. Tautan bisa berupa string kosong. Gunakan untuk pengayaan catatan kontak atau untuk memberikan konteks lebih lanjut kepada peninjau manusia. Foto yang hilang tidak mengatakan apa pun tentang apakah nomor tersebut terdaftar.

ws_business

Pemeriksaan akun bisnis. Selain pendaftaran, ini melaporkan apakah akun tersebut adalah akun WhatsApp Business, jenis akun yang dibuat dengan WhatsApp Business app atau platform bisnis. Tim penjualan menggunakannya untuk memisahkan akun bisnis dari akun standar. Ini hanya menjelaskan jenis akun dan bukan pemeriksaan pada perusahaan hukum.

Memeriksa hingga 100 nomor dengan endpoint batch-check

Ketika backend sudah memiliki sekelompok nomor, seperti impor malam hari atau pengiriman formulir dengan beberapa kontak, POST /api/v1/batch-check mengirim hingga 100 nomor dalam satu permintaan sinkron. Seluruh batch kembali dalam respons terhadap permintaan tersebut, atau permintaan gagal secara keseluruhan.

Perilaku tersebut membentuk kode klien:

• Pecah daftar yang lebih besar. Bagi input menjadi kelompok 100 atau kurang dan kirimkan satu demi satu atau dengan jumlah kecil yang terkontrol dalam penerbangan.
• Perlakukan permintaan yang gagal sebagai satu unit. Jika permintaan batch itu sendiri gagal, coba lagi potongan tersebut; jangan tandai nomornya dengan hasil apa pun.
• Tetap baca hasil per nomor. Di dalam batch yang berhasil, setiap nomor memiliki hasil selesai atau tidak ditentukan sendiri, sehingga logika percabangan dari alur satu nomor berlaku untuk setiap entri.
• Hapus duplikat terlebih dahulu. Normalisasi sebelum memecah sering kali mengungkapkan duplikat yang ditulis dalam format lokal yang berbeda; memeriksa setiap nomor sekali menjaga pengeluaran tetap dapat diprediksi.

Endpoint batch masih merupakan alur respons yang sama. Ini adalah alat yang tepat untuk puluhan atau beberapa ratus nomor yang ditangani oleh kode aplikasi, bukan untuk file dengan daftar yang sangat besar.

Menangani pemeriksaan yang tidak ditentukan dan kesalahan permintaan

Kesalahan integrasi yang paling mahal adalah menulis "tidak terdaftar" ke dalam basis data ketika pemeriksaan tidak pernah mencapai keputusan. Hasil tidak terdaftar yang selesai adalah jawaban nyata. Kode bisnis bukan nol sama sekali bukan jawaban.

Pola percabangan yang praktis:

Gunakan exponential backoff untuk percobaan ulang dan batasi jumlah upaya, sehingga masalah sementara tidak berubah menjadi serangkaian panggilan berulang. Simpan nomor yang tidak ditentukan dalam status terpisah seperti "menunggu pemeriksaan ulang", yang memungkinkan laporan membedakannya dari hasil yang diputuskan.

Menjalankan integrasi dalam produksi

Beberapa kebiasaan operasional membuat integrasi pemeriksa lebih mudah didukung:

• Hormati kontrol yang didokumentasikan. Dokumentasi API saat ini menjelaskan kontrol konkurensi dan timeout per pengguna. Sesuaikan jumlah permintaan yang sedang berjalan dengan kontrol tersebut dan baca kembali dokumentasi saat melakukan penskalaan, alih-alih mengasumsikan tunjangan per menit yang tetap.
• Perhatikan saldo akun. Satu saldo akun mencakup dasbor, REST API, dan server MCP, sehingga pekerjaan API besar dan pemeriksaan dasbor manual diambil dari kumpulan yang sama. Periksa saldo di dasbor sebelum menjalankan pekerjaan besar.
• Catat tanpa membocorkan. Catat hasil permintaan dan kode kesalahan, tetapi samarkan nomor telepon di log aplikasi umum dan jangan pernah mencatat kunci API.
• Rotasi kunci. Dasbor mengelola kunci API; rotasi kunci jika mungkin telah terekspos dan perbarui penyimpanan rahasia dalam satu langkah.
• Rekam konteks. Simpan pemeriksaan mana yang berjalan dan kapan. Hasil dari berbulan-bulan yang lalu menjelaskan nomor pada saat itu, bukan hari ini.

Ketentuan Layanan WhatsApp sendiri membatasi akses otomatis atau tidak sah ke layanannya, yang merupakan salah satu alasan tim beralih dari skrip yang menjalankan sesi pribadi ke API yang di-host dengan kuncinya sendiri.

Kapan tugas file lebih cocok daripada API

Untuk daftar yang sangat besar, tugas bulk asinkron adalah pilihan yang lebih baik: unggah file TXT atau CSV dengan satu nomor per baris, tunggu pemrosesan, lalu unduh result.csv. Tugas bulk menggunakan POST /api/v1/bulk-tasks untuk mengirimkan dan GET /api/v1/bulk-tasks/{id} untuk mengikuti kemajuan, dan batas per produk berlaku seperti yang dijelaskan dalam dokumentasi API. File harus berisi nomor dari satu negara, dan layanan bulk tidak mencakup nomor Tiongkok daratan, Hong Kong, atau Makau. Saldo bulk dicadangkan saat pengiriman, dengan bagian yang tidak terpakai dikembalikan setelah pemrosesan.

Untuk sebagian besar fitur backend yang bereaksi terhadap tindakan pengguna atau impor kecil, panggilan sinkron satu nomor dan batch-check tetap menjadi pilihan yang lebih sederhana.

FAQ

Bagaimana tim dapat menguji API pemeriksa WhatsApp sebelum menghubungkannya ke produksi?

Mulailah dengan beberapa nomor yang hasil yang diharapkan sudah diketahui oleh tim, seperti telepon perusahaan, dan panggil endpoint satu nomor dari lingkungan staging. Akun baru yang memenuhi syarat secara otomatis menerima 100 pemeriksaan gratis sekali setelah pendaftaran, yang biasanya cukup untuk melatih jalur terdaftar, tidak terdaftar, dan coba lagi dalam kode klien.

Apa yang harus dilakukan backend ketika nomor kembali tidak ditentukan?

Biarkan bidang hasil kosong, rekam kode bisnis dan waktu, dan tempatkan nomor dalam antrean percobaan ulang dengan backoff. Menulis nilai tidak terdaftar untuk pemeriksaan yang tidak ditentukan akan merusak data daftar dan menyebabkan keputusan saluran yang salah di kemudian hari.

Apakah endpoint batch-check bekerja secara berbeda dari unggahan file?

Ya. Endpoint batch-check mengembalikan hingga 100 hasil dalam respons terhadap permintaan yang sama. Unggahan file membuat tugas bulk asinkron yang diproses di latar belakang, setelah itu result.csv diunduh.

Jenis pemeriksaan mana yang harus digunakan integrasi CRM secara default?

Pemeriksaan pendaftaran, ws, mencakup sebagian besar keputusan saluran dan kualitas data. Tambahkan ws_avatar atau ws_business hanya jika bidang di CRM benar-benar menggunakan ketersediaan avatar atau jenis akun, karena setiap pemeriksaan yang selesai akan dikenakan biaya.

Pelajari Lebih Lanjut

Pilih informasi produk yang sesuai dengan langkah selanjutnya dalam alur kerja Anda.

• Lihat dokumentasi produk →
• Bicara dengan tim →