Verifikasi Nomor WhatsApp

Cek apakah satu atau banyak nomor telepon terdaftar di WhatsApp. Berguna untuk membersihkan database kontak sebelum kampanye, atau memvalidasi input form pendaftaran.

Endpoint

POST /contacts/verify

Base URL

https://dash.ngirimwa.com/api/v1

Headers

x-api-key: API_KEY_ANDA
Content-Type: application/json
Idempotency-Key: <uuid-unik-per-request>

Idempotency-Key opsional. Hasil 2xx dengan key yang sama diputar ulang selama 24 jam — jangan pakai key yang sama untuk daftar nomor yang berbeda.

Request

{
  "phones": [
    "628123456789",
    "628987654321",
    "628111111111"
  ]
}

Respon Sukses

{
  "success": true,
  "message": "Numbers verified",
  "data": [
    { "phone": "628123456789", "exists": true,  "jid": "628123456789@s.whatsapp.net" },
    { "phone": "628987654321", "exists": false, "jid": null },
    { "phone": "628111111111", "exists": true,  "jid": "628111111111@s.whatsapp.net" }
  ]
}

Parameter

Parameter	Tipe	Wajib	Deskripsi
`phones`	string[]	✅	1–50 nomor per request. Format Indonesia (`628...`, `08...`, atau `8...`) atau internasional dengan kode negara — sistem otomatis normalisasi ke bentuk `628...`. Karakter selain digit (`+`, `-`, spasi) dibuang; panjang valid 8–15 digit — aturan yang sama dengan endpoint kirim.

Field Respon

Field	Tipe	Deskripsi
`phone`	string	Nomor yang Anda kirim setelah dinormalisasi (mis. `08123456789` → `628123456789`) — cocokkan hasil dengan bentuk ini
`exists`	boolean	`true` jika nomor terdaftar di WhatsApp
`jid`	string \| null	JID lengkap (untuk dipakai endpoint lain) jika terdaftar, `null` jika tidak

Contoh cURL

curl -X POST https://dash.ngirimwa.com/api/v1/contacts/verify \
  -H "x-api-key: API_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": ["628123456789", "628987654321"]
  }'

Use Case

Sebelum broadcast kampanye — filter dulu nomor yang tidak terdaftar supaya tidak membuang quota & menghindari pengiriman gagal.

Validasi form — saat pelanggan mendaftar via website, verify nomor sebelum simpan supaya CS tahu nomor tersebut bisa di-WA.

Cleaning database — batch process kontak lama untuk hapus nomor yang sudah tidak aktif di WhatsApp.

Catatan Penting

Maksimal 50 nomor per request. Untuk batch lebih besar, panggil endpoint berulang dengan chunk 50.
Endpoint ini tidak menghabiskan kuota pesan — verifikasi adalah operasi metadata, bukan pengiriman.
Endpoint memerlukan device dalam status connected. Bila device sedang offline, response 409 WhatsApp device is not connected (details.code: device_not_connected). Bila layanan sesi sedang restart, 503 session_service_unavailable / 504 — coba lagi.
Bila WhatsApp tidak menjawab, Anda menerima 503 verify_unavailable (tidak ada hasil) atau 504 verify_timeout (lebih dari 15 detik) — bukan 200 dengan semua exists: false. Ulangi beberapa detik kemudian; jangan menganggap nomor tidak terdaftar berdasarkan respons error.
Hasil tidak di-cache oleh server — setiap request mengecek langsung ke WhatsApp (kecuali diputar ulang oleh Idempotency-Key). Hindari memanggil ulang untuk nomor yang sama dalam interval singkat.

Verifikasi Nomor WhatsApp

On this page