Langsung ke isi

Pemrograman, Software

Membuat Aplikasi WA Gateway Mandiri dengan Go dan PostgreSQL

Catatan proyek riset membangun WhatsApp gateway mandiri dengan Go dan PostgreSQL: arsitektur, tech stack, fitur, kegunaannya untuk pribadi maupun instansi, dan risiko yang perlu dipahami sebelum memakainya.

siapkan kopi dulu ☕

Team Inbox aplikasi WA gateway mandiri: daftar percakapan berlabel dan isi chat pelanggan fiktif, nomor telepon diburamkan

Layanan WA gateway siap pakai memang praktis, tetapi ada harganya: biaya bulanan per nomor, batas API, dan seluruh isi chat tersimpan di server orang lain. Saya penasaran seberapa jauh gateway seperti itu bisa dibangun sendiri, berjalan di server sendiri, dengan data milik sendiri.

Hasilnya sebuah aplikasi WA gateway mandiri yang saya beri nama proyek Wazapan. Gateway lama saya berbasis Laravel + Node.js, lalu saya tulis ulang total menjadi satu biner Go. Ini proyek riset yang dikerjakan santai, bukan produk komersial. Tulisan ini mencatat cara membangunnya, apa saja kegunaannya, dan risiko yang perlu dipahami sebelum memakainya.

Catatan demo. Semua tangkapan layar di sini memakai data fiktif: kedai "Kopi Senja", nama pelanggan, isi chat, dan angkanya dibuat khusus untuk demo. Nomor WhatsApp/HP juga nomor demo dan sengaja diburamkan.

Arsitektur WA gateway mandiri: satu proses, satu database

Prinsip utamanya sederhana: semakin sedikit komponen yang harus dirawat, semakin baik. Panel web, engine WhatsApp, REST API, penjadwal, dan worker latar semuanya hidup dalam satu proses Go.

 Browser (panel web) ───┐
 Aplikasi lain (API) ───┤ HTTP
 Webhook masuk ─────────┘
                        ▼
        ┌──────────── satu biner Go ─────────────┐
        │ handler → service → repository         │
        │ engine WhatsApp (whatsmeow, per nomor)  │
        │ worker: campaign, flow, jadwal, laporan │
        └───────────────────┬─────────────────────┘
                            ▼
                PostgreSQL 17 + pgvector

Kodenya dibagi tiga lapis dengan arah dependensi satu jalur: handler (HTTP) memanggil service (logika bisnis), dan service memanggil repository (SQL) lewat interface. Dengan begitu logika bisnis bisa diuji tanpa database dan tanpa WhatsApp sungguhan.

Tech stack

Lapisan Pilihan
Bahasa & HTTP Go 1.26, router chi
Engine WhatsApp whatsmeow (protokol multi-device, tautkan lewat QR atau kode pairing)
Database PostgreSQL 17 + pgvector, driver pgx, 118 migrasi SQL berurutan
Antarmuka SPA JavaScript murni (ES modules), Tailwind CSS v4 + Flowbite, PWA + Web Push
AI Adapter multipenyedia (kompatibel OpenAI & Anthropic) untuk chatbot dan embedding
Pendukung Midtrans, penyimpanan kompatibel S3, maroto (PDF), goldmark (Markdown), TOTP (2FA)
Deploy Biner statik CGO_ENABLED=0, image Docker distroless ±49 MB, Docker Compose

Bagian-bagian yang dibangun

1. Menautkan nomor. whatsmeow menangani protokol WhatsApp multi-device. Sesi tiap nomor disimpan di PostgreSQL yang sama dengan data aplikasi, jadi tidak ada berkas sesi yang tercecer di disk. Status QR dan koneksi dikirim ke browser secara realtime lewat Server-Sent Events.

2. Pesan masuk. Setiap pesan masuk melewati satu jalur: dicatat ke kotak masuk, dicek terhadap flow yang sedang berjalan, lalu terhadap autoreply. Urutan ini penting, karena balasan pelanggan di tengah flow harus masuk ke flow, bukan memicu autoreply.

3. Antrean kirim yang "sopan". Kiriman massal tidak dilepas sekaligus. Worker mengirim satu per satu dengan jeda acak, hanya di jam kirim yang ditentukan, dan dengan variasi kalimat (spintax). Jatah harian tiap nomor naik bertahap (warm-up).

4. REST API. Integrasi dengan aplikasi lain cukup dengan API key:

curl -s -XPOST https://gateway.example/api/send-message \
  -H "Authorization: Bearer wzp_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{"sender":"6281200000001","number":"6281200000002","message":"Pesanan #1234 sudah dikirim 🛵"}'

Sebaliknya, setiap pesan masuk bisa diteruskan ke webhook milik aplikasi lain.

5. Panel tanpa server frontend terpisah. HTML, CSS, dan JavaScript panel ditanam ke dalam biner dengan go:embed. Tidak perlu Node.js di server; cukup satu berkas yang dijalankan.

6. Chatbot yang membaca dokumen sendiri. Dokumen (daftar harga, FAQ, kebijakan) dipotong kecil-kecil, diubah menjadi embedding, dan disimpan sebagai kolom vector di PostgreSQL. Saat ada pertanyaan, potongan yang relevan dicari dengan indeks pgvector, lalu diberikan ke model sebagai konteks (pola RAG). Bot jadi menjawab berdasarkan dokumen, bukan mengarang.

Hasilnya: fitur yang akhirnya jadi

Team Inbox

Team Inbox aplikasi WA gateway mandiri: daftar percakapan berlabel dan isi chat pelanggan fiktif, nomor telepon diburamkan

Satu nomor dipakai bersama beberapa agen. Percakapan bisa ditugaskan, diberi label, dan diselesaikan.

Chat masuk dikumpulkan di satu kotak masuk bersama, bisa ditugaskan ke agen, diberi label, ditunda, dan diselesaikan. Balasan cepat dipanggil dengan /, misalnya /ongkir.

Campaign

Daftar campaign berstatus selesai dengan progres pengiriman 100 persen

Daftar campaign beserta progres pengirimannya.

Pesan ke banyak kontak, dicicil lewat antrean tadi. Tersedia uji A/B dan follow-up otomatis untuk penerima yang belum membalas.

Flow Builder

Kanvas Flow Builder berisi alur pemesanan kopi: kirim pesan, tanya, kondisi bercabang ya dan tidak

Alur pemesanan kopi: tanya menu, tanya cara ambil, lalu bercabang antara dikirim dan diambil sendiri.

Alur percakapan dirangkai di kanvas: kirim pesan, tanya dan tunggu balasan, bercabang sesuai jawaban, lalu serahkan ke manusia. Di balik layar, kanvas ini dikompilasi menjadi graf node dan sisi yang dijalankan oleh runner.

Basis Pengetahuan

Halaman Basis Pengetahuan dengan satu basis FAQ berisi 4 dokumen dan 30 potongan teks

Dokumen yang menjadi rujukan chatbot AI.

Tempat mengunggah dokumen (berkas, teks, atau URL) yang menjadi rujukan chatbot. Setiap dokumen diindeks menjadi potongan-potongan yang siap dicari.

Anti-Ban

Halaman Anti-Ban: skor kesehatan dua perangkat dan jatah warm-up harian, nomor perangkat diburamkan

Skor kesehatan dan jatah warm-up harian tiap nomor.

Skor kesehatan per nomor, batas kirim yang naik otomatis, rotasi beban antarnomor, dan opt-out otomatis saat penerima membalas STOP.

Laporan

Halaman Laporan: funnel campaign dari diantre, terkirim, sampai, dibaca, hingga dibalas

Funnel campaign: diantre → terkirim → sampai → dibaca → dibalas.

Funnel tiap campaign sampai ke jumlah yang membalas, performa agen, dan statistik flow, bisa diekspor ke CSV.

Selain itu ada autoreply kata kunci, pesan terjadwal, jam kerja (balasan otomatis di luar jam layanan), webhook masuk (Google Forms, WooCommerce, gateway pembayaran), widget chat untuk situs, survei, serta invoice dan kwitansi digital.

Kegunaannya untuk pribadi dan instansi

Untuk pemakaian pribadi

  • Notifikasi dari sistem sendiri. Server, aplikasi, atau skrip pribadi bisa mengirim kabar ke WhatsApp lewat REST API, misalnya peringatan server mati, hasil backup, atau pengingat tagihan bulanan.
  • OTP dan konfirmasi untuk aplikasi buatan sendiri, tanpa berlangganan layanan pihak ketiga.
  • Pengingat terjadwal: ulang tahun, jatuh tempo, atau jadwal rutin, cukup diatur sekali.
  • Balasan otomatis saat sibuk: autoreply dan jam kerja menjawab pertanyaan yang itu-itu saja.
  • Tempat belajar. Bagi yang ingin memahami Go, PostgreSQL, pgvector, atau RAG, proyek seperti ini adalah laboratorium yang lengkap.

Untuk instansi (sekolah, kantor, organisasi, UMKM)

  • Satu nomor resmi, dipegang banyak petugas. Team Inbox membagi percakapan ke beberapa petugas, dan riwayatnya tetap milik instansi meski petugas berganti. Tidak ada lagi nomor layanan yang menempel di ponsel pribadi satu orang.
  • Pengumuman dan pengingat yang tertata. Contohnya pengumuman ke wali murid atau anggota, pengingat pembayaran, dan undangan kegiatan, dikirim bertahap dengan jeda supaya lebih aman.
  • Formulir yang langsung ditindaklanjuti. Pendaftaran lewat Google Forms bisa otomatis dibalas konfirmasi WhatsApp lewat webhook masuk.
  • Layanan informasi 24 jam. Chatbot menjawab pertanyaan rutin (jadwal, syarat, prosedur) berdasarkan dokumen resmi instansi, lalu menyerahkan ke petugas bila pertanyaannya di luar dokumen.
  • Umpan balik dan laporan. Survei, nilai kepuasan setelah percakapan selesai, dan laporan kinerja membantu menilai kualitas layanan dengan angka, bukan perkiraan.

Keuntungan memakai gateway mandiri

  • Data di server sendiri. Isi chat, kontak, dan dokumen tidak dititipkan ke penyedia lain.
  • Tanpa biaya langganan per nomor. Biaya utamanya hanya server, ditambah biaya AI kalau fitur chatbot dipakai.
  • Bebas diintegrasikan dengan sistem yang sudah ada lewat REST API dan webhook.
  • Bisa disesuaikan dengan alur kerja sendiri, karena kodenya dipegang sendiri.

Cara menjalankannya

Di server, stack-nya hanya tiga layanan di Docker Compose: postgres (image pgvector/pgvector:pg17), migrate (menjalankan migrasi SQL lalu berhenti), dan app (biner Go). Langkahnya:

cp .env.example .env          # isi DB_PASSWORD dan SESSION_SECRET
docker compose up -d --build

# akun admin pertama dibuat lewat CLI; sandi lewat stdin,
# supaya tidak tersimpan di riwayat shell
printf '%s\n' 'sandi-kuat' | docker compose run --rm -T app \
  create-admin --password-stdin --username admin --email admin@example.com

Saat start, aplikasi memeriksa skema database. Kalau ada migrasi yang belum diterapkan, ia menolak jalan dan tidak berlanjut dengan skema yang setengah jadi.

Pahami risikonya sebelum memakai

Bagian ini sama pentingnya dengan daftar fitur di atas.

  • Ini proyek riset yang dikerjakan santai. Tidak ada jaminan layanan (SLA), garansi, maupun dukungan resmi. Bug tetap mungkin ada, dan fitur bisa berubah sewaktu-waktu.
  • whatsmeow adalah pustaka tidak resmi. Menautkan nomor lewat QR seperti WhatsApp Web selalu membawa risiko nomor dibatasi atau diblokir, apalagi untuk pengiriman massal. Pemakaian klien tidak resmi juga bisa bertentangan dengan ketentuan layanan WhatsApp, dan risikonya ditanggung pemakai.
  • Pakai nomor khusus, bukan nomor utama. Jangan menautkan nomor pribadi atau nomor resmi instansi yang tidak boleh hilang. Siapkan rencana cadangan kalau nomor terblokir.
  • Kirim secukupnya. Ikuti warm-up, kirim hanya ke kontak yang sudah memberi persetujuan, dan hormati permintaan berhenti (STOP). Gateway ini bukan alat spam.
  • Data pribadi adalah tanggung jawab Anda. Begitu menjalankan sendiri, Anda menjadi pengendali datanya: keamanan server, cadangan, dan kepatuhan pada UU Pelindungan Data Pribadi ada di tangan Anda.
  • Jangan dipakai untuk layanan kritis. Informasi darurat, layanan yang diwajibkan aturan, atau komunikasi berskala besar sebaiknya memakai jalur resmi WhatsApp Business Cloud API. Gateway ini juga mendukungnya sebagai kanal per nomor.
  • Untuk instansi, mulai dari uji coba kecil. Libatkan bagian TI, uji dengan nomor cadangan dan kelompok kecil, lalu nilai hasilnya sebelum dipakai lebih luas.

Penutup

Membangun gateway sendiri memang lebih repot daripada berlangganan, tetapi memberi kontrol penuh: data tinggal di server sendiri, fitur bisa ditambah sesuai kebutuhan, dan biaya operasionalnya cuma satu server kecil berisi satu biner dan satu database. Anggap saja proyek ini sebagai bahan belajar dan alat bantu skala kecil. Pakailah dengan sadar risiko, dan pilih jalur resmi ketika taruhannya besar.

WhatsApp adalah merek dagang Meta Platforms, Inc. Proyek ini independen dan tidak berafiliasi dengan Meta.