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 perhitungandefaultbebas, atau modelsubsidized(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
billingsetarareadyang 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
- Akses menu Tagihan & Penggunaan di bilah sidebar.
- Gulir menuju blok visualisasi Kuota Gateway.
- 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:
- Klik tab Riwayat (History) pada jendela widget Kuota Gateway.
- Setiap kali ada pengiriman kolektif yang menghabiskan persentase saldo (misalnya: 100 pesan dikirim via Broadcast), sistem merekamnya di daftar tersebut.
- 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:
- Buka antarmuka bot WhatsApp di sisi pembeli palsu (dummy buyer).
- Arahkan kursor Anda ke kolom pengaturan ambang batas pada dasbor toko.
- Ubah saldo ambang batas peringatan Anda menjadi 99%.
- 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.
- Masuk ke Menu Agensi → Kuota Alokasi.
- Anda akan disuguhkan tabel
baseline allocationsdari setiap anak toko. - Ubah kolom input
QuotaLimitpada toko cabang. Sistem secara mandiri menolak jika jumlahSUM(children)melebihi alokasiparent(ErrDistributionExceedsQuota). - 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:
- Transmisi ke Provider Gateway (seperti API Meta) diputus sepenuhnya (circuit breaker).
- Pesan dimasukkan ke status
faileddengan galat peladen internal. - 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
ReleaseQuotauntuk 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
CheckAndFireAlertsdalam 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
QuotaLimitpada sub-tokonya.
Integrasi sistem menghadirkan pemantauan lewat API Endpoint:
GET /api/quota/status: Menghasilkan JSON ringkasan saldo, propertiRemaining, serta indikator inklusi, sehingga antarmuka sistem (frontend) bisa memutuskan untuk menonaktifkan tombol kirim pesan ketikaRemaining == 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:
