Skip to content

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

StatusArtinya
pendingProses baru dimulai, QR belum siap
qrQR code siap dipindai
pairedBerhasil terhubung, session_id tersedia
errorGagal (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:

FieldKeterangan
jidID unik grup — pakai ini sebagai nilai to saat kirim pesan ke grup
nameNama 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.

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:

FieldKeterangan
queryNomor yang diminta (sudah dinormalisasi)
on_whatsapptrue jika nomor terdaftar di WhatsApp
jidJID kanonik — pakai ini sebagai to saat mengirim (hanya ada bila terdaftar)
verified_nameNama 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:

StatusArtinyaTindakan
TerhubungSesi aktif, siap kirim/terima
ReconnectingSedang mencoba terhubung kembaliTunggu, otomatis pulih
OfflineKoneksi terputusCek log, mungkin perlu pairing ulang
Logged OutNomor di-logout dari perangkat tertautLakukan 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
  }'
FieldWajibKeterangan
toYaJID chat tujuan
typingTidaktrue = 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).

Produk independen — tidak terafiliasi dengan Meta Platforms, Inc. atau WhatsApp Inc.