WA Gateway

Appearance

Kirim Pesan ​

Kirim pesan teks atau media WhatsApp ke nomor manapun lewat satu endpoint REST.

Endpoint ​

POST /v1/messages

Header wajib:

HeaderNilai
AuthorizationBearer <api_key>
Content-Typeapplication/json
Idempotency-KeyString unik per percobaan pengiriman (lihat bawah)

Field request body:

FieldTipeWajibKeterangan
session_idstringYaJID sesi pengirim (didapat saat pairing)
tostringYaNomor tujuan — bisa format 628xxx atau JID lengkap 628xxx@s.whatsapp.net
textstringYa*Isi pesan teks
media_typestringYa*Tipe media: image, video, audio, document
media_urlstringYa*URL publik file media (maks 64 MB)
captionstringTidakTeks keterangan di bawah media (image, video, document)
file_namestringTidakNama file tampilan untuk tipe document

*Harus ada salah satu: text atau pasangan media_type + media_url.

Response (202 Accepted):

json
{
  "message_id": "msg_7f3a...",
  "status": "accepted"
}

Status accepted berarti pesan sudah masuk antrean dan akan dikirim. Pengiriman ke WhatsApp terjadi secara asinkron dalam hitungan detik.

Pesan Teks ​

Kirim pesan teks biasa.

bash
curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-notif-1" \
  -d '{
    "session_id": "6281200000000@s.whatsapp.net",
    "to": "628111111111",
    "text": "Pesanan #12345 Anda sedang diproses."
  }'

Pesan Media ​

Server mendownload file dari media_url, menguploadnya ke server WhatsApp, lalu mengirimkan pesan. Pastikan URL dapat diakses secara publik saat permintaan diproses.

Gambar (image) ​

bash
curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: promo-banner-juli-2026" \
  -d '{
    "session_id": "6281200000000@s.whatsapp.net",
    "to": "628111111111",
    "media_type": "image",
    "media_url": "https://cdn.example.com/promo-juli.jpg",
    "caption": "Promo spesial Juli — diskon 30%!"
  }'

Video ​

bash
curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tutorial-video-user-789" \
  -d '{
    "session_id": "6281200000000@s.whatsapp.net",
    "to": "628111111111",
    "media_type": "video",
    "media_url": "https://cdn.example.com/tutorial-onboarding.mp4",
    "caption": "Tutorial cara menggunakan aplikasi kami"
  }'

Audio ​

bash
curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: voice-note-order-456" \
  -d '{
    "session_id": "6281200000000@s.whatsapp.net",
    "to": "628111111111",
    "media_type": "audio",
    "media_url": "https://cdn.example.com/konfirmasi-order.ogg"
  }'

Dokumen (document) ​

bash
curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-june-tenant-101" \
  -d '{
    "session_id": "6281200000000@s.whatsapp.net",
    "to": "628111111111",
    "media_type": "document",
    "media_url": "https://cdn.example.com/invoice-juni-2026.pdf",
    "file_name": "Invoice-Juni-2026.pdf",
    "caption": "Invoice bulan Juni 2026"
  }'

TIP

file_name bersifat opsional — jika tidak diisi, nama file diambil dari segmen terakhir URL (invoice-juni-2026.pdf). Isi file_name jika Anda ingin nama tampilan yang lebih ramah pengguna.

Idempotency Key ​

Header Idempotency-Key wajib disertakan di setiap request.

Mengapa wajib? Jaringan bisa timeout atau koneksi terputus sebelum response diterima. Tanpa idempotency key, retry akan menghasilkan pesan ganda. Dengan key yang sama, server mengenali bahwa ini adalah request yang sama dan mengembalikan hasil asli tanpa mengirim ulang.

Aturan penggunaan:

  • Gunakan string yang unik per percobaan logis — misalnya ID transaksi, ID order, atau UUID.
  • Jika Anda ingin mengirim ulang pesan yang berbeda, gunakan key yang berbeda.
  • Jika koneksi timeout dan Anda tidak yakin apakah pesan terkirim, kirim ulang dengan key yang sama — aman, tidak akan duplikat.
  • Key disimpan selama 24 jam.

Contoh key yang baik:

  • order-12345-shipped-notif
  • otp-user-456-1719340800
  • 550e8400-e29b-41d4-a716-446655440000

Error & Status Code ​

StatusArtinya
202 AcceptedPesan diterima dan masuk antrean
400 Bad RequestRequest body tidak valid atau field wajib kosong
401 UnauthorizedAPI key tidak valid atau tidak disertakan
403 ForbiddenSesi tidak milik akun Anda
409 ConflictIdempotency-Key sudah digunakan untuk pesan yang berbeda
422 Unprocessable EntityToS belum disetujui
429 Too Many RequestsRate limit terlampaui (lihat bawah)
503 Service UnavailableSesi sedang offline atau akun disuspend

Response error selalu dalam format:

json
{
  "error": "deskripsi singkat masalah"
}

Rate Limit ​

Pengiriman dibatasi untuk menjaga kesehatan sesi WhatsApp:

ScopeLimit
Per akun20 pesan/detik, burst hingga 40
Per sesi (nomor)1 pesan/detik, burst hingga 5

Saat limit terlampaui, server merespons 429 Too Many Requests. Implementasikan exponential backoff sebelum retry.

Kirim ke Grup ​

Untuk mengirim pesan ke grup WhatsApp, Anda hanya perlu mengubah nilai to dari nomor pribadi ke JID grup.

Apa itu JID Grup? Setiap grup WhatsApp punya identitas unik yang disebut JID (format 120363xxxxxxxxxx@g.us). JID ini berbeda dari nomor HP — tidak bisa ditebak, harus diambil dari WhatsApp.

Langkah 1 — Ambil daftar grup dari sesi Anda:

Lihat panduan sesi → List Grup untuk cara mengambil JID grup.

Langkah 2 — Kirim pesan ke grup:

Gunakan to berisi JID grup, bukan nomor HP.

bash
curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: notif-grup-flash-sale-1" \
  -d '{
    "session_id": "6281200000000@s.whatsapp.net",
    "to": "120363123456789@g.us",
    "text": "Flash sale dimulai 5 menit lagi! Jangan lewatkan 🎉"
  }'

Anda juga bisa kirim media ke grup — formatnya sama persis, cukup ganti to.

TIP

Sesi WhatsApp Anda harus sudah bergabung di grup tersebut agar pesan bisa terkirim.

Tips Pengiriman yang Aman ​

  • Jangan kirim spam. Pengiriman massal ke nomor yang tidak mengenal pengirim berisiko nomor diblokir oleh WhatsApp.
  • Gunakan nomor yang aktif sebagai sesi. Nomor yang lama tidak aktif bisa kehilangan sesi dan perlu pairing ulang.
  • Pastikan URL media dapat diakses. File harus dapat didownload oleh server saat pesan diproses (bukan URL yang membutuhkan auth atau expires cepat).
  • Pantau quota. Cek dashboard untuk melihat sisa kuota bulan ini.

Dokumentasi WhatsApp Gateway