Untuk developer
Kirim pesan dan template WhatsApp, kelola kontak, dan baca percakapan dari sistem Anda. Terima pemberitahuan setiap ada chat baru lewat webhook.
Alamat dasar API (ditulis di kode program Anda, bukan untuk dibuka di browser):
https://api.hallowa.app/api/v1
Daftar isi
Autentikasi
Setiap request memakai API key di header Authorization. Akses API tersedia mulai paket Starter.
- Pemilik akun membuka Pengaturan → Kunci API, lalu klik Buat key (maksimal 10 key aktif). Demi keamanan, Anda diminta memasukkan password dan kode 2FA (bila aktif); akun yang masuk lewat Google/Facebook cukup login ulang dalam 15 menit terakhir.
- Pilih masa berlaku key (30 hari, 90 hari, 1 tahun, atau tanpa batas).
- Pilih scope:
read untuk membaca data, write untuk mengirim pesan dan mengubah kontak, atau keduanya. - Salin key-nya. Key hanya ditampilkan sekali; simpan di server Anda, jangan di aplikasi browser atau HP.
Authorization: Bearer hwk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Key yang bocor bisa dicabut kapan saja dari halaman yang sama dan langsung berhenti berlaku. API key hanya bisa memanggil endpoint di halaman ini; pengaturan akun, tim, dan tagihan tetap hanya lewat dashboard. Membaca riwayat pesan lewat API tidak menandai pesan sebagai dibaca, dan setiap pesan yang dikirim lewat API dicatat beserta key-nya.
Panduan cepat
1. Ambil id nomor WhatsApp
curl https://api.hallowa.app/api/v1/whatsapp/accounts \
-H "Authorization: Bearer $HALLOWA_API_KEY"
2. Kirim template
curl -X POST https://api.hallowa.app/api/v1/messages/send-template \
-H "Authorization: Bearer $HALLOWA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"whatsapp_account_id": "ID_NOMOR", "to": "6281234567890",
"template_name": "hello_world", "language": "en_US"}'
3. Terima pesan masuk
Daftarkan URL server Anda di menu Webhooks. HalloWa akan mengirim pemberitahuan setiap ada pesan masuk dan perubahan status pesan.
Nomor & template
GET /whatsapp/accounts scope: read
Daftar nomor WhatsApp
Nomor yang terhubung di akun Anda. Pakai id-nya sebagai whatsapp_account_id saat mengirim pesan.
Respons
{
"success": true,
"data": [
{ "id": "6f1c…", "name": "Toko Berkah", "phone_number": "+62 812-3456-7890", "status": "active" }
]
}
GET /whatsapp/accounts/{id}/templates scope: read
Daftar template
Template milik nomor tersebut beserta status persetujuan Meta (APPROVED, PENDING, REJECTED), sesuai sinkron terakhir di dashboard.
Respons
{
"success": true,
"count": 1,
"data": [
{ "name": "konfirmasi_pesanan", "language": "id", "category": "UTILITY", "status": "APPROVED", "components": [ … ] }
]
}
Pesan
Pesan bebas (teks, gambar, dokumen) hanya bisa dikirim dalam 24 jam setelah pelanggan terakhir mengirim pesan. Di luar itu, pakai template yang sudah disetujui.
POST /messages/send-template scope: write
Kirim template
Memulai percakapan atau mengirim notifikasi, misalnya konfirmasi pesanan. Komponen mengikuti format template WhatsApp. Sertakan header Idempotency-Key agar request yang diulang setelah timeout tidak mengirim pesan ganda.
Body
{
"whatsapp_account_id": "6f1c…",
"to": "6281234567890",
"template_name": "konfirmasi_pesanan",
"language": "id",
"components": [
{ "type": "body", "parameters": [
{ "type": "text", "text": "Budi" },
{ "type": "text", "text": "INV-1024" }
] }
]
}
Respons
{ "success": true, "message_id": "wamid.HBgM…", "data": { "id": "c2a1…", "status": "sent", … } }
POST /messages/send scope: write
Kirim pesan
Jenis: text, image, video, audio, document. Teks memakai content.body; media memakai content.link (URL https publik) dan content.caption.
Body
{
"whatsapp_account_id": "6f1c…",
"to": "6281234567890",
"type": "text",
"content": { "body": "Pesanan Anda sudah dikirim hari ini." }
}
Respons
{ "success": true, "message_id": "wamid.HBgM…", "data": { "id": "c2a1…", "status": "sent", … } }
POST /conversations/{id}/send-template scope: write
Kirim template ke percakapan
Sama seperti kirim template, tetapi nomor dan penerima diambil dari percakapan. Isi variabel di params.body: source static (dengan value), contact_name, atau contact_phone.
Body
{
"template_name": "pengingat_jadwal",
"language": "id",
"params": { "body": [
{ "source": "contact_name", "fallback": "Kak" },
{ "source": "static", "value": "Senin, 10.00" }
] }
}
GET /messages/{id} scope: read
Status pesan
Status terakhir pesan: sent, delivered, read, atau failed. Untuk pembaruan langsung, pakai webhook.
Percakapan
GET /conversations scope: read
Daftar percakapan
Parameter: page, limit (bawaan 20), status, search, whats_app_account_id.
Respons
{
"success": true,
"data": [ { "id": "9b0e…", "status": "open", "contact": { … }, "last_message_at": "2026-10-09T08:15:00Z", "unread_count": 2 } ],
"meta": { "page": 1, "limit": 20, "total": 1 }
}
GET /conversations/{id} scope: read
Detail percakapan
Satu percakapan beserta kontaknya.
GET /conversations/{id}/messages scope: read
Riwayat pesan
Pesan dalam percakapan. Parameter: page, limit (bawaan 50).
Respons
{
"success": true,
"data": [ { "id": "c2a1…", "direction": "inbound", "type": "text", "content": { "body": "Masih ada ukuran M?" }, "status": "read", "created_at": "…" } ],
"meta": { "page": 1, "limit": 50, "total": 12 }
}
Kirim ulang dengan aman
Koneksi bisa putus setelah pesan terkirim tetapi sebelum respons sampai ke server Anda. Agar request yang diulang tidak mengirim pesan dua kali, sertakan header Idempotency-Key berisi ID unik buatan Anda, misalnya nomor pesanan atau UUID. Header ini berlaku di endpoint kirim pesan, kirim template, dan tambah kontak.
curl -X POST https://api.hallowa.app/api/v1/messages/send-template \
-H "Authorization: Bearer $HALLOWA_API_KEY" \
-H "Idempotency-Key: notif-INV-1024" \
-H "Content-Type: application/json" \
-d '{"whatsapp_account_id": "ID_NOMOR", "to": "6281234567890",
"template_name": "konfirmasi_pesanan", "language": "id"}'
- Request dengan key yang sama dalam 24 jam tidak dijalankan lagi. Anda menerima respons pertama beserta header
Idempotent-Replayed: true. - Key yang sama untuk isi request yang berbeda ditolak dengan
422 IDEMPOTENCY_KEY_REUSED. - Jika request pertama masih diproses, request ulang dijawab
409 IDEMPOTENCY_IN_PROGRESS. Tunggu sesuai header Retry-After, lalu ulangi. - Hanya respons sukses yang disimpan. Setelah respons gagal (4xx atau 5xx), key yang sama boleh dipakai lagi begitu penyebabnya diperbaiki.
- Key berisi 1–100 karakter (huruf, angka,
- _ . :) dan berlaku per akun.
Webhook
Atur URL tujuan dan pilih event di menu Webhooks. URL harus memakai https. Setiap event dikirim sebagai POST JSON:
{
"id": "d3b7…",
"event": "message.received",
"created_at": "2026-10-09T08:15:00Z",
"data": { … }
}
| Event | Kapan dikirim |
|---|
message.received | Pesan masuk dari pelanggan |
message.sent | Pesan terkirim dari HalloWa |
message.delivered | Pesan sampai ke HP pelanggan |
message.read | Pesan dibaca pelanggan |
message.failed | Pesan gagal terkirim |
conversation.new | Percakapan baru dibuat |
contact.new | Kontak baru dibuat |
contact.updated | Kontak diubah |
broadcast.completed | Broadcast selesai dikirim |
broadcast.failed | Broadcast gagal |
Memastikan kiriman asli
Setiap kiriman membawa header X-HalloWa-Event, X-HalloWa-Delivery, X-HalloWa-Timestamp, dan X-HalloWa-Signature. Tanda tangan dihitung dari secret webhook Anda:
X-HalloWa-Signature: sha256=HEX( HMAC_SHA256(secret, timestamp + "." + body) )
Bandingkan dengan perbandingan waktu-konstan, dan tolak kiriman dengan timestamp yang terlalu lama. Kiriman yang gagal dikirim ulang otomatis dengan jeda yang makin panjang (paling lama 30 menit), dan riwayat pengiriman bisa dilihat di dashboard.
Kode error
Respons gagal selalu berisi { "success": false, "error": "KODE", "message": "…" }.
| HTTP | Kode | Artinya |
|---|
| 400 | VALIDATION_FAILED, INVALID_REQUEST | Isi request tidak valid |
| 401 | INVALID_API_KEY | API key salah atau tidak dikenal |
| 401 | API_KEY_REVOKED, API_KEY_EXPIRED | Key sudah dicabut atau kedaluwarsa |
| 403 | API_KEY_SCOPE | Key tidak punya scope yang dibutuhkan (read atau write) |
| 403 | API_KEY_FORBIDDEN | Endpoint ini tidak bisa dipanggil dengan API key |
| 403 | PLAN_REQUIRED | Paket Anda belum termasuk akses API |
| 404 | NOT_FOUND | Data tidak ditemukan di akun Anda |
| 403 | QUOTA_EXCEEDED | Kuota pesan bulan ini atau batas kontak paket Anda sudah habis (field resource: messages atau contacts) |
| 400 | INVALID_IDEMPOTENCY_KEY | Format header Idempotency-Key tidak valid |
| 409 | IDEMPOTENCY_IN_PROGRESS | Request pertama dengan Idempotency-Key yang sama masih diproses; coba lagi setelah waktu di header Retry-After |
| 422 | IDEMPOTENCY_KEY_REUSED | Idempotency-Key sudah dipakai untuk request dengan isi berbeda |
| 429 | RATE_LIMITED | Melewati batas request per menit; coba lagi setelah waktu di header Retry-After |
| 429 | TOO_MANY_FAILED_KEYS | Terlalu banyak key salah dari alamat IP yang sama; coba lagi setelah waktu di header Retry-After |
| 503 | SERVICE_UNAVAILABLE | Gangguan sementara, coba lagi sebentar lagi |
Batas rate
Setiap API key bisa mengirim 100 request per menit. Sisa jatah ada di header X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Request yang melewati batas dijawab 429 RATE_LIMITED dengan header Retry-After (detik).
Kuota paket
Pesan yang dikirim lewat API dihitung dalam kuota pesan keluar bulanan paket Anda (bulan kalender WIB). Saat kuota habis, request kirim dijawab 403 QUOTA_EXCEEDED sampai bulan berikutnya atau sampai upgrade; balasan yang diketik tim di kotak masuk tetap bisa dikirim. Menambah kontak juga dibatasi jumlah kontak paket. Rinciannya ada di halaman harga.
Di luar itu berlaku batas kirim dari WhatsApp untuk pesan yang Anda mulai lebih dulu.
Butuh bantuan integrasi?
Ceritakan sistem yang ingin Anda sambungkan, tim kami bantu lewat WhatsApp.
Tanya lewat WhatsApp