Dokumentasi Halokirim
Halokirim adalah layanan WhatsApp Gateway untuk bisnis Indonesia: hubungkan nomor WhatsApp Anda sendiri (disebut device), lalu kirim pesan satuan, broadcast, pesan terjadwal, dan notifikasi otomatis lewat dashboard atau REST API. Pembayaran memakai kredit prabayar per device, dengan opsi Plan Akun berupa pool kredit bersama plus fitur tambahan.
Halokirim adalah layanan tidak resmi (unofficial): bukan produk atau mitra resmi WhatsApp LLC / Meta. Layanan bekerja melalui protokol perangkat tertaut WhatsApp, sehingga nomor yang dipakai berisiko dibatasi atau diblokir oleh WhatsApp bila melanggar kebijakan mereka. Kirim pesan hanya kepada penerima yang bersedia dihubungi (opt-in) dan jangan mengirim spam.
Mulai Cepat
- Masuk ke akun dengan email dan kata sandi. Pendaftaran publik dapat ditutup selama persiapan operasional. Sebelum membuka ruang kerja, aktifkan authenticator di Keamanan akun dan simpan kode pemulihan secara offline.
- Tambah device dari Dashboard: beri nama nomor Anda (mis. "WA Toko"), lalu simpan token API yang tampil satu kali — token utuh tidak akan ditampilkan lagi (di server hanya tersimpan hash-nya). Setiap device baru otomatis mendapat 100 kredit trial gratis.
- Hubungkan nomor: di halaman device, scan QR dengan WhatsApp (menu Perangkat tertaut) atau minta kode pairing 8 digit lalu masukkan dari ponsel nomor tersebut.
- Top-up kredit lewat menu Top Up (pembayaran via Duitku: transfer bank, QRIS, e-wallet, virtual account). Kredit masuk otomatis setelah pembayaran terkonfirmasi, tanpa perlu mengirim bukti transfer.
- Mulai kirim: dari halaman device (form kirim uji), halaman Broadcast, atau REST API memakai token device.
Konsep Kredit
- Tarif: pesan teks, lokasi, dan autoreply = 1 kredit; pesan dengan lampiran media (gambar, video, dokumen, audio) = 3 kredit.
- Kredit hanya terpotong bila pesan berhasil terkirim ke WhatsApp. Pesan gagal (device terputus, nomor tidak valid, saldo kurang) = 0 kredit dan tercatat
faileddi riwayat. - Kredit menempel per device: top-up mengisi device yang dipilih; device lain tidak ikut terisi. Broadcast memakai kredit device pengirim.
- Kredit per device tidak kedaluwarsa selama akun aktif (ada aktivitas apa pun dalam 12 bulan terakhir).
- Watermark trial: selama device belum pernah top-up berbayar, setiap pesan teksnya memakai tanda di bawah pesan:
Dikirim dari Halokirim
Setelah top-up berbayar pertama pada device itu, watermark hilang permanen untuk device tersebut.
- Saldo gabungan kurang dari biaya pesan: pengiriman ditolak dengan alasan saldo kredit habis (API: HTTP 402).
Plan Akun
Plan Akun adalah langganan per periode 30 hari yang berlaku untuk seluruh akun (bukan per device), ditambahkan di samping top-up per device:
| Plan | Harga / 30 hari | Pool bersama | Maks device | Watermark | Fitur |
|---|---|---|---|---|---|
| Bersama | Rp49.000 | 5.000 kredit | 3 | tetap ada | dasar |
| Pro | Rp149.000 | 15.000 kredit | 10 | hilang | semua |
Aturan mainnya:
- Pool bersama dipakai semua device di akun dan selalu dipotong lebih dulu, baru kredit per device pengirim (yang hangus berkala dipakai duluan; kredit per device tidak kedaluwarsa).
- Fitur dasar (semua akun): kirim pesan, broadcast, jadwal, template, kontak & grup kontak, lampiran media & lokasi.
- Fitur Plan Pro (semua): tambahan REST API, autoreply kata kunci, webhook pesan masuk, rotator (mode device acak), serta statistik & mutasi kredit.
- Plan Pro mematikan watermark untuk semua device selama plan aktif.
- Masa tenggang 3 hari setelah plan berakhir: plan dan pool tetap bisa dipakai. Lewat masa tenggang tanpa perpanjangan, sisa pool hangus dan plan nonaktif.
- Perpanjangan manual dari halaman Plan Akun (invoice Duitku) karena tidak ada penagihan otomatis; memperpanjang plan yang sama menambah 30 hari dari tanggal berakhir yang tercatat dan menambah pool baru ke sisa pool.
REST API
Semua endpoint API memakai token per device. Token hanya tampil satu kali saat device dibuat atau diregenerasi; bila hilang, regenerate dari halaman device (token lama langsung tidak berlaku).
Token baru berlaku 90 hari. Di halaman device, buka Batasi izin dan alamat IP untuk memilih izin, mengatur masa berlaku 1–90 hari, dan membatasi IP publik/CIDR server integrasi. Pembatasan berlaku juga untuk API lama. Token lama sebelum pembaruan tidak langsung diputus; pemilik perlu mengatur masa berlaku atau merotasinya. Token kedaluwarsa menghasilkan HTTP 401; izin atau IP yang ditolak menghasilkan HTTP 403. Rotator memerlukan izin tersendiri. Simpan token hanya di secret server, bukan URL, repository, atau JavaScript browser.
HTTP 429 berarti batas permintaan tercapai; ikuti header Retry-After. Untuk pengiriman, gunakan API v1 dengan Idempotency-Key, dan periksa status sebelum mencoba ulang agar pesan tidak terkirim ganda.
Autentikasi
Kirim token di header Authorization, polos atau dengan awalan Bearer:
Authorization: <TOKEN_DEVICE>
atau
Authorization: Bearer <TOKEN_DEVICE>
Token salah atau hilang dibalas HTTP 401:
{ "status": false, "reason": "unauthorized: invalid token" }
Akses API adalah fitur Plan Pro: token dari akun tanpa fitur API dibalas HTTP 403:
{ "status": false, "reason": "Fitur API hanya tersedia pada Plan Pro" }
POST /send — kirim satu pesan
Body JSON:
| Parameter | Wajib | Keterangan |
|---|---|---|
| target | ya | Nomor tujuan format 628xx, atau JID grup [email protected]. Alias: number, phone |
| message | bersyarat | Isi pesan teks. Alias: text. Menjadi caption bila ada file, dan nama pin bila type location. Wajib kecuali ada file atau type location |
| file | tidak | URL publik lampiran (gambar/video/dokumen/audio, maks 25 MB) |
| filename | tidak | Nama file untuk lampiran dokumen |
| type | tidak | Isi "location" untuk mengirim pin lokasi |
| latitude | bersyarat | Lintang; wajib bila type location |
| longitude | bersyarat | Bujur; wajib bila type location |
| device | tidak | Isi "random" untuk mode rotator: device pengirim dipilih acak dari device akun yang terhubung dan saldonya cukup (fitur rotator Plan Pro; tanpa fitur itu, device terhubung pertama yang dipakai) |
Contoh pesan teks:
curl -X POST https://halokirim.nusakode.com/send -H "Authorization: <TOKEN_DEVICE>" -H "content-type: application/json" -d '{"target": "6281234567890", "message": "Halo, pesanan Anda sudah dikirim."}'
Contoh pesan media (message menjadi caption):
curl -X POST https://halokirim.nusakode.com/send -H "Authorization: <TOKEN_DEVICE>" -H "content-type: application/json" -d '{"target": "6281234567890", "message": "Brosur bulan ini", "file": "https://contoh.id/brosur.pdf", "filename": "brosur.pdf"}'
Contoh lokasi:
curl -X POST https://halokirim.nusakode.com/send -H "Authorization: <TOKEN_DEVICE>" -H "content-type: application/json" -d '{"target": "6281234567890", "type": "location", "latitude": -6.2, "longitude": 106.8, "message": "Lokasi toko kami"}'
Respons sukses (HTTP 200) — dikembalikan setelah pesan tersebut selesai diproses antrean:
{ "status": true, "device": "<id-device>", "target": "6281234567890" }
Respons gagal yang umum:
| HTTP | Isi reason | Penyebab |
|---|---|---|
| 401 | unauthorized: missing token / invalid token | Header Authorization kosong atau token salah |
| 403 | Fitur API hanya tersedia pada Plan Pro | Akun token tidak punya fitur API |
| 400 | target is required | Parameter target tidak dikirim |
| 400 | message is required (or provide file / type location) | Tidak ada message, file, maupun type location |
| 400 | latitude and longitude are required for type "location" | Lokasi tanpa koordinat lengkap |
| 400 | device is not connected | Device pengirim belum terhubung ke WhatsApp (detail berisi status device) |
| 402 | saldo kredit habis | Saldo gabungan (pool plan + kredit device) kurang dari biaya pesan |
| 500 | failed to send message | Pengiriman gagal di antrean (detail berisi penyebab) |
Variabel personalisasi: {nama} dan {nomor} di dalam message diganti dari buku kontak akun bila nomor dikenal (alias Inggris {name} dan {number} juga didukung); nama yang tidak dikenal diganti string kosong.
POST /broadcast — kirim ke banyak target
Body JSON:
| Parameter | Wajib | Keterangan |
|---|---|---|
| targets | salah satu | Array nomor tujuan (format 628xx / 08xx diterima, dinormalisasi) |
| group_id | salah satu | ID grup kontak milik akun (alias: groupId, group). Boleh digabung dengan targets; duplikat dibuang |
| message | bersyarat | Isi pesan; variabel {nama} dan {nomor} dipersonalisasi per penerima. Alias: text. Wajib kecuali ada file |
| file | tidak | URL publik lampiran; message menjadi caption |
| filename | tidak | Nama file untuk lampiran dokumen |
| device | tidak | Sama seperti /send: "random" untuk mode rotator |
Contoh:
curl -X POST https://halokirim.nusakode.com/broadcast -H "Authorization: <TOKEN_DEVICE>" -H "content-type: application/json" -d '{"targets": ["6281234567890", "6281234567891"], "message": "Halo {nama}, ada promo khusus bulan ini."}'
Respons sukses (HTTP 200) dikembalikan langsung setelah semua target masuk antrean (hasil akhir tiap target tercatat di riwayat pesan):
{ "status": true, "device": "<id-device>", "accepted": 2 }
Respons gagal: 401 / 403 sama seperti /send; HTTP 400 dengan reason no valid targets (provide targets[] or group_id), contact group not found, atau message is required (or provide file).
Semua pengiriman dari API masuk antrean per device dengan jeda acak 2–5 detik antar pesan (anti-burst). /send menunggu hasil pesan yang bersangkutan; /broadcast tidak menunggu hasil tiap target.
GET /device-info — info device, saldo, dan plan
Tanpa body; autentikasi token sama seperti /send. Contoh respons (HTTP 200):
{
"status": true,
"device": { "id": "<id-device>", "name": "WA Toko", "phone": "6281234567890", "connected": true },
"credits": 850,
"plan": { "active": true, "name": "Pro", "pool": 12000, "expiresAt": 1796000000000 }
}
Field credits adalah saldo kredit device pemilik token (belum termasuk pool plan). plan.name bernilai null dan plan.expiresAt null bila tidak ada plan aktif; plan.pool adalah sisa pool bersama saat ini.
Webhook Pesan Masuk
Isi URL webhook di halaman device (fitur Plan Pro). Setiap pesan masuk dikirim sebagai POST JSON ke URL tersebut, dengan 1 percobaan + 2 retry bila gagal:
{
"device": "<id-device>",
"deviceName": "WA Toko",
"sender": "6281234567890",
"senderName": "Nama Pengirim",
"message": "isi pesan teks",
"timestamp": 1796000000000,
"isGroup": false
}
| Field | Keterangan |
|---|---|
| device | ID device penerima pesan |
| deviceName | Nama device penerima pesan |
| sender | Nomor pengirim (untuk pesan grup: nomor peserta yang mengirim) |
| senderName | Nama profil WhatsApp pengirim (bisa kosong) |
| message | Isi teks pesan (atau caption media) |
| timestamp | Waktu pesan dalam epoch milidetik |
| isGroup | true bila pesan berasal dari grup |
MCP Server (agen AI)
Halokirim menyediakan server MCP (Model Context Protocol) di folder mcp/ pada repositori, sehingga agen AI seperti Claude Code dapat mengirim pesan lewat perangkat Anda dengan tiga tool: halokirim_send, halokirim_broadcast, dan halokirim_device_info. Konfigurasi cukup dua variabel env: HALOKIRIM_BASE_URL (default https://halokirim.nusakode.com) dan HALOKIRIM_TOKEN (token device). Petunjuk pemasangan ada di mcp/README.md. Token yang dipakai tetap memerlukan fitur API (Plan Pro).
Fitur Dashboard
- Broadcast: kirim massal dari daftar nomor manual/CSV atau grup kontak, dengan pilihan template dan lampiran; mode rotator tersedia sebagai pilihan device pengirim "Acak / rotator" (Plan Pro).
- Jadwal: pesan sekali, harian, atau mingguan ke satu nomor atau grup kontak; diperiksa tiap 30 detik mengikuti waktu lokal server.
- Template: simpan teks pesan dengan variabel {nama} / {nomor}, dapat dipilih di form kirim.
- Kontak & Grup Kontak: buku kontak per akun (impor CSV format number,name), digrupkan untuk target broadcast dan jadwal.
- Autoreply: aturan kata kunci per device (pencocokan contains, tidak peka huruf) — fitur Plan Pro.
- Riwayat Pesan: semua pesan masuk dan keluar lintas device dengan filter device/status/arah dan penomoran halaman. Pesan keluar berteks dapat dikirim ulang (memakai kredit seperti pesan baru; lampiran tidak tersimpan sehingga hanya teks yang dikirim), dijadwalkan ulang menjadi jadwal sekali kirim, atau dihapus dari riwayat.
- Inbox CS & Tim CS: inbox bersama untuk semua pesan masuk per device (Plan Pro). Pemilik akun menambah agen dari menu Tim CS; agen hanya dapat mengakses inbox (dan menu Akun), dapat ditugaskan menangani percakapan tertentu, dan membalas chat pelanggan langsung dari dashboard — balasan dikirim lewat device terkait dan memakai kredit seperti pesan biasa. Percakapan dapat ditutup dan dibuka kembali.
- Statistik: ringkasan terkirim / delivered / read / gagal per device dan mutasi kredit terakhir — fitur Plan Pro. Status delivered dan read diperbarui dari event WhatsApp.
- Top Up & Plan Akun: isi kredit per device dan kelola langganan pool bersama dari dashboard.
FAQ
Apakah Halokirim layanan resmi WhatsApp? Bukan. Halokirim adalah gateway tidak resmi yang bekerja lewat perangkat tertaut. Risiko pembatasan nomor oleh WhatsApp ada pada pemilik nomor; gunakan nomor khusus bisnis dan hanya kirim ke penerima yang bersedia dihubungi.
Pesan gagal apakah tetap memotong kredit? Tidak. Kredit hanya terpotong bila pesan berhasil terkirim: teks 1 kredit, media 3 kredit, gagal 0 kredit.
Apa bedanya top-up per device dengan Plan Akun? Top-up membeli kredit yang menempel pada satu device dan tidak kedaluwarsa. Plan Akun adalah langganan 30 hari berisi pool kredit bersama untuk semua device (dipotong lebih dulu) plus fitur sesuai plan. Keduanya dapat digabung.
Token API saya hilang, bagaimana? Regenerate token dari halaman device. Token lama langsung berhenti berlaku, dan token baru hanya tampil satu kali.
Kenapa API membalas 403? Token Anda valid, tetapi akunnya tidak memiliki fitur API. REST API, autoreply, webhook, rotator, dan statistik adalah fitur Plan Pro.
Apakah ada batas ukuran lampiran? Ya, lampiran dari URL publik dibatasi 25 MB per file.
Berapa lama riwayat pesan saya disimpan? Paling lama 180 hari. Riwayat pesan yang lebih tua dari itu dihapus otomatis secara berkala. Catatan transaksi (top-up dan pembelian plan) disimpan lebih lama untuk kebutuhan pembukuan. Anda juga dapat menghapus akun beserta seluruh data Anda kapan saja dari menu Akun → Zona berbahaya; penghapusan bersifat permanen dan tidak dapat dibatalkan.
Dokumen Lain
- Syarat dan Ketentuan
- Kebijakan Privasi
- Dokumentasi ini dalam format Markdown mentah: /docs.md