Dokumentasi API

Kirim pesan WhatsApp lewat HTTP, termasuk tombol interaktif (salin kode, link, balas cepat, daftar pilihan). Cara pakainya mirip Fonnte: satu token per device.

1. Autentikasi

Ambil token di Dashboard → Salin token. Kirim lewat header Authorization.

Authorization: TOKEN_DEVICE_KAMU

Format Bearer TOKEN, header X-Token, atau parameter token juga diterima. Base URL:

Body boleh application/json atau x-www-form-urlencoded (field buttons kirim sebagai string JSON).

2. Cek status device

GET/api/device

{ "status": true, "device": "a1b2c3d4", "name": "Toko", "status": "open", "phone": "6281234567890" }

3. Kirim pesan

POST/api/send

Field	Wajib	Keterangan
`target`	ya	Nomor tujuan. Format `08xx`, `628xx`, atau ID grup `[email protected]`. Banyak nomor dipisah koma (maks 200, diproses di background dengan jeda acak).
`message`	ya*	Isi pesan. Mendukung format WhatsApp (`tebal`, `_miring_`). *Boleh kosong jika kirim media.
`footer`	tidak	Teks kecil di bawah pesan (untuk pesan bertombol).
`buttons`	tidak	Array tombol, lihat bagian 4. Maks 5.
`image_url`	tidak	Gambar header (untuk pesan bertombol) atau gambar biasa.
`file_url`	tidak	URL dokumen/file. `filename` untuk nama file.
`delay`	tidak	Jeda antar target, detik. Contoh `5` atau `3-8` (acak). Default dari `.env`.
`typing`	tidak	`false` untuk mematikan efek "mengetik…".

Respons sukses:

{ "status": true, "detail": "sent", "id": ["3EB0A1B2C3..."], "target": ["08123456789"], "process": "sent" }

Untuk banyak target: "detail": "queued" (dikirim bertahap di background).

4. Tombol interaktif

Setiap tombol adalah objek dengan field type:

type	Field	Fungsi
`copy`	`text`, `code`	Tombol Salin Kode — menyalin `code` ke clipboard penerima.
`url`	`text`, `url`	Membuka link.
`call`	`text`, `phone`	Menelepon nomor (format internasional, mis. `628123...`).
`reply`	`text`, `id`	Quick reply. Saat ditekan, `id` dikirim ke webhook.
`list`	`text`, `sections[]`	Menu pilihan. Tiap section punya `title` dan `rows[]` (`id`, `title`, `description`).

Teks tombol maks 25 karakter.

"buttons": [
  { "type": "copy",  "text": "Salin Kode", "code": "482913" },
  { "type": "url",   "text": "Buka Dashboard", "url": "https://contoh.com" },
  { "type": "call",  "text": "Hubungi CS", "phone": "6281234567890" },
  { "type": "reply", "text": "Konfirmasi", "id": "confirm_123" }
]

Contoh menu list:

"buttons": [{
  "type": "list", "text": "Pilih layanan",
  "sections": [{
    "title": "Layanan",
    "rows": [
      { "id": "svc_1", "title": "Cek Pesanan",  "description": "Lacak status order" },
      { "id": "svc_2", "title": "Hubungi CS",   "description": "Chat dengan admin" }
    ]
  }]
}]

Tombol interaktif memakai fitur WhatsApp yang tidak resmi untuk akun biasa. Tampilannya bisa berbeda antar versi WhatsApp, dan di beberapa akun/versi tombol bisa tidak muncul. Selalu sertakan teks pesan yang bisa dibaca tanpa tombol (mis. kode OTP tetap ada di message).

5. Kirim OTP (tombol Salin Kode)

POST/api/send-otp — shortcut untuk OTP.

Field	Wajib	Keterangan
`target`	ya	Nomor tujuan.
`code`	ya	Kode OTP.
`message`	tidak	Teks custom. Default: "Kode verifikasi Anda: 123456 …".
`button_text`	tidak	Teks tombol, default `Salin Kode`.

6. Webhook pesan masuk

Isi URL webhook di Dashboard → Kelola. Setiap pesan masuk dikirim sebagai POST JSON:

{
  "device": "a1b2c3d4",
  "id": "3EB0...",
  "from": "628123456789",
  "chat": "[email protected]",
  "isGroup": false,
  "pushName": "Budi",
  "timestamp": 1761577000,
  "type": "text",          // text | image | video | document | audio | button_reply | list_reply
  "text": "Halo",
  "buttonId": null         // terisi saat type = button_reply / list_reply
}

Contoh: ketika pelanggan menekan tombol reply dengan id: "confirm_123", webhook menerima type: "button_reply" dan buttonId: "confirm_123".

7. Kode error

HTTP	Arti
400	Parameter salah / tombol tidak valid
401	Token salah
409	Device belum terhubung ke WhatsApp
429	Rate limit 60 request/menit per token
500	Gagal kirim (mis. nomor tidak terdaftar di WhatsApp)

Semua error berbentuk { "status": false, "reason": "…" }.

8. Tips agar akun aman

Pakai nomor yang sudah "hangat" (bukan nomor baru), dan hanya kirim ke orang yang mengharapkan pesan.
Untuk broadcast, beri delay minimal 5–10 detik dan variasikan isi pesan.
Hindari pengiriman massal ke nomor yang belum pernah menghubungi Anda — risiko banned tinggi.