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, hapus pesan, stiker, edit, polling, disappearing messages, teruskan (forward), 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.wagwayapp.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 mengunduh file dari media_url, mengunggahnya ke server WhatsApp, lalu mengirimkan pesan. Pastikan URL dapat diakses secara publik saat permintaan diproses.

Gambar (image)

bash

curl -X POST https://api.wagwayapp.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.wagwayapp.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.wagwayapp.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.wagwayapp.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.wagwayapp.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.wagwayapp.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.wagwayapp.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).

Hapus Pesan / Unsend (`type: "revoke"`)

Hapus pesan untuk semua pihak (bukan hanya lokal). Wajib revoked_message_id.

bash

curl -X POST https://api.wagwayapp.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: revoke-msg-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "type": "revoke",
    "revoked_message_id": "3EB0F1A2B3C4D5E6F7",
    "revoked_from_me": true
  }'

revoked_from_me wajib true untuk menghapus pesan yang dikirim sendiri oleh sesi ini. Untuk pesan grup, sertakan juga revoked_participant (JID pengirim asli) — menghapus pesan orang lain hanya diizinkan WhatsApp untuk admin grup.

Stiker (`type: "sticker"`)

Kirim stiker .webp (diam atau animasi). Wajib sticker_url — URL publik file .webp; server mengunduh lalu mengunggahnya ke WhatsApp. Format selain webp ditolak.

bash

curl -X POST https://api.wagwayapp.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sticker-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "type": "sticker",
    "sticker_url": "https://contoh.com/stiker.webp"
  }'

Stiker termasuk lampiran (attachment) — paket Free hanya mendukung teks.

Edit Pesan (`type: "edit"`)

Ubah teks pesan yang sudah terkirim (hanya pesan yang dikirim sesi ini, dalam jendela 20 menit WhatsApp). to = JID chat pesan asli, edit_message_id = message ID pesan yang diedit, text = isi baru.

bash

curl -X POST https://api.wagwayapp.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: edit-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "type": "edit",
    "edit_message_id": "3EB0F1A2B3C4D5E6F7",
    "text": "Teks yang sudah diperbaiki"
  }'

Polling / Voting (`type: "poll"`)

Buat polling multi-opsi. Wajib poll_name dan poll_options (minimal 2). poll_selectable_count = jumlah opsi maksimum yang boleh dipilih pemilih (1 = pilihan tunggal; 0 = tak dibatasi).

bash

curl -X POST https://api.wagwayapp.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: poll-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "type": "poll",
    "poll_name": "Rapat hari apa?",
    "poll_options": ["Senin", "Selasa", "Rabu"],
    "poll_selectable_count": 1
  }'

Menghitung suara masuk dilakukan lewat webhook pesan masuk (bukan endpoint ini).

Disappearing Messages (`type: "disappearing"`)

Aktif/nonaktifkan timer self-destruct sebuah chat. to = JID chat, disappearing_timer salah satu dari off, 24h, 7d, 90d. Ini setelan chat, bukan pesan — response tidak mengembalikan message_id.

bash

curl -X POST https://api.wagwayapp.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: disappear-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "type": "disappearing",
    "disappearing_timer": "7d"
  }'

Status / Story (`type: "status"`)

Posting ke Status/Story WhatsApp. status_type salah satu dari text, image, video. Field to tidak dipakai (status disiarkan, bukan dikirim ke satu nomor) — boleh dikosongkan.

bash

# Status teks
curl -X POST https://api.wagwayapp.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: status-001" \
  -d '{
    "session_id": "[email protected]",
    "type": "status",
    "status_type": "text",
    "text": "Halo dari status! 👋"
  }'

# Status gambar (pakai media_url + caption opsional)
curl -X POST https://api.wagwayapp.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: status-002" \
  -d '{
    "session_id": "[email protected]",
    "type": "status",
    "status_type": "image",
    "media_url": "https://contoh.com/promo.jpg",
    "caption": "Promo hari ini"
  }'

Penerima diambil dari kontak perangkat

WhatsApp menentukan siapa yang melihat status dari daftar kontak perangkat + setelan privasi status. Sesi gateway yang belum punya kontak tersimpan akan memposting status yang tidak terlihat siapa pun. Status image/video termasuk lampiran — paket Free hanya mendukung teks.

Undangan Grup (`type: "group_invite"`)

Kirim undangan grup sebagai bubble (bukan sekadar teks link). Wajib group_invite_jid (JID grup, …@g.us); kode & nama grup diambil otomatis oleh server. caption opsional. Sesi harus admin grup tersebut.

bash

curl -X POST https://api.wagwayapp.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ginvite-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "[email protected]",
    "type": "group_invite",
    "group_invite_jid": "[email protected]",
    "caption": "Yuk gabung grup kami!"
  }'

Pesan Interaktif / Tombol (`type: "interactive"`)

EKSPERIMENTAL — tanpa jaminan

Tombol memakai format NativeFlow yang tidak resmi. WhatsApp mematikan ButtonsMessage/ListMessage lama sejak 2023; format pengganti ini hanya diketahui dari diskusi komunitas dan bisa berhenti dirender kapan saja saat WhatsApp update. Rendering tidak konsisten antar platform — sering muncul di iOS/Web/Desktop tapi tidak di Android. Fitur ini best-effort, bukan bagian dari SLA. Uji ke perangkat target Anda sebelum mengandalkannya. Butuh paket Pro ke atas.

Wajib interactive_body (teks utama) dan interactive_buttons (1–3 tombol). interactive_footer opsional. Setiap tombol punya type:

`type`	Field wajib	Perilaku
`quick_reply`	`id`	Balasan cepat; `id` dikembalikan lewat webhook saat ditekan.
`cta_url`	`url`	Buka tautan.
`cta_copy`	`copy_code`	Salin teks ke clipboard.
`cta_call`	`phone_number`	Panggil nomor.
`single_select`	`sections`	Daftar pilihan (dropdown).

bash

curl -X POST https://api.wagwayapp.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: interactive-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "type": "interactive",
    "interactive_body": "Konfirmasi pesanan Anda?",
    "interactive_footer": "Powered by WagWay",
    "interactive_buttons": [
      { "type": "quick_reply", "display_text": "Ya", "id": "confirm_yes" },
      { "type": "quick_reply", "display_text": "Batal", "id": "confirm_no" },
      { "type": "cta_url", "display_text": "Lihat detail", "url": "https://toko.example/order/123" }
    ]
  }'

Ketika penerima menekan tombol, balasannya masuk ke webhook sebagai type: "button_response" dengan objek button_response (selected_id, selected_text, params_json). Cocokkan selected_id dengan id tombol yang Anda kirim untuk tahu pilihan mereka.

Teruskan (Forward)

Tandai pesan teks atau media biasa sebagai "Diteruskan". Tambahkan "forwarded": true — ini modifier, bukan type tersendiri. Karena kami tidak menyimpan pesan asli, Anda menyediakan sendiri konten yang diteruskan (teks atau media_url).

bash

curl -X POST https://api.wagwayapp.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: forward-001" \
  -d '{
    "session_id": "[email protected]",
    "to": "628111111111",
    "text": "Info penting yang diteruskan",
    "forwarded": true
  }'

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.wagwayapp.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.wagwayapp.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 diunduh oleh server saat pesan diproses (bukan URL yang membutuhkan auth atau expires cepat).
Pantau kuota. 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") ​

Hapus Pesan / Unsend (type: "revoke") ​

Stiker (type: "sticker") ​

Edit Pesan (type: "edit") ​

Polling / Voting (type: "poll") ​

Disappearing Messages (type: "disappearing") ​

Status / Story (type: "status") ​

Undangan Grup (type: "group_invite") ​

Pesan Interaktif / Tombol (type: "interactive") ​

Teruskan (Forward) ​

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"`)

Hapus Pesan / Unsend (`type: "revoke"`)

Stiker (`type: "sticker"`)

Edit Pesan (`type: "edit"`)

Polling / Voting (`type: "poll"`)

Disappearing Messages (`type: "disappearing"`)

Status / Story (`type: "status"`)

Undangan Grup (`type: "group_invite"`)

Pesan Interaktif / Tombol (`type: "interactive"`)

Teruskan (Forward)

Reply / Quote

Idempotency Key

Error & Status Code

Rate Limit

Kirim ke Grup

Tips Pengiriman yang Aman