Lompat ke konten utama
StableTerakhir diperbarui: 9 Okt 2026, 09.28

Kuota Pesan Gateway WhatsApp

1. Ringkasan

Sistem Kuota Pesan Gateway ( P-QUOTA ) adalah mekanisme pengawasan yang membatasi dan melacak total penggunaan pengiriman pesan harian atau bulanan toko Anda melalui infrastruktur WhatsApp API DagangBot. Alih-alih Anda berurusan langsung dengan tagihan rumit Meta per pesan, DagangBot telah menyediakan subsidi kuota pesan (Subsidized Pricing Mode) bawaan setiap siklus paket langganan Anda.

Halaman dasbor kuota menampilkan sisa ketersediaan secara terpusat agar kampanye pesan massal Anda tidak tiba-tiba berhenti pada pertengahan jalan.

2. Konsep Dasar

Model penetapan jumlah pesan selalu dihitung berdasarkan Pesan Keluar (Outbound Message), baik itu dipicu secara manual, berjadwal, ataupun melalui alur otomasi sistem.

Sebuah objek status kuota pesan (Quota Status) akan memuat variabel berikut:

  • QuotaLimit: Batas maksimum pesan yang diizinkan dalam suatu periode.
  • QuotaUsed: Jumlah pesan yang sudah dikirim atau sedang dalam antrean.
  • Remaining: Sisa (Limit dikurangi Used). Jika mencapai 0, layanan pengiriman pesan akan dicegah.
  • PeriodStart & PeriodEnd: Rentang waktu perhitungan.
  • ResetMode: Skema perpanjangan atau penyetelan ulang saldo (contoh: direset setiap awal bulan kalender atau ditambahkan pada siklus tagihan).
  • PricingMode: Mengidentifikasi apakah Anda menggunakan perhitungan default bebas, atau model subsidized (terpotong dari paket DagangBot).

Aturan Inklusi Fitur

Tidak semua lalu lintas pesan keluar disedot dari kuota utama:

  • OTPIncluded: Jika aktif, pesan konfirmasi OTP (seperti PIN login pembeli) memakan saldo. Jika non-aktif, sistem tidak akan mengurangi jatah kuota pada rute OTP.
  • BroadcastIncluded: Jika aktif, layanan Broadcast Campaign langsung terintegrasi dengan pengecekan saldo, artinya Anda tidak bisa menyebarkan promo melebihi sisa kuota yang ada.

2.2 Klasifikasi Pesan (Message Categories)

Ketika sebuah pesan keluar dari peladen, sistem (Quota Service) mengkategorikan lalu lintas untuk pencatatan analitik metrik Prometheus (QuotaConsumedTotal). Kategori ini meliputi:

  • broadcast: Kampanye promosi massal.
  • notification: Pembaruan status pesanan otomatis kepada pembeli (misal: "Pesanan dikirim").
  • otp: One-Time Password dan autentikasi.
  • reply: Balasan manual agen kasir dari dasbor chat. Pemisahan kategori ini memudahkan audit ketika Anda ingin mengetahui sektor mana yang paling boros menyedot alokasi bulanan.

2.3 Mekanisme Kunci Silang (Concurrency & Race Conditions)

Mengingat puluhan pesan (khususnya broadcast) dapat dikirim dalam milidetik yang sama, DagangBot menggunakan penguncian Database Row-Level Lock (SELECT FOR UPDATE) pada saat pemotongan saldo (UpdateUsed). Mekanisme ini menjamin tidak terjadi Over-Quota ganda ( Race Condition ) di mana 2 pesan dikirim saat limit sisa saldo hanya 1. Pesan kedua akan secara aman tertahan dengan pesan ErrQuotaExceeded.

3. Prasyarat & Konfigurasi

  • Hak Akses: Hanya profil dengan wewenang lapisan billing setara read yang dapat membuka rincian penggunaan di dasbor pemantauan kuota.
  • Status Langganan: Fitur alokasi perhitungan subsidiar mengharuskan siklus tagihan toko berstatus aktif (bukan masa tenggang atau kadaluwarsa). Jika konfigurasi sistem utama mematikan (toggle-off) saklar kuota, pesan Anda akan diteruskan tanpa penghalang perhitungan saldo ini.

3.2 Siklus Langganan dan Rollover

Alokasi ini diintegrasikan lewat adaptor (InitQuotaForSubscription). Ketika toko Anda berpindah paket (upgrade/downgrade), pekerja penagihan sistem akan mengeksekusi ResetQuotaWithPeriod. Limit akan diatur ulang menjadi batas baru, dan nilai pemakaian (QuotaUsed) dikembalikan ke 0. Kuota yang tidak terpakai (unused) dari bulan sebelumnya akan hangus dan tidak diakumulasikan ke siklus baru.

4. Panduan Penggunaan

4.1 Memantau Sisa Kuota

  1. Akses menu Tagihan & Penggunaan di bilah sidebar.
  2. Gulir menuju blok visualisasi Kuota Gateway.
  3. Sistem akan merender diagram riwayat QuotaUsed dengan batasan persentase yang mudah diinterpretasikan.

4.2 Mengakses Riwayat Mutasi Kuota

Jika Anda mencurigai adanya anomali atau pencurian lalu lintas (misalnya lonjakan drastis pada jam 2 pagi), Anda dapat memeriksa mutasi riwayat kuota:

  1. Klik tab Riwayat (History) pada jendela widget Kuota Gateway.
  2. Setiap kali ada pengiriman kolektif yang menghabiskan persentase saldo (misalnya: 100 pesan dikirim via Broadcast), sistem merekamnya di daftar tersebut.
  3. Fitur pelaporan di tab ini mencantumkan jejak timestamp yang rinci untuk keperluan audit.

4.3 Simulasi Pengiriman Pesan Peringatan

Platform menyediakan alat dry-run untuk menguji logika penguncian kuota sebelum Anda meluncurkan pemasaran:

  1. Buka antarmuka bot WhatsApp di sisi pembeli palsu (dummy buyer).
  2. Arahkan kursor Anda ke kolom pengaturan ambang batas pada dasbor toko.
  3. Ubah saldo ambang batas peringatan Anda menjadi 99%.
  4. Kirimkan satu pesan, lalu amati modul Alert Center di antarmuka sistem. Anda akan menerima proksi notifikasi palsu low_balance. Ini membuktikan bahwa integrasi detektor kuota (QuotaAlertService) sedang hidup dan memantau dengan tepat.

4.4 Mengalokasikan Sub-Kuota untuk Agensi (Agency Sub-allocation)

Jika toko Anda berbentuk korporasi besar yang membeli multi-tenant agency tier, Anda bertindak sebagai payung besar yang memiliki Global Quota (misal: 10.000.000 pesan). Anda bisa memecah saldo ini kepada setiap anak cabang toko ( sub-merchant ) melalui dasbor Agensi.

  1. Masuk ke Menu Agensi → Kuota Alokasi.
  2. Anda akan disuguhkan tabel baseline allocations dari setiap anak toko.
  3. Ubah kolom input QuotaLimit pada toko cabang. Sistem secara mandiri menolak jika jumlah SUM(children) melebihi alokasi parent (ErrDistributionExceedsQuota).
  4. Anak toko akan melihat angka ini sebagai batas absolut (hard limit) harian/bulanan mereka.

5. Skenario Lanjutan

Mekanisme Ambang Batas Peringatan (Alert Thresholds)

Anda tidak harus mengecek layar ini setiap hari. Fitur Alert Thresholds dalam sistem berfungsi ganda dengan Pusat Notifikasi tenant. Saat sisa kuota mencapai persentase rawan (contoh: 20%, lalu 5%), platform akan memicu notifikasi peringatan low_balance ke alamat surel atau bot CRM Anda untuk menyarankan penambahan (top-up) saldo segera sebelum pengiriman tertahan (bounce).

5.2 Kebijakan Penalti & Penahanan (Block & Bounce)

Apabila lalu lintas toko nekat menembus batasan setelah saldo Remaining bernilai 0:

  1. Transmisi ke Provider Gateway (seperti API Meta) diputus sepenuhnya (circuit breaker).
  2. Pesan dimasukkan ke status failed dengan galat peladen internal.
  3. Toko tidak didenda secara finansial (karena prabayar), namun aktivitas pemasaran terhenti total. Kampanye berjalan akan dibekukan ( paused ). Anda dituntut membeli kuota tambahan ( Add-on ) untuk melanjutkan antrean yang terhenti.

5.3 Aturan Kebebasan Terbatas (Override Rules)

Pada kasus insiden darurat, agen dukungan pelanggan DagangBot memiliki wewenang administrator (ForceApplyDelta) untuk menyuntikkan pengecualian kuota secara sepihak ke toko tertentu (Manual Top-up Override).

5.4 Penambahan Saldo Darurat Berkelanjutan (Continuous Top-Up)

Bila batas habis di penghujung bulan, Anda tidak perlu memajukan siklus penagihan penuh. Fitur Penambahan Koin (Top-up) memungkinkan Anda membeli paket Add-on (contoh: +5.000 pesan). Sistem akan melakukan injeksi ForceApplyDelta secara aman tanpa mengubah rentang kalender PeriodStart dan PeriodEnd. Nilai QuotaLimit Anda akan menggelembung seketika, dan pesan yang sedang tersendat di Queue Worker akan kembali dilepaskan dalam hitungan detik.

6. Referensi Teknis

Arsitektur Eksekusi Pemotongan dan Sinkronisasi Kuota

Fungsi utama pemotongan kuota ditangani secara otomatis oleh layanan manajemen kuota backend. Metode ini membaca batas mutlak (QuotaLimit) dan memvalidasi sisa (Remaining) melalui lapisan memori cepat untuk mencegah perlombaan data (race condition). Saat pesan berhasil dieksekusi:

  • Blokir: Jika current >= quota.QuotaLimit, pesan ditolak seketika (block) dan mengembalikan galat, sehingga lalu lintas toko Anda aman dari tagihan liar (overcharge).
  • Penahanan Sementara: Jika pesan gagal terkirim (misalnya nomor tak valid), platform memanggil ReleaseQuota untuk mengembalikan (refund) kuota yang sempat dipesan (reserved) sehingga hitungan QuotaUsed tetap presisi dan adil.
  • Ambang Batas (Alert Threshold): Proses peringatan berjalan asinkron menggunakan metode non-blocking CheckAndFireAlerts dalam rutinitas goroutine ( safego ). Saat persentase krisis (low_balance) terlewati, sistem menyebarkan email kepada pemilik tanpa mengganggu kecepatan transmisi pesan konsumen.
  • Sub-Alokasi Agensi: Pemrosesan delegasi kuota multi-tenant diproses untuk menolak alokasi bila distribusi sub-toko melebihi induk. Agensi induk dapat mengunci porsi spesifik QuotaLimit pada sub-tokonya.

Integrasi sistem menghadirkan pemantauan lewat API Endpoint:

  • GET /api/quota/status: Menghasilkan JSON ringkasan saldo, properti Remaining, serta indikator inklusi, sehingga antarmuka sistem (frontend) bisa memutuskan untuk menonaktifkan tombol kirim pesan ketika Remaining == 0.
  • GET /api/quota/history: Mendapatkan rangkaian data baris waktu pencatatan kronologis lalu lintas mutasi, diurutkan dari yang terbaru ke yang terlama.
  • Cross-tenant Check: Komponen di backend (P-QUOTA S4) didesain memiliki perlindungan ekstra sehingga pemeriksaan alokasi hanya membaca catatan dari penyewa ( tenant ) yang sama ( Row-Level Security terisolasi ).

6.1 Tabel A. Model Beban Permintaan Saldo (Quota Status Payload)

Saat frontend menanyakan status, struktur objek balasannya sebagai berikut:

Properti Tipe Deskripsi
merchant_id UUID Pengenal unik penyewa.
quota_limit Integer Plafon batas atas pengiriman dalam satu periode.
quota_used Integer Pemakaian berjalan saat ini.
remaining Integer Kalkulasi otomatis dari selisih limit dikurangi terpakai.
reset_mode String Strategi setel ulang, biasanya "billing_cycle".
otp_included Boolean Parameter bendera inklusi.

6.2 Tabel B. Model Pembaruan Rekam Jejak (History Log)

Properti Tipe Deskripsi
mutation_type String Nilainya "decrement" (dipakai), "reset" (ulang), atau "add" (tambah darurat).
amount Integer Angka fluktuasi perubahan (delta).
created_at DateTime Waktu spesifik hingga orde milidetik pemotongan terekam (Audit Timestamp).

7. Pemecahan Masalah

Masalah Penyebab Solusi
Pesan OTP / Autentikasi tidak terkirim Kuota bulanan habis dan flag OTPIncluded disetel pada opsi bernilai benar. Beli paket add-on top-up saldo koin pada modul tagihan untuk memperpanjang siklus.
Layar Widget hilang dari Dashboard Penagihan Pengaturan internal platform quota.message_quota_enabled pada penyewa toko Anda bernilai non-aktif atau dinonaktifkan sementara. Hubungi dukungan pelanggan DagangBot, kemungkinan paket lama Anda (tipe legacy) mengizinkan unlimited usage sehingga UI pelacakan otomatis dihilangkan.
Broadcast gagal padahal sasaran 1.000 kontak Sisa ( Remaining ) kuota hanya tersedia 500, dan flag BroadcastIncluded diaktifkan. Sistem menolak perintah pre-flight check. Pecah kampanye Anda dan hapus 500 kontak terbawah dari fail audiens Anda, atau perbarui langganan terlebih dahulu.
Notifikasi email kehabisan batas sangat telat tiba Server email Anda membuang peringatan ke folder Spam, atau jeda antrean worker. Anda dapat secara mandiri memeriksa mutasi secara harian pada tab History, serta memasukkan (whitelist) alamat email dari DagangBot.
Pesan harian memantul dengan status ErrQuotaDisabled Konfigurasi global kuota pada sistem (ErrQuotaDisabled) dinonaktifkan sementara untuk perbaikan internal. Ini adalah fail-safe platform. Pengiriman pesan ditunda dan bukan dibuang. Hubungi dukungan pelanggan.
Perhitungan tidak sinkron / sisa kuota lebih kecil dari hitungan manual Terdapat pesan balasan panjang yang dipecah (multipart message) oleh Provider Meta sehingga dihitung dua kali penyedotan. Tinjau log History untuk melihat apakah satu pesan panjang memicu dua entri pengurangan saldo. Pendekkan konten pesan promosi Anda.
content/docs/features/gateway-quota.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot