Cara Mengecek Status Koneksi Device melalui Webhook WhatsApp

Cara Mengecek Status Koneksi Device melalui Webhook WhatsApp perlu diketahui sebab aplikasi bergantung pada device yang harus tetap terhubung untuk menerima atau mengirim pesan. Webhook dapat digunakan untuk menerima event perubahan status dari API sehingga aplikasi dapat mengetahui ketika device terhubung, terputus, atau mengalami perubahan koneksi.

Tanpa webhook, aplikasi biasanya harus melakukan pengecekan status secara berkala. Dengan webhook, server dapat menerima event ketika terjadi perubahan status.

Alur dasarnya:

Device WhatsApp
      ↓
Perubahan status koneksi
      ↓
API Whapi
      ↓
Webhook
      ↓
Server
      ↓
Update status device

Apa Itu Status Koneksi Device?

Status koneksi device menunjukkan kondisi device WhatsApp yang digunakan oleh API.

Contohnya:

CONNECTED
DISCONNECTED

Status tersebut dapat digunakan aplikasi untuk menentukan apakah device siap digunakan.

Contoh penggunaan:

• Menampilkan status device pada dashboard.
• Memberi tanda ketika device terputus.
• Menghentikan proses pengiriman sementara.
• Menjalankan proses ketika device kembali terhubung.
• Mencatat riwayat koneksi.
• Mengirim notifikasi kepada administrator.

Status koneksi tidak sama dengan status pesan. Status koneksi menunjukkan kondisi device, sedangkan status pesan menunjukkan kondisi pesan seperti terkirim atau gagal.

Mengapa Status Device Perlu Dipantau?

Aplikasi yang menggunakan WhatsApp API biasanya memiliki proses yang bergantung pada koneksi device.

Misalnya sistem memiliki antrean pengiriman:

Pesan masuk ke queue
       ↓
Device CONNECTED?
    ↙       ↘
  Ya        Tidak
  ↓           ↓
Kirim      Tunggu

Jika aplikasi tidak mengetahui status device, sistem dapat terus mencoba mengirim pesan meskipun device sedang terputus.

Dengan menerima event perubahan status melalui webhook, aplikasi dapat memperbarui status secara otomatis.

Buat Endpoint Webhook

Langkah pertama adalah menyediakan endpoint yang dapat menerima request dari Whapi.

Contoh menggunakan Node.js dan Express:

const express = require('express');

const app = express();

app.use(express.json());

app.post('/webhook/whatsapp', (req, res) => {
  console.log('Webhook diterima');
  console.log(JSON.stringify(req.body, null, 2));

  res.sendStatus(200);
});

app.listen(3000, () => {
  console.log('Server berjalan di port 3000');
});

Endpoint tersebut:

POST /webhook/whatsapp

digunakan untuk menerima event dari API.

Pada tahap awal, tampilkan seluruh payload terlebih dahulu. Tujuannya agar struktur event yang diterima dapat diperiksa sebelum kode dibuat untuk membaca field tertentu.

Konfigurasi URL Webhook

Setelah endpoint tersedia, gunakan URL publik endpoint tersebut pada konfigurasi webhook Whapi.

Contoh:

https://example.com/webhook/whatsapp

Pastikan URL dapat diakses dari internet dan server dapat menerima request POST.

Jangan menggunakan:

http://localhost:3000/webhook/whatsapp

untuk endpoint production karena localhost hanya dapat diakses dari mesin yang menjalankan server tersebut.

Membaca Event Status Device

Setelah webhook aktif, periksa payload yang diterima ketika status device berubah.

Gunakan log:

app.post('/webhook/whatsapp', (req, res) => {
  console.log(
    JSON.stringify(req.body, null, 2)
  );

  res.sendStatus(200);
});

Contoh hasil log dapat digunakan untuk mengetahui struktur event yang dikirim API.

Jangan langsung mengasumsikan nama field status sebelum payload aktual diperiksa. Struktur data harus mengikuti event yang dikirim oleh versi API yang digunakan.

Menyimpan Status Device

Setelah struktur event diketahui, status device dapat disimpan pada database.

Contoh alurnya:

Event webhook
      ↓
Ambil status
      ↓
Cari device
      ↓
Update database

Contoh pseudo-code:

const status = getDeviceStatus(req.body);

if (status) {
  await updateDeviceStatus(status);
}

Fungsi getDeviceStatus() perlu disesuaikan dengan struktur payload webhook yang diterima.

Data pada database dapat dibuat seperti:

Device	Status	Updated At
Device 01	CONNECTED	2026-09-30 09:30
Device 02	DISCONNECTED	2026-09-30 09:27

Dengan data tersebut, dashboard dapat menampilkan status terbaru setiap device.

Menampilkan Status pada Dashboard

Status webhook dapat digunakan untuk membuat halaman monitoring.

Contoh:

WhatsApp Device

Device 01
Status: CONNECTED

Device 02
Status: DISCONNECTED

Ketika event baru diterima, aplikasi memperbarui data pada database.

Alurnya:

Device berubah status
        ↓
Webhook menerima event
        ↓
Database diperbarui
        ↓
Dashboard membaca status terbaru

Dashboard tidak perlu menunggu pengguna melakukan refresh jika aplikasi menggunakan WebSocket, Server-Sent Events, atau mekanisme pembaruan data lainnya.

Membuat Notifikasi Saat Device Terputus

Status webhook juga dapat digunakan untuk memberi tahu administrator.

Contohnya:

Device WhatsApp terputus

Device: Device 01
Status: DISCONNECTED

Periksa koneksi device sebelum melanjutkan pengiriman pesan.

Alurnya:

Status berubah
      ↓
Webhook
      ↓
Status = DISCONNECTED
      ↓
Simpan database
      ↓
Kirim notifikasi admin

Notifikasi dapat dikirim melalui email, Telegram, dashboard internal, atau layanan lain sesuai kebutuhan sistem.

Menangani Device Kembali Terhubung

Proses yang sama dapat digunakan ketika device kembali terhubung.

Contohnya:

Device terputus
      ↓
Status DISCONNECTED
      ↓
Device tersambung kembali
      ↓
Status CONNECTED
      ↓
Update database

Setelah status menjadi CONNECTED, sistem dapat melanjutkan proses yang sebelumnya ditahan.

Misalnya terdapat antrean pesan:

Queue
  ↓
Device DISCONNECTED
  ↓
Pengiriman ditahan
  ↓
Device CONNECTED
  ↓
Queue dilanjutkan

Jangan langsung menjalankan seluruh antrean tanpa aturan jika jumlah pesan cukup besar. Sistem perlu memiliki batas pengiriman dan proses antrean yang sesuai dengan kebutuhan aplikasi.

Jangan Menyamakan Status Device dengan Status Pesan

Status device dan status pesan memiliki fungsi berbeda.

Contoh:

Device:
CONNECTED

berarti device terhubung.

Sementara pesan dapat memiliki status lain setelah dikirim.

Contoh alur:

Device CONNECTED
      ↓
API menerima request
      ↓
Pesan diproses
      ↓
Status pesan diperbarui

Karena itu, aplikasi sebaiknya menyimpan status device dan status pesan pada data yang berbeda.

Contoh struktur database:

devices
- id
- name
- status
- updated_at

messages
- id
- device_id
- recipient
- message
- status
- created_at

Struktur tersebut membuat data koneksi device tidak tercampur dengan data pengiriman pesan.

Mencatat Riwayat Status Device

Selain menyimpan status terbaru, sistem dapat menyimpan riwayat perubahan status.

Contohnya:

Waktu	Device	Status
09:10	Device 01	CONNECTED
09:25	Device 01	DISCONNECTED
09:29	Device 01	CONNECTED

Riwayat ini berguna untuk melihat kapan device terputus dan kapan kembali terhubung.

Struktur sederhananya:

device_status_logs
- id
- device_id
- status
- created_at

Setiap event perubahan status dapat membuat satu record baru.

Hindari Update Database pada Setiap Event yang Sama

Webhook dapat menerima event yang sama lebih dari sekali. Jika aplikasi langsung membuat record tanpa pemeriksaan, database dapat berisi data duplikat.

Contoh:

CONNECTED
CONNECTED
CONNECTED

Jika status tidak berubah, aplikasi dapat menghindari update yang tidak diperlukan.

Contoh logika:

if (currentStatus !== newStatus) {
  await updateDeviceStatus(newStatus);
}

Untuk riwayat status, gunakan ID event atau identifier lain yang tersedia pada payload jika sistem membutuhkan pencegahan duplikasi yang lebih ketat.

Contoh Handler Webhook

Berikut contoh struktur handler yang memisahkan penerimaan request dan proses status:

app.post('/webhook/whatsapp', async (req, res) => {
  const event = req.body;

  res.sendStatus(200);

  try {
    const status = extractDeviceStatus(event);

    if (!status) {
      return;
    }

    await processDeviceStatus(status);

  } catch (error) {
    console.error(
      'Gagal memproses status device:',
      error
    );
  }
});

Fungsi extractDeviceStatus() dan processDeviceStatus() dapat disesuaikan dengan struktur aplikasi.

Pemisahan seperti ini membuat route webhook lebih mudah dirawat ketika proses monitoring bertambah.

Cara Menguji Status Device

Setelah webhook dikonfigurasi, lakukan pengujian dengan mengamati perubahan status device.

Urutannya:

1. Pastikan device CONNECTED
2. Pastikan webhook aktif
3. Periksa log server
4. Ubah kondisi koneksi device
5. Periksa event yang diterima
6. Periksa status pada database
7. Pastikan dashboard menampilkan status terbaru

Pada tahap pengujian, log payload lengkap terlebih dahulu:

console.log(JSON.stringify(req.body, null, 2));

Setelah struktur event sudah diketahui, hapus log yang tidak diperlukan atau gunakan logging yang lebih terkontrol untuk production.

Jika Status Device Tidak Masuk ke Webhook

Jika perubahan status tidak terlihat pada server, periksa dari bagian paling dasar.

Periksa URL

Pastikan URL webhook benar dan sesuai dengan route server.

Periksa Akses Internet

Server harus dapat menerima request dari luar.

Periksa HTTPS

Pastikan sertifikat SSL valid dan domain dapat diakses melalui HTTPS.

Periksa Route

Pastikan endpoint menerima POST.

Periksa Log Server

Jika tidak ada request sama sekali, masalah kemungkinan berada sebelum proses aplikasi.

Jika request sudah masuk tetapi status tidak terbaca, periksa payload dan kode parsing.

Periksa Device

Pastikan pengujian dilakukan pada device yang benar dan status device memang berubah.

Status Device untuk Sistem Pengiriman Otomatis

Status koneksi dapat digunakan sebagai salah satu kondisi sebelum sistem mengirim pesan.

Contohnya:

if (device.status !== 'CONNECTED') {
  return {
    success: false,
    message: 'Device belum terhubung'
  };
}

Alur sistem:

Pesan masuk queue
       ↓
Cek status device
       ↓
CONNECTED?
   ↙        ↘
 Ya        Tidak
 ↓            ↓
Kirim       Tunda

Pengecekan ini tidak menggantikan penanganan error pada API. Status device hanya menjadi salah satu informasi yang dapat digunakan sebelum pengiriman.

Kapan Webhook Lebih Berguna daripada Polling?

Polling berarti aplikasi melakukan request secara berkala untuk mengetahui status terbaru.

Contohnya:

Aplikasi
  ↓
Cek status
  ↓
Tunggu
  ↓
Cek status
  ↓
Tunggu
  ↓
Cek status

Webhook bekerja berdasarkan event:

Status berubah
      ↓
Whapi mengirim event
      ↓
Webhook menerima
      ↓
Aplikasi memperbarui status

Untuk perubahan status yang perlu diketahui aplikasi secara otomatis, event webhook dapat mengurangi kebutuhan request pengecekan berulang.

Namun, polling tetap dapat digunakan sebagai pemeriksaan tambahan ketika aplikasi membutuhkan sinkronisasi berkala.

Kesimpulan

Cara mengecek status koneksi device melalui webhook WhatsApp dimulai dengan menyediakan endpoint yang dapat menerima event, menghubungkannya ke konfigurasi webhook, kemudian membaca event perubahan status pada server.

Alurnya:

Device WhatsApp
      ↓
Perubahan status
      ↓
Webhook
      ↓
Server
      ↓
Database
      ↓
Dashboard / Sistem Pengiriman

Status device dapat digunakan untuk menampilkan kondisi koneksi pada dashboard, mencatat riwayat koneksi, memberi notifikasi ketika device terputus, dan menentukan apakah antrean pesan dapat diproses.

Untuk mendapatkan hasil yang akurat, jangan menebak struktur payload webhook. Tampilkan payload yang diterima terlebih dahulu, identifikasi field status yang tersedia, kemudian buat kode berdasarkan struktur event tersebut.