Autentikasi & API Key

API NgirimWA memungkinkan Anda mengintegrasikan layanan WhatsApp ke dalam aplikasi Anda.

Pembaruan 18 September 2026: kontrak API diperjelas agar lebih jujur dan konsisten. Ringkasan: (1) semua error memakai amplop { success, message, details: { code } } — field lama error masih dikirim sebagai alias sampai 31 Oktober 2026; (2) status perangkat (device_not_connected, device_logged_out) kini 409, bukan 400, dengan pesan berbahasa Inggris; (3) rate limit 1.000 request/jam dihitung per API key, bukan per IP; (4) endpoint kirim menjawab "... queued for delivery" + data.job_id karena pesan diproses lewat antrean; (5) API key yang salah selalu 403 (bukan 429), dan bila backend autentikasi sementara tidak bisa dihubungi Anda menerima 503 auth_unavailable + Retry-After — boleh retry; (6) webhook dapat ditandatangani (HMAC) dan diulang 1× saat tidak ada respons. Detail di Penanganan Error dan Jenis Event Webhook.

Base URL

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

Semua permintaan API harus menyertakan header x-api-key:

http

x-api-key: API_KEY_ANDA

Cara Mendapatkan API Key

⚠️ Penting: API Key hanya ditampilkan sekali! Simpan dengan aman.

Konsep 1 API Key = 1 Perangkat (1 perangkat bisa buat lebih dari 1 API key)

• Setiap API Key terhubung ke satu perangkat WhatsApp tertentu
• Anda tidak perlu mengirim device_id di setiap request
• Sistem otomatis mengenali perangkat dari API Key

Quick Start

Kirim pesan WhatsApp pertama Anda dengan mudah menggunakan API NgirimWA. Pastikan perangkat WhatsApp Anda sudah terhubungdi dashboard.

Kirim Pesan

curl -X POST https://dash.ngirimwa.com/api/v1/messages/send \
  -H "x-api-key: API_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"to": "628123456789", "message": "Halo dari NgirimWA!"}'

Selesai! Pesan Anda berhasil terkirim.

Rate Limiting

Jika melebihi batas Anda menerima 429 dengan details.code: "rate_limited". Rate limit dihitung per API key — memanggil dari banyak server dengan key yang sama tetap berbagi satu kuota 1.000/jam; bila perlu kuota terpisah untuk sistem yang berbeda, buat API key terpisah per sistem. Setiap respons /api/v1/* membawa header RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, dan RateLimit-Policy; respons 429 juga membawa Retry-After (detik). Header gaya lama X-RateLimit-* tidak dikirim.

Selain itu ada proteksi kegagalan autentikasi: 5 kegagalan per API key atau 20 kegagalan per IP klien dalam 10 menit memblokir key/IP tersebut selama 30 menit (429 details.code: "auth_blocked" + Retry-After). Yang dihitung hanya API key salah/nonaktif dan header x-api-key yang hilang — langganan yang tidak aktif tidak dihitung. Jangan retry otomatis pada 401/403.

Bila backend autentikasi kami sementara tidak bisa dihubungi, Anda menerima 503 details.code: "auth_unavailable" + Retry-After: 5. Ini bukan masalah pada API key Anda — ulangi request beberapa detik kemudian.

Idempotency-Key

Untuk mencegah pesan terkirim ganda akibat retry HTTP, sertakan header Idempotency-Key pada request POST /messages/* dan POST /contacts/verify:

Idempotency-Key: <uuid-atau-string-unik-per-request>

• Pakai UUID v4, atau gabungan <order-id>-<timestamp> yang unik per request.
• Bila request dengan key yang sama dikirim ulang dalam 24 jam, NgirimWA mengembalikan ulang respons sukses (2xx) yang pertama tanpa eksekusi ganda. Body request tidak dibandingkan — key-nya yang menentukan.
• Hanya respons 2xx yang disimpan. Request yang gagal (4xx/5xx) boleh diulang dengan key yang sama.
• Key di-scope per API Key + method + path — key yang sama dari API Key lain, atau dipakai di endpoint lain (mis. /messages/send lalu /messages/reaction), tidak saling memengaruhi.
• Alias yang juga diterima: x-idempotency-key.
• Header opsional tapi sangat disarankan untuk integrasi production.
• Berlaku hanya untuk POST /messages/* dan POST /contacts/verify. POST /devices/connect dan DELETE /devices/disconnect tidak idempoten — header diabaikan di sana.

Format Respon

Semua respon API menggunakan format JSON standar:

Respon Sukses

{
  "success": true,
  "message": "Operasi berhasil",
  "data": { ... }
}

Respon Error

{
  "success": false,
  "message": "Deskripsi error (bahasa Inggris)",
  "details": { "code": "device_not_connected" }
}

details.code adalah kode mesin yang stabil — gunakan ini (bukan teks message) untuk percabangan logika. Daftar lengkap kode ada di Penanganan Error. Error validasi menambahkan details.errors (array { field, message }).

Deprecated: respons validasi dan rate limit dulu memakai field error. Field itu masih dikirim sebagai alias sampai 31 Oktober 2026, lalu dihapus — migrasikan ke message + details.

Kode Status HTTP

Keamanan API Key

Lakukan

• Simpan API Key di environment variable
• Gunakan HTTPS untuk semua request
• Rotasi API Key secara berkala

Hindari

• Jangan taruh API Key di kode frontend/JavaScript browser
• Jangan commit API Key ke repository publik
• Jangan share API Key dengan pihak tidak berwenang