Siapkan token API

Masuk sebagai pengguna yang akan mengirim, lalu buka Akun Saya → Token API saya dan buat token baru. Simpan saat ditampilkan karena token hanya muncul sekali. Jangan menaruh token pada halaman web publik.

Semua permintaan memakai Authorization: Bearer TOKEN_API_PENGGUNA. Body pengiriman memakai JSON. Aplikasi eksternal boleh langsung mengirim nomor to dan isi message tanpa menyimpan kontak di dashboard ini.

Token menentukan akun pengirim

Setiap token terikat ke satu pengguna. Paket Pribadi mengirim dari WhatsApp pengguna itu. Paket Bersama mengirim dari nomor bersama yang dipilih Admin atau Super Admin. Kuota dan riwayat tetap mengikuti pemilik token.

Periksa identitas dan paket token:

Respons menampilkan username, senderMode, senderName, status langganan, dan izin API. Pengiriman perlu izin role Kirim pesan serta paket aktif dengan akses API.

API pesan biasa selalu memakai akun pemilik token. Admin memakai endpoint kampanye terpisah untuk mengirim ke seluruh kontak pelanggan yang dipilih.

Kirim satu pesan

Isi to dengan nomor internasional, misalnya 628123456789, dan message dengan teks hingga 4.096 karakter. scheduledAt opsional; tanpa itu pesan masuk antrean sekarang. Untuk menjadwalkan, kirim waktu ISO 8601 dengan zona, seperti YYYY-MM-DDTHH:mm:ss+07:00.

Gunakan Idempotency-Key unik untuk setiap pesan baru dan pakai lagi kunci yang sama saat mengulang permintaan tersebut. Nomor akan dinormalkan ke format internasional.

Gunakan bahasa aplikasi Anda

Contoh berikut mengirim satu pesan melalui aplikasi sisi server. Simpan token pengguna pada variabel lingkungan KURIR_WA_TOKEN. Ganti nomor, isi pesan, dan Idempotency-Key untuk setiap pesan baru; gunakan kunci yang sama ketika mengulang permintaan yang hasil HTTP-nya belum jelas. Respons 202 hanya berarti pesan sudah masuk antrean.

Untuk pengiriman massal, gunakan pola request yang sama ke POST /api/v1/messages/bulk dan ubah to menjadi array nomor. Untuk gambar, unggah berkas biner sekali ke POST /api/v1/images, lalu sertakan imageId hasil unggahan pada body pesan. Pantau id dari respons dengan GET /api/v1/messages/:id.

Kirim gambar dengan caption

Unggah JPG atau PNG maksimal 5 MB sebagai body biner ke POST /api/v1/images dengan Bearer token pengguna. Respons berisi imageId. Sertakan ID itu bersama message saat memanggil endpoint pesan biasa atau massal. Untuk 10 penerima, unggah sekali dan pakai ID yang sama: server menyimpan satu file. HTML tidak didukung; editor dashboard mengubah tebal, miring, dan coret menjadi format teks WhatsApp.

Admin yang mengirim kampanye pelanggan mengunggah ke POST /api/v1/customers/:id/images, lalu mengisi imageId pada POST /api/v1/campaigns. ID gambar hanya dapat dipakai oleh akun pemiliknya. File dibersihkan otomatis tujuh hari setelah seluruh job selesai; pesan yang masih antre tetap menyimpan file.

Media, lokasi, dan grup

Paket menentukan izin allowImage, allowMedia, allowLocation, dan allowGroups. Periksa melalui GET /api/v1/account. Teks biasa selalu tersedia bagi langganan aktif.

Media: unggah file biner sekali ke POST /api/v1/media dengan header Content-Type dan X-File-Name (nama file URL encoded). Format: PDF, DOCX, XLSX, MP3, OGG, WAV, MP4, atau WebM; maksimal 20 MB. Respons memberi mediaId. Kirim dengan {"messageType":"media","mediaId":"...","to":"628...","message":"Keterangan opsional"}. File yang sama dapat dipakai untuk beberapa tujuan dan dibersihkan tujuh hari setelah seluruh pengirimannya selesai.

Lokasi: gunakan messageType: "location" dan location berisi latitude, longitude, nama, dan alamat. Grup: lihat daftar grup nomor pengirim melalui GET /api/v1/groups, lalu gunakan recipientType: "group" dan to berupa ID grup. Endpoint bulk menerima array ID grup. Pada paket Bersama, Admin perlu memilih grup pelanggan melalui Langganan → Atur grup; pelanggan hanya melihat dan memakai grup yang dipetakan untuknya.

List dengan pilihan yang dapat diketuk belum tersedia lewat integrasi WhatsApp Web ini. Pengiriman messageType: "list" ditolak; fitur itu memerlukan integrasi WhatsApp Business Platform tersendiri. Sequence Message tidak tersedia sesuai pengaturan aplikasi ini.

Kirim ke banyak kontak

Isi to dengan array nomor, atau "all" untuk seluruh kontak milik pengguna token. Setiap penerima mendapat job dan status sendiri.

Pengiriman diproses berurutan per akun WhatsApp. Paket dapat membatasi jumlah pesan per bulan.

Kirim ke seluruh kontak pelanggan

Token Admin atau Super Admin dengan izin kampanye dapat mengirim ke satu pelanggan yang dipilih melalui POST /api/v1/campaigns. Isi customerId dengan ID pelanggan dan message dengan isi pesan; scheduledAt opsional. Paket, kuota, dan akun WhatsApp pelanggan menentukan pengiriman. Respons memberi batchId dan count.

Dapatkan ID pelanggan melalui GET /api/v1/customers?limit=100&offset=0:

Pesan mendukung {nama_kontak}, {tanggal}, dan {jam}. Anda juga dapat mengirim templateId sebagai pengganti message. Pratinjau dengan POST /api/v1/customers/:id/preview; body berisi message atau templateId, serta scheduledAt opsional. Daftar kampanye tersedia di GET /api/v1/customers/:id/campaign-batches. Detail batch di GET /api/v1/customers/:id/batches/:batchId. Untuk menjeda, melanjutkan, membatalkan sisa antrean, atau mencoba ulang pesan gagal, gunakan POST /api/v1/customers/:id/batches/:batchId/:action dengan action pause, resume, cancel, atau retry. Setiap job mencatat requestedByUserId.

Cek status pesan

Respons kirim memberi id dan status awal queued. HTTP 202 berarti pesan diterima ke antrean, belum berarti terkirim.

Untuk bulk akun sendiri, pakai GET /api/v1/batches/:batchId?limit=100&offset=0. Untuk kampanye pelanggan, pakai endpoint batch pelanggan. Status akhir: sent, failed, canceled, atau unknown. Status unknown berarti hasil kirim belum dapat dipastikan; periksa chat WhatsApp sebelum mengirim ulang. Jika pesan sudah terkirim, konfirmasi melalui tombol di Riwayat.

Respons dan error

Contoh respons sukses: