Appearance
Sesi WhatsApp
Panduan lengkap menghubungkan nomor WhatsApp ke gateway, melihat daftar grup, dan mengelola sesi.
Apa itu Sesi?
Sesi adalah koneksi aktif antara sebuah nomor WhatsApp dan gateway. Anggap saja seperti "menghubungkan WhatsApp Web" — gateway bertindak sebagai perangkat kedua yang terhubung ke akun WhatsApp Anda.
Setelah sesi terhubung, gateway bisa:
- Mengirim pesan atas nama nomor tersebut
- Menerima pesan masuk dan meneruskannya ke webhook Anda
Pairing — Hubungkan Nomor WhatsApp
Proses menghubungkan nomor ke gateway disebut pairing. Caranya adalah memindai QR code, seperti saat Anda menghubungkan WhatsApp Web di komputer.
Langkah 1 — Mulai Proses Pairing
bash
curl -X POST https://api.wagwayapp.com/v1/sessions/onboard \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"Response:
json
{
"onboard_id": "onb_9c1f...",
"status": "pending"
}Simpan onboard_id — dipakai untuk mengambil QR code di langkah berikutnya.
Langkah 2 — Ambil QR Code
Panggil endpoint ini berulang setiap 2-3 detik sampai status menjadi qr:
bash
curl https://api.wagwayapp.com/v1/onboard/onb_9c1f... \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"Response saat QR siap:
json
{
"status": "qr",
"qr": "2@abc123def456..."
}Field qr berisi string payload yang perlu dirender menjadi gambar QR code. Contoh sederhana dengan JavaScript di browser:
html
<!-- Gunakan library qrcode.js -->
<script src="https://cdn.jsdelivr.net/npm/qrcode/build/qrcode.min.js"></script>
<canvas id="qr"></canvas>
<script>
QRCode.toCanvas(document.getElementById('qr'), '2@abc123def456...')
</script>Langkah 3 — Pindai dari WhatsApp
Di ponsel Anda, buka WhatsApp → tiga titik (⋮) → Perangkat Tertaut → Tautkan Perangkat, lalu pindai QR code yang muncul.
QR code berlaku terbatas
QR code kedaluwarsa sekitar 60 detik. Jika Anda terlambat memindai, panggil ulang endpoint poll untuk mendapat QR baru.
Langkah 4 — Tunggu Konfirmasi
Setelah dipindai, status berubah ke paired:
json
{
"status": "paired",
"session_id": "[email protected]"
}Simpan session_id — ini adalah identitas sesi yang dipakai di semua request pengiriman pesan.
Status Pairing
| Status | Artinya |
|---|---|
pending | Proses baru dimulai, QR belum siap |
qr | QR code siap dipindai |
paired | Berhasil terhubung, session_id tersedia |
error | Gagal (QR kedaluwarsa, koneksi bermasalah, dll) |
Pairing dengan Kode (Pairing Code)
Alternatif QR untuk kasus developer ≠ pemegang HP. Developer memulai request dari server, mendapat kode 8 karakter, lalu mengirim kode itu ke pemilik HP untuk diketik langsung — tanpa perlu memindai QR.
Langkah 1 — Minta Kode
Kirim nomor HP target (format internasional tanpa +):
bash
curl -X POST https://api.wagwayapp.com/v1/sessions/paircode \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"phone": "6281200000000"}'Response:
json
{
"onboard_id": "onb_9c1f...",
"status": "pending"
}Langkah 2 — Ambil Kode
Poll GET /v1/onboard/{id} sampai status menjadi code:
bash
curl https://api.wagwayapp.com/v1/onboard/onb_9c1f... \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"json
{
"status": "code",
"code": "ABCD-1234"
}Langkah 3 — Ketik Kode di HP
Pemilik HP membuka WhatsApp → Perangkat Tertaut → Tautkan Perangkat → Tautkan dengan nomor telepon lalu mengetik kode ABCD-1234.
Setelah berhasil, poll yang sama mengembalikan status: "paired" beserta session_id — sama seperti alur QR.
TIP
Status onboarding di-poll lewat endpoint yang sama (GET /v1/onboard/{id}) untuk QR maupun pairing code. Bedakan hasilnya dari field status: qr vs code.
List Grup
Setelah sesi terhubung, Anda bisa mengambil daftar semua grup WhatsApp yang diikuti oleh nomor tersebut. Data ini berguna untuk mengetahui JID grup sebelum mengirim pesan ke grup.
Apa itu JID Grup? Setiap grup punya kode unik seperti [email protected]. Kode ini yang dipakai sebagai tujuan (to) saat kirim pesan ke grup.
Request
bash
curl "https://api.wagwayapp.com/v1/sessions/6281200000000%40s.whatsapp.net/groups" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"Kenapa %40?
Karakter @ dalam URL harus ditulis sebagai %40. Jadi [email protected] menjadi 6281200000000%40s.whatsapp.net di URL.
Sebagian besar HTTP client (axios, fetch, Guzzle, curl dengan opsi --data-urlencode) melakukan ini otomatis. Jika Anda merakit URL secara manual, pastikan encode karakter @-nya.
Response
json
{
"groups": [
{
"jid": "[email protected]",
"name": "Tim Marketing"
},
{
"jid": "[email protected]",
"name": "Flash Sale July"
}
]
}Setiap entri dalam groups:
| Field | Keterangan |
|---|---|
jid | ID unik grup — pakai ini sebagai nilai to saat kirim pesan ke grup |
name | Nama grup sesuai yang terlihat di WhatsApp |
Butuh koneksi aktif
Endpoint ini mengambil data langsung dari WhatsApp. Sesi harus dalam keadaan online dan terhubung. Jika sesi offline, akan dikembalikan 409 Conflict.
Contoh — Kirim Pesan ke Grup
Setelah mendapat JID:
bash
curl -X POST https://api.wagwayapp.com/v1/messages \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: grup-promo-juli-001" \
-d '{
"session_id": "[email protected]",
"to": "[email protected]",
"text": "Halo Tim Marketing, update terbaru sudah tersedia!"
}'Manajemen Grup
Semua endpoint di bawah butuh sesi online (409 bila offline) dan sebagian butuh sesi menjadi admin grup (WhatsApp menolak dengan error bila bukan admin). {id} = JID sesi, {group_id} = JID grup (…@g.us), keduanya di-URL-encode.
Buat Grup
bash
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/groups" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "name": "Tim Marketing", "participants": ["[email protected]"] }'Mengembalikan objek group (JID, nama, peserta, dll). Nama grup maksimal 25 karakter.
Info Detail Grup
bash
curl "https://api.wagwayapp.com/v1/sessions/{id}/groups/{group_id}" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"Kelola Peserta
bash
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/groups/{group_id}/participants" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "participants": ["[email protected]"], "action": "add" }'action: add, remove, promote, demote.
Ubah Nama / Deskripsi
bash
curl -X POST ".../groups/{group_id}/name" -d '{ "name": "Nama Baru" }' ...
curl -X POST ".../groups/{group_id}/description" -d '{ "description": "Deskripsi baru" }' ...Ganti Foto Grup
bash
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/groups/{group_id}/photo" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "image_url": "https://contoh.com/logo.jpg" }'image_url kosong menghapus foto grup. Mengembalikan picture_id.
Link Undangan
bash
# Ambil link (tambahkan ?reset=true untuk mencabut link lama & buat baru)
curl "https://api.wagwayapp.com/v1/sessions/{id}/groups/{group_id}/invite-link" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"
# Gabung grup lewat link/kode undangan
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/groups/join" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "link": "https://chat.whatsapp.com/XXXXXXXX" }'Mute (Announce) & Lock
bash
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/groups/{group_id}/settings" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "announce": true, "locked": false }'announce: true→ hanya admin yang bisa mengirim pesan (grup "mute" untuk anggota).locked: true→ hanya admin yang bisa mengubah info grup (nama/foto/deskripsi).
Sertakan salah satu atau keduanya.
Keluar dari Grup
bash
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/groups/{group_id}/leave" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"Validasi Nomor
Cek apakah nomor terdaftar di WhatsApp sebelum mengirim — hemat kuota dan jaga higiene pengiriman (hindari blast ke nomor mati). Maksimal 50 nomor per permintaan.
Request
bash
curl -X POST "https://api.wagwayapp.com/v1/sessions/6281200000000%40s.whatsapp.net/validate" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "numbers": ["6281234567890", "6289999999999"] }'Nomor boleh dengan atau tanpa awalan + — gateway menormalisasi ke format internasional.
Response
json
{
"results": [
{ "query": "+6281234567890", "jid": "[email protected]", "on_whatsapp": true, "verified_name": "Toko ABC" },
{ "query": "+6289999999999", "on_whatsapp": false }
]
}Setiap entri:
| Field | Keterangan |
|---|---|
query | Nomor yang diminta (sudah dinormalisasi) |
on_whatsapp | true jika nomor terdaftar di WhatsApp |
jid | JID kanonik — pakai ini sebagai to saat mengirim (hanya ada bila terdaftar) |
verified_name | Nama bisnis terverifikasi, bila nomor adalah akun WhatsApp Business |
Membutuhkan koneksi WhatsApp aktif; mengembalikan 409 jika sesi sedang offline.
Kontak & Profil
Semua endpoint butuh sesi online (409 bila offline). {id} = JID sesi, {jid} = JID kontak (di-URL-encode).
Daftar Kontak
bash
curl "https://api.wagwayapp.com/v1/sessions/{id}/contacts" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"Mengembalikan contacts: array { jid, first_name, full_name, push_name, business_name }. Diambil dari cache kontak WhatsApp bawaan (tersinkron otomatis sejak nomor terhubung) — WagWay tidak menyimpan salinan tambahan; kelengkapan nama tergantung riwayat sinkronisasi.
Info Detail User
bash
curl "https://api.wagwayapp.com/v1/sessions/{id}/contacts/{jid}" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"Mengembalikan objek user: status (bio/About), picture_id, verified_name (bila akun bisnis), dan devices.
Foto Profil Kontak
bash
# jid HARUS bare (tanpa suffix device sesi Anda, mis. ":28") — WhatsApp menolak dengan 400
# ?preview=true untuk thumbnail (lebih kecil & cepat)
curl "https://api.wagwayapp.com/v1/sessions/{id}/contacts/{jid}/photo" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"Sukses (200) mengembalikan picture: { has_picture: true, url, id, type }. url link CDN publik WhatsApp, diunduh langsung tanpa auth tambahan (bukan .enc — beda dari media pesan chat yang terenkripsi) — tapi ambil lewat parser JSON, JANGAN copy-paste teks respons mentah ke browser (parameter query URL ini bersambung &; sebagian tool menampilkan versi belum ter-decode, merusak parameter hash → WhatsApp CDN balas "Bad URL hash"). URL kedaluwarsa berkala, jangan simpan permanen.
Kontak/grup tanpa foto bukan 200 has_picture:false, melainkan error: 404 (belum pernah memasang foto) atau 403 (memasang tapi menyembunyikannya dari Anda).
Ubah Bio (About) Sesi
bash
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/profile/status" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "status": "Sibuk, balas nanti 🙏" }'Blocklist
bash
# Lihat daftar blokir
curl "https://api.wagwayapp.com/v1/sessions/{id}/blocklist" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"
# Blokir / buka blokir sebuah nomor
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/blocklist" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "jid": "[email protected]", "action": "block" }'action: block atau unblock. Mengembalikan blocklist terbaru.
Keterbatasan diketahui: akun addressing_mode "lid"
Sebagian akun (yang sudah bermigrasi ke sistem pengalamatan lid WhatsApp) mendapat 400 bad-request untuk endpoint ini terlepas dari format JID yang dikirim. Sudah dicoba JID nomor telepon polos maupun JID @lid hasil terjemahan — WhatsApp menolak keduanya secara identik. Ini keterbatasan whatsmeow/protokol WhatsApp, bukan validasi kita — belum ada workaround yang terbukti berhasil.
Channel / Newsletter
WhatsApp Channel (newsletter) — broadcast satu-arah. Semua endpoint butuh sesi online. Membuat/mengirim butuh sesi sebagai admin channel. {nl} = JID channel (…@newsletter, di-URL-encode).
Buat & Kelola
bash
# Buat channel
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/newsletters" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "name": "Promo WagWay", "description": "Info & promo terbaru", "picture_url": "https://contoh.com/logo.jpg" }'
# Daftar channel yang diikuti
curl ".../v1/sessions/{id}/newsletters" -H "Authorization: Bearer wag_xxxxxxxxxxxx"
# Info satu channel
curl ".../v1/sessions/{id}/newsletters/{nl}" -H "Authorization: Bearer wag_xxxxxxxxxxxx"
# Mute / unmute
curl -X POST ".../v1/sessions/{id}/newsletters/{nl}/mute" -d '{ "mute": true }' ...Objek newsletter: jid, name, description, subscriber_count, invite_code.
Follow / Unfollow
Follow menerima link undangan, kode undangan, atau JID channel di field channel — WhatsApp tak menampilkan JID ke pengguna biasa, jadi untuk channel orang lain cukup pakai link-nya. Responsnya memuat metadata channel (termasuk jid untuk unfollow/mute).
bash
# Follow via link (atau kode / JID) — satu param `channel`
curl -X POST ".../v1/sessions/{id}/newsletters/follow" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"channel":"https://whatsapp.com/channel/XXXX"}'
# Unfollow tetap pakai JID (channel yang sudah diikuti — JID-nya sudah Anda ketahui)
curl -X POST ".../v1/sessions/{id}/newsletters/{nl}/unfollow" -H "Authorization: Bearer wag_xxxxxxxxxxxx"Kirim Pesan ke Channel
Terpisah dari POST /v1/messages (channel = broadcast, bukan chat). Teks atau media.
bash
# Teks
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/newsletters/{nl}/messages" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "text": "Update terbaru sudah rilis 🎉" }'
# Media (image|video|audio|document)
curl -X POST ".../v1/sessions/{id}/newsletters/{nl}/messages" \
-d '{ "media_type": "image", "media_url": "https://contoh.com/promo.jpg", "caption": "Promo Juli" }' ...Mengembalikan message_id.
Reaksi ke Pesan Channel
bash
curl -X POST "https://api.wagwayapp.com/v1/sessions/{id}/newsletters/{nl}/react" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "server_id": 12345, "message_id": "3EB0...", "reaction": "👍" }'server_id = ID server pesan channel (dari event inbound). reaction kosong = hapus reaksi.
Status Sesi
Sesi bisa dalam beberapa kondisi:
| Status | Artinya | Tindakan |
|---|---|---|
| Terhubung | Sesi aktif, siap kirim/terima | — |
| Reconnecting | Sedang mencoba terhubung kembali | Tunggu, otomatis pulih |
| Offline | Koneksi terputus | Cek log, mungkin perlu pairing ulang |
| Logged Out | Nomor di-logout dari perangkat tertaut | Lakukan pairing ulang |
Gateway secara otomatis mencoba reconnect saat koneksi terputus — Anda tidak perlu melakukan apa-apa selama nomor WhatsApp masih aktif.
Typing Indicator
Kirim sinyal "sedang mengetik" agar respons bot terasa lebih natural. Kirim typing: true sesaat sebelum mengirim pesan, lalu typing: false setelahnya (atau biarkan WhatsApp menghapus indikator otomatis setelah ~25 detik).
bash
curl -X POST "https://api.wagwayapp.com/v1/sessions/6281200000000%40s.whatsapp.net/typing" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"to": "[email protected]",
"typing": true
}'| Field | Wajib | Keterangan |
|---|---|---|
to | Ya | JID chat tujuan |
typing | Tidak | true = sedang mengetik (default), false = berhenti |
Berhasil mengembalikan 204 No Content. Seperti List Grup, endpoint ini butuh sesi online — sesi offline mengembalikan 409 Conflict.
Langganan Presence Kontak
Mulai menerima event online/offline sebuah kontak (webhook kind: "presence"). Perlu sekali per kontak; setelahnya perubahan presence kontak itu dikirim ke webhook.
bash
curl -X POST "https://api.wagwayapp.com/v1/sessions/6281200000000%40s.whatsapp.net/presence/subscribe" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "contact_jid": "[email protected]" }'Berhasil mengembalikan 204 No Content. Butuh sesi online (409 bila offline).
Yang perlu diketahui:
- Cukup subscribe sekali per kontak — bukan sesuatu yang perlu dipanggil ulang tiap mau tahu statusnya; setelah didaftarkan, perubahan presence-nya terus mengalir ke
events_url. - Efek samping: memanggil endpoint ini membuat nomor Anda sendiri tampak online ke orang lain sesaat (WhatsApp mensyaratkan sesi online sebelum mau mengirim presence kontak ke Anda).
- Butuh privacy token dari kontak tersebut — biasanya baru ada setelah pernah berinteraksi (chat/terima pesan). Untuk kontak yang belum pernah berinteraksi sama sekali, subscribe bisa saja tetap sukses (
204) tapi presence-nya tidak pernah benar-benar terkirim WhatsApp — paling reliable dipakai untuk kontak yang sudah pernah chat.
Efek samping: nomor tampak online
Untuk menerima presence kontak, WhatsApp mensyaratkan sesi Anda "online". Akibatnya nomor Anda tampak online dan last-seen-nya bisa terlihat kontak lain selama sesi aktif.
Auto-Reject Panggilan
Panggilan masuk selalu diteruskan ke webhook (kind: "call"). Aktifkan auto-reject agar gateway menolak panggilan otomatis (berguna untuk nomor bot).
bash
# Aktifkan
curl -X POST "https://api.wagwayapp.com/v1/sessions/6281200000000%40s.whatsapp.net/calls/auto-reject" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "enabled": true }'
# Cek setelan saat ini
curl "https://api.wagwayapp.com/v1/sessions/6281200000000%40s.whatsapp.net/calls/auto-reject" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"Mengembalikan { "session_id": "...", "auto_reject": true }. Default mati. Setelan berlaku langsung untuk panggilan berikutnya (tak perlu reconnect).
Logout Sesi
Memutus pairing device dari WhatsApp (logout), menghentikan sesi di worker, dan menghapus mapping sesi dari database.
bash
curl -X DELETE "https://api.wagwayapp.com/v1/sessions/6281200000000%40s.whatsapp.net" \
-H "Authorization: Bearer wag_xxxxxxxxxxxx"Berhasil mengembalikan 204 No Content. Ingat URL-encode karakter @ menjadi %40. Jika sesi sudah offline, mapping tetap dihapus dari database.
Tidak dapat dibatalkan
Logout bersifat permanen. Untuk memakai nomor yang sama lagi, Anda harus melakukan pairing ulang dari awal (QR atau pairing code).
