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

curl -X POST https://api.example.com/v1/sessions/onboard \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx"

Response:

{
  "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:

curl https://api.example.com/v1/onboard/onb_9c1f... \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx"

Response saat QR siap:

{
  "status": "qr",
  "qr": "2@abc123def456..."
}

Field qr berisi string payload yang perlu dirender menjadi gambar QR code. Contoh sederhana dengan JavaScript di browser:

<!-- 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:

{
  "status": "paired",
  "session_id": "6281200000000@s.whatsapp.net"
}

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)

---

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 120363123456789@g.us. Kode ini yang dipakai sebagai tujuan (to) saat kirim pesan ke grup.

Request

curl "https://api.example.com/v1/sessions/6281200000000%40s.whatsapp.net/groups" \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx"

Kenapa %40?

Karakter @ dalam URL harus ditulis sebagai %40. Jadi 6281200000000@s.whatsapp.net 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

{
  "groups": [
    {
      "jid": "120363123456789@g.us",
      "name": "Tim Marketing"
    },
    {
      "jid": "120363987654321@g.us",
      "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:

curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer wag_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: grup-promo-juli-001" \
  -d '{
    "session_id": "6281200000000@s.whatsapp.net",
    "to": "120363123456789@g.us",
    "text": "Halo Tim Marketing, update terbaru sudah tersedia!"
  }'

---

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.

---

Logout Sesi (Segera Hadir)

Fitur untuk melepas koneksi sesi dan menghapusnya dari gateway akan tersedia dalam waktu dekat.