Kelola Perangkat

Tiga endpoint untuk mengelola koneksi WhatsApp device terkait API Key Anda. Device ID otomatis terbaca dari API Key — Anda tidak perlu mengirim device_id.

Base URL

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

Headers (semua endpoint)

x-api-key: API_KEY_ANDA

Periksa apakah device WhatsApp Anda terhubung. Berguna sebelum kirim massal atau sebelum memanggil endpoint yang butuh sesi hidup (/groups, /contacts/verify, /messages/reaction, /messages/mark-read, /messages/presence) — endpoint tersebut menjawab 409 device_not_connected bila perangkat offline. Endpoint kirim pesan tidak perlu dicek dulu: pesan diantrekan dan dikirim saat koneksi pulih; hanya sesi yang sudah berakhir ditolak dengan 409 device_logged_out.

Endpoint

GET /devices/status

Respon Sukses

{
  "success": true,
  "message": "Device status",
  "data": {
    "status": "connected",
    "user": {
      "id": "628123456789:1@s.whatsapp.net"
    },
    "phone_number": "628123456789",
    "db_status": "connected"
  }
}

Nilai `status`

Status	Arti
`connected`	✅ Sesi WhatsApp aktif di server — siap mengirim
`connecting`	🔄 Sesi ada tetapi sedang tersambung ulang (gangguan singkat / setelah restart) — tunggu beberapa detik lalu cek lagi; pesan yang dikirim saat ini tetap diantrikan
`disconnected`	❌ Tidak ada sesi: belum scan QR, logout dari HP, atau kredensial sudah tidak berlaku — hubungkan ulang via dashboard atau `/devices/connect`

Field Respon

Field	Tipe	Deskripsi
`status`	string	Status koneksi real-time (lihat tabel di atas)
`user.id`	string \| null	Identitas akun WhatsApp (`<nomor>:<device>@s.whatsapp.net`); `null` saat `disconnected`
`phone_number`	string \| null	Nomor WhatsApp yang terhubung; `null` saat `disconnected`
`db_status`	string \| null	Status perangkat di dashboard (`connected`, `disconnected`, `logged_out`, `connecting`). Bisa tertinggal beberapa detik dari `status`

status adalah sumber kebenaran untuk keputusan "boleh kirim sekarang?". db_status hanya untuk cross-check dengan tampilan dashboard.

cURL

curl -X GET https://dash.ngirimwa.com/api/v1/devices/status \
  -H "x-api-key: API_KEY_ANDA"

Hubungkan Perangkat (Dapatkan QR Code)

Hasilkan QR code untuk login WhatsApp. Endpoint ini menunggu sampai QR siap (timeout 30 detik) lalu mengembalikan base64 PNG. Bila device sedang terhubung, sesi yang ada akan diputus untuk memulai login baru.

Endpoint

POST /devices/connect

Respon Sukses

{
  "success": true,
  "message": "QR Code generated",
  "data": {
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

Render qr_code di frontend Anda. User scan dari WhatsApp ponsel mereka. Setelah scan, status berubah ke connected dan QR tidak berlaku lagi.

Respon Gagal

Kode	`message`	Arti
408	`QR code generation timeout`	QR tidak siap dalam 30 detik — panggil ulang
503 / 504	`Device session service is temporarily unavailable...` / `... timed out` (`details.code: session_service_unavailable`)	Layanan sesi perangkat sedang restart / tidak bisa dijangkau — coba lagi beberapa detik (`Retry-After`)

POST /devices/connect dan DELETE /devices/disconnect tidak idempoten — header Idempotency-Key diabaikan. Jangan memanggilnya ulang secara otomatis tanpa mengecek /devices/status dulu.

cURL

curl -X POST https://dash.ngirimwa.com/api/v1/devices/connect \
  -H "x-api-key: API_KEY_ANDA"

Catatan: Lebih praktis, hubungkan device langsung dari Dashboard → Perangkat → Semua Perangkat. Endpoint ini berguna bila Anda mengintegrasikan onboarding di aplikasi Anda sendiri.

Putuskan Perangkat

Logout WhatsApp dari NgirimWA. Session di server dihapus; setelah ini endpoint kirim dijawab 409 device_logged_out dan endpoint yang butuh sesi hidup dijawab 409 device_not_connected sampai device dihubungkan ulang.

Endpoint

DELETE /devices/disconnect

Respon Sukses

{
  "success": true,
  "message": "Device disconnected successfully"
}

cURL

curl -X DELETE https://dash.ngirimwa.com/api/v1/devices/disconnect \
  -H "x-api-key: API_KEY_ANDA"

Hati-hati: Pemutusan ini bersifat permanen sampai login ulang via QR. Tidak ada konfirmasi atau undo.

Kelola Perangkat

Base URL

Headers (semua endpoint)

Cek Status Perangkat

Endpoint

Respon Sukses

Nilai `status`

Field Respon

cURL

Hubungkan Perangkat (Dapatkan QR Code)

Endpoint

Respon Sukses

Respon Gagal

cURL

Putuskan Perangkat

Endpoint

Respon Sukses

cURL

On this page