Langsung ke konten

Untuk developer

Dokumentasi API

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.

  1. 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.
  2. Pilih masa berlaku key (30 hari, 90 hari, 1 tahun, atau tanpa batas).
  3. Pilih scope: read untuk membaca data, write untuk mengirim pesan dan mengubah kontak, atau keduanya.
  4. 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 }
}

Kontak

GET /contacts scope: read

Daftar kontak

Parameter: page, limit (bawaan 20), search (nama atau nomor), label, is_blocked.

Respons

{
  "success": true,
  "data": [ { "id": "4d7a…", "phone_number": "6281234567890", "name": "Budi", "labels": ["VIP"], "metadata": {} } ],
  "meta": { "page": 1, "limit": 20, "total": 1 }
}
GET /contacts/{id} scope: read

Detail kontak

Satu kontak.

GET /contacts/labels scope: read

Daftar label

Label yang tersedia untuk kontak.

POST /contacts scope: write

Tambah kontak

Nomor ditulis dengan kode negara. Jika nomor sudah tersimpan, respons 409 berisi kontak yang sudah ada.

Body

{
  "whatsapp_account_id": "6f1c…",
  "phone_number": "+6281234567890",
  "name": "Budi",
  "labels": ["Pelanggan"],
  "metadata": { "kota": "Bekasi" }
}
PUT /contacts/{id} scope: write

Ubah kontak

Ubah nama atau label. Metadata digabung dengan yang sudah ada; status berhenti berlangganan (STOP) dan blokir kontak hanya bisa diubah dari dashboard.

Body

{ "name": "Budi Santoso", "labels": ["VIP"] }

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": { … }
}
EventKapan dikirim
message.receivedPesan masuk dari pelanggan
message.sentPesan terkirim dari HalloWa
message.deliveredPesan sampai ke HP pelanggan
message.readPesan dibaca pelanggan
message.failedPesan gagal terkirim
conversation.newPercakapan baru dibuat
contact.newKontak baru dibuat
contact.updatedKontak diubah
broadcast.completedBroadcast selesai dikirim
broadcast.failedBroadcast 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": "…" }.

HTTPKodeArtinya
400VALIDATION_FAILED, INVALID_REQUESTIsi request tidak valid
401INVALID_API_KEYAPI key salah atau tidak dikenal
401API_KEY_REVOKED, API_KEY_EXPIREDKey sudah dicabut atau kedaluwarsa
403API_KEY_SCOPEKey tidak punya scope yang dibutuhkan (read atau write)
403API_KEY_FORBIDDENEndpoint ini tidak bisa dipanggil dengan API key
403PLAN_REQUIREDPaket Anda belum termasuk akses API
404NOT_FOUNDData tidak ditemukan di akun Anda
403QUOTA_EXCEEDEDKuota pesan bulan ini atau batas kontak paket Anda sudah habis (field resource: messages atau contacts)
400INVALID_IDEMPOTENCY_KEYFormat header Idempotency-Key tidak valid
409IDEMPOTENCY_IN_PROGRESSRequest pertama dengan Idempotency-Key yang sama masih diproses; coba lagi setelah waktu di header Retry-After
422IDEMPOTENCY_KEY_REUSEDIdempotency-Key sudah dipakai untuk request dengan isi berbeda
429RATE_LIMITEDMelewati batas request per menit; coba lagi setelah waktu di header Retry-After
429TOO_MANY_FAILED_KEYSTerlalu banyak key salah dari alamat IP yang sama; coba lagi setelah waktu di header Retry-After
503SERVICE_UNAVAILABLEGangguan 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