Kirim Pesan

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

Endpoint

POST /v1/messages

Header wajib:

Header	Nilai
`Authorization`	`Bearer <api_key>`
`Content-Type`	`application/json`
`Idempotency-Key`	String unik per percobaan pengiriman (lihat bawah)

Field request body:

Field	Tipe	Wajib	Keterangan
`session_id`	string	Ya	JID sesi pengirim (didapat saat pairing)
`to`	string	Ya	Nomor tujuan — bisa format `628xxx` atau JID lengkap `[email protected]`
`text`	string	Ya*	Isi pesan teks
`media_type`	string	Ya*	Tipe media: `image`, `video`, `audio`, `document`
`media_url`	string	Ya*	URL publik file media (maks 64 MB)
`caption`	string	Tidak	Teks keterangan di bawah media (image, video, document)
`file_name`	string	Tidak	Nama file tampilan untuk tipe `document`

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

Untuk lokasi, kontak, reaksi, dan reply/quote, lihat Jenis Pesan Lanjutan.

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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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-user-101" \
  -d '{
    "session_id": "[email protected]",
    "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.

Jenis Pesan Lanjutan

Selain teks dan media, satu endpoint yang sama mendukung lokasi, kontak, reaksi, dan reply/quote. Pilih jenisnya lewat field type (kecuali reply/quote yang ditambahkan ke pesan teks/media biasa).

Lokasi (`type: "location"`)

Kirim pin lokasi. Wajib latitude + longitude; loc_name dan loc_address opsional.

bash

curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lokasi-toko-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "type": "location",
    "latitude": -6.2088,
    "longitude": 106.8456,
    "loc_name": "Kantor Pusat",
    "loc_address": "Jl. Sudirman No. 1, Jakarta"
  }'

Kontak (`type: "contact"`)

Kirim kartu kontak. Wajib display_name + vcard (string vCard RFC 2426 lengkap).

bash

curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kontak-cs-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "type": "contact",
    "display_name": "Budi Santoso",
    "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Budi Santoso\nTEL:+628111111111\nEND:VCARD"
  }'

Reaksi Emoji (`type: "reaction"`)

Beri reaksi emoji ke pesan tertentu. Wajib reacted_message_id + emoji. Kirim emoji kosong ("") untuk menghapus reaksi. Untuk grup, sertakan juga reacted_participant (JID pengirim asli) dan reacted_from_me.

bash

curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: react-msg-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "type": "reaction",
    "reacted_message_id": "3EB0F1A2B3C4D5E6F7",
    "emoji": "👍"
  }'

reacted_message_id diambil dari field message_id pada webhook pesan masuk (lihat panduan webhook).

Reply / Quote

Balas sambil mengutip pesan sebelumnya. Tambahkan quoted_message_id ke pesan teks atau media biasa. Untuk grup, wajib juga quoted_participant. quoted_text mengisi pratinjau di dalam gelembung kutipan (kosongkan saat mengutip media).

bash

curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-msg-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "text": "Tentu, ini detailnya 👇",
    "quoted_message_id": "3EB0F1A2B3C4D5E6F7",
    "quoted_participant": "[email protected]",
    "quoted_text": "Ada yang bisa saya bantu?"
  }'

Ketiga field quoted_* diambil langsung dari payload webhook pesan masuk: message_id → quoted_message_id, sender_jid → quoted_participant, text → quoted_text. Inilah pola dasar bot dua arah — terima pesan, balas sambil mengutipnya.

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

Status	Artinya
`202 Accepted`	Pesan diterima dan masuk antrean
`400 Bad Request`	Request body tidak valid atau field wajib kosong
`401 Unauthorized`	API key tidak valid atau tidak disertakan
`403 Forbidden`	ToS belum disetujui, akun disuspend, atau sesi bukan milik akun Anda
`409 Conflict`	Sesi sedang offline (tidak dihosting worker mana pun)
`429 Too Many Requests`	Kuota habis atau rate limit terlampaui (lihat bawah)
`502 Bad Gateway`	Gagal memasukkan ke antrean — aman di-retry dengan `Idempotency-Key` yang sama

Tabel ini selaras dengan halaman referensi error. Khusus 502: ini satu-satunya kasus yang harus Anda retry, dan retry wajib memakai Idempotency-Key yang sama agar pesan tidak terkirim dua kali.

Response error selalu dalam format:

json

{
  "error": "deskripsi singkat masalah"
}

Rate Limit

Pengiriman dibatasi untuk menjaga kesehatan sesi WhatsApp:

Scope	Limit
Per akun	20 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 [email protected]). 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": "[email protected]",
    "to": "[email protected]",
    "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 pada periode langganan berjalan.

Kirim Pesan ​

Endpoint ​

Pesan Teks ​

Pesan Media ​

Gambar (image) ​

Video ​

Audio ​

Dokumen (document) ​

Jenis Pesan Lanjutan ​

Lokasi (type: "location") ​

Kontak (type: "contact") ​

Reaksi Emoji (type: "reaction") ​

Reply / Quote ​

Idempotency Key ​

Error & Status Code ​

Rate Limit ​

Kirim ke Grup ​

Tips Pengiriman yang Aman ​

Kirim Pesan

Endpoint

Pesan Teks

Pesan Media

Gambar (image)

Video

Audio

Dokumen (document)

Jenis Pesan Lanjutan

Lokasi (`type: "location"`)

Kontak (`type: "contact"`)

Reaksi Emoji (`type: "reaction"`)

Reply / Quote

Idempotency Key

Error & Status Code

Rate Limit

Kirim ke Grup

Tips Pengiriman yang Aman