Unduh .md

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

  1. 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.
  2. 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.
  3. Hubungkan nomor: di halaman device, scan QR dengan WhatsApp (menu Perangkat tertaut) atau minta kode pairing 8 digit lalu masukkan dari ponsel nomor tersebut.
  4. 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.
  5. Mulai kirim: dari halaman device (form kirim uji), halaman Broadcast, atau REST API memakai token device.

Konsep Kredit

Dikirim dari Halokirim

Setelah top-up berbayar pertama pada device itu, watermark hilang permanen untuk device tersebut.

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:

PlanHarga / 30 hariPool bersamaMaks deviceWatermarkFitur
BersamaRp49.0005.000 kredit3tetap adadasar
ProRp149.00015.000 kredit10hilangsemua

Aturan mainnya:

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:

ParameterWajibKeterangan
targetyaNomor tujuan format 628xx, atau JID grup [email protected]. Alias: number, phone
messagebersyaratIsi pesan teks. Alias: text. Menjadi caption bila ada file, dan nama pin bila type location. Wajib kecuali ada file atau type location
filetidakURL publik lampiran (gambar/video/dokumen/audio, maks 25 MB)
filenametidakNama file untuk lampiran dokumen
typetidakIsi "location" untuk mengirim pin lokasi
latitudebersyaratLintang; wajib bila type location
longitudebersyaratBujur; wajib bila type location
devicetidakIsi "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:

HTTPIsi reasonPenyebab
401unauthorized: missing token / invalid tokenHeader Authorization kosong atau token salah
403Fitur API hanya tersedia pada Plan ProAkun token tidak punya fitur API
400target is requiredParameter target tidak dikirim
400message is required (or provide file / type location)Tidak ada message, file, maupun type location
400latitude and longitude are required for type "location"Lokasi tanpa koordinat lengkap
400device is not connectedDevice pengirim belum terhubung ke WhatsApp (detail berisi status device)
402saldo kredit habisSaldo gabungan (pool plan + kredit device) kurang dari biaya pesan
500failed to send messagePengiriman 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:

ParameterWajibKeterangan
targetssalah satuArray nomor tujuan (format 628xx / 08xx diterima, dinormalisasi)
group_idsalah satuID grup kontak milik akun (alias: groupId, group). Boleh digabung dengan targets; duplikat dibuang
messagebersyaratIsi pesan; variabel {nama} dan {nomor} dipersonalisasi per penerima. Alias: text. Wajib kecuali ada file
filetidakURL publik lampiran; message menjadi caption
filenametidakNama file untuk lampiran dokumen
devicetidakSama 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
}
FieldKeterangan
deviceID device penerima pesan
deviceNameNama device penerima pesan
senderNomor pengirim (untuk pesan grup: nomor peserta yang mengirim)
senderNameNama profil WhatsApp pengirim (bisa kosong)
messageIsi teks pesan (atau caption media)
timestampWaktu pesan dalam epoch milidetik
isGrouptrue 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

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