Dokumentasi API

Kirim satu pesan

POST https://hiwa.my.id/api/v1/messages

Header: Accept: application/json, Content-Type: application/json

Body JSON

{
  "token_device": "YOUR_DEVICE_TOKEN_HERE",
  "to": "6281234567890",
  "message": "Halo dari API HiWA"
}

• token_device (string, wajib) — Token kirim perangkat dari alur Perangkat (ditampilkan sekali saat perangkat pertama kali terhubung, atau setelah dibuat ulang).
• to (string, wajib) — Penerima dalam format angka internasional, atau JID lengkap @c.us. Nomor Indonesia boleh diawali 0 (diubah ke 62).
• message (string, wajib, maks. 4096) — Isi teks biasa.

Respons sukses 200

{
  "ok": true,
  "message_id": "true_6281234567890@c.us_ABC123",
  "quota": {
    "messages_remaining": 99,
    "messages_limit_per_month": 100
  }
}

Objek `quota` berisi `messages_remaining` (turun satu setiap pengiriman sukses) dan `messages_limit_per_month` dari paket layanan akun. Isi ulang bulanan dari proses Anda sendiri; bila perlu bisa memakai `php artisan users:reset-monthly-message-quotas`.

Kuota bulanan di respons API

Respons sukses dan sebagian besar error menyertakan objek `quota` untuk pengguna pemilik perangkat: `messages_remaining` dan `messages_limit_per_month`. Setelah sukses, nilai remaining sudah dikurangi untuk pesan yang baru dikirim.

401 `token_device` tidak valid — hanya `ok` dan `message`, tanpa `quota`. 403 akun tidak aktif — ada `quota` (nol jika perangkat tanpa pemilik). 422 — validasi Laravel memakai `errors` dan `message`; perangkat belum terhubung, nomor tidak valid, kuota bulanan habis, dan banyak kegagalan gateway tetap menyertakan `quota` agar counter di aplikasi Anda bisa diperbarui. 404 / 409 / 5xx — gateway atau server; field `message` menjelaskan bila tersedia dan `quota` sering tetap ada setelah gagal kirim yang mengembalikan reservasi kuota.

Contoh — kuota bulanan habis (422)

{
  "ok": false,
  "message": "Kuota pesan bulanan paket Anda sudah habis. Coba lagi bulan depan atau naikkan paket.",
  "quota": {
    "messages_remaining": 0,
    "messages_limit_per_month": 100
  }
}

Respons error

• 401 — token_device tidak valid atau tidak dikenal. Respons ini tidak menyertakan field `quota`.
• 403 — Akun Anda tidak aktif. Hubungi administrator untuk mengaktifkan akun.
• 422 — Body tidak valid (error validasi Laravel), perangkat tidak terhubung, penerima tidak valid, atau WhatsApp menolak pengiriman. Periksa pesan JSON (dan field errors jika validasi gagal).
• 422 — Kuota pesan bulanan habis; respons memuat objek quota yang sama dengan messages_remaining bernilai 0.
• 404 / 409 — Gateway hulu: sesi WhatsApp belum termuat di Node atau belum terhubung. Restart wa-gateway (npm start) setelah pembaruan kode dan pastikan perangkat tampil terhubung di aplikasi.
• 4xx/5xx lainnya — Kegagalan gateway atau server; field message menjelaskan masalah bila tersedia.

---

Contoh cURL

curl -X POST "https://hiwa.my.id/api/v1/messages" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{\"token_device\":\"YOUR_DEVICE_TOKEN_HERE\",\"to\":\"6281234567890\",\"message\":\"Halo\"}"