Balesin- WA RAG Chatbot

1. Project Summary

Balesin adalah platform full-stack untuk membantu bisnis mengotomasi percakapan pelanggan di WhatsApp menggunakan pendekatan Retrieval-Augmented Generation (RAG).

Aplikasi ini memungkinkan admin menghubungkan WhatsApp melalui QR pairing, menerima pesan pelanggan lewat webhook, menyimpan histori percakapan, menjawab otomatis menggunakan AI berdasarkan knowledge yang dikelola dari dashboard web, serta melakukan manual takeover ketika percakapan perlu ditangani manusia.

Secara garis besar, Balesin menggabungkan:

• WhatsApp integration melalui Evolution API.
• Backend API menggunakan NestJS.
• Dashboard admin menggunakan Vue 3.
• Database relasional menggunakan PostgreSQL dan Prisma.
• Vector search menggunakan Qdrant untuk retrieval knowledge.
• Redis untuk kebutuhan service Evolution API.
• Docker Compose/Dokploy untuk deployment.

2. Tech Stack

Backend

• NestJS: framework utama backend untuk REST API, webhook handler, auth, dashboard data, knowledge, RAG, conversation, tenant, user, dan WhatsApp integration.
• TypeScript: bahasa utama backend.
• Prisma ORM: akses database, schema modeling, query, dan seed data awal.
• PostgreSQL: penyimpanan data utama seperti user, tenant, WhatsApp instance, conversation, message, knowledge source, RAG config, assistant template, dan unanswered lead.
• JWT + Cookie Auth: autentikasi dashboard admin.
• bcryptjs: hashing password user.

AI and Retrieval

• RAG (Retrieval-Augmented Generation): pola utama untuk menjawab pertanyaan pelanggan berdasarkan knowledge bisnis.
• Qdrant: vector database untuk menyimpan dan mencari embedding knowledge.
• Embedding API: mengubah knowledge dan pertanyaan user menjadi vector.
• LLM Chat API: menghasilkan jawaban akhir berdasarkan pertanyaan user, histori chat, konfigurasi assistant, dan context dari Qdrant.

WhatsApp Integration

• Evolution API: service WhatsApp gateway untuk QR pairing, webhook event, connection state, dan send message.
• Webhook MESSAGES_UPSERT: event utama untuk menerima pesan masuk dari WhatsApp.
• Typing Presence and Reply Delay: backend mengirim typing presence dan delay natural sebelum balasan otomatis.

Frontend

• Vue 3: framework dashboard admin.
• Vite: tooling frontend.
• Tailwind CSS / TailAdmin: UI dashboard.
• Vue Router: routing halaman dashboard.
• Lucide Icons: icon UI.

Infrastructure

• Docker Compose: menjalankan service aplikasi secara terpisah.
• Dokploy: target deployment.
• Nginx: serving frontend production.
• Redis: dependency Evolution API.
• Persistent Volumes: menyimpan data PostgreSQL, Qdrant, Redis, Evolution instance, dan upload/runtime data.

3. Main Features

WhatsApp Connection

Admin dapat membuat atau menghubungkan WhatsApp instance dari dashboard. Backend memanggil Evolution API untuk membuat instance, mengambil QR code, membaca connection state, dan menyimpan status ke database.

Status yang disimpan meliputi:

• not_created
• connecting
• connected
• disconnected
• error

Dashboard menampilkan status koneksi, nomor aktif, QR pairing, tombol connect/reconnect, disconnect, dan refresh.

Webhook Message Automation

Ketika pelanggan mengirim pesan WhatsApp, Evolution API mengirim webhook ke backend.

Backend melakukan beberapa proses:

• Validasi payload webhook.
• Mengabaikan pesan grup, pesan kosong, atau instance yang tidak dikenal.
• Deduplicate message menggunakan table processed_messages.
• Menentukan tenant berdasarkan WhatsApp instance.
• Menyimpan conversation dan message.
• Menghitung lead intent dan lead score.
• Mengecek apakah takeover sedang aktif.
• Jika takeover tidak aktif, pesan masuk ke pipeline RAG.
• Mengirim balasan otomatis kembali ke WhatsApp.

RAG-Powered Auto Reply

RAG digunakan agar AI tidak menjawab hanya dari general knowledge, tetapi dari knowledge bisnis yang sudah dikelola admin.

Pipeline RAG:

1. User mengirim pesan ke WhatsApp.
2. Backend mengambil histori conversation terbaru.
3. Sistem membangun search query dari pertanyaan dan konteks chat.
4. Pertanyaan dikirim ke embedding API.
5. Vector hasil embedding dipakai untuk mencari context relevan di Qdrant.
6. Context knowledge, pertanyaan user, histori chat, dan instruction assistant dikirim ke LLM.
7. LLM menghasilkan jawaban.
8. Backend menyimpan jawaban sebagai message assistant.
9. Jawaban dikirim ke pelanggan melalui Evolution API.

Jika knowledge tidak ditemukan atau confidence rendah, sistem mengirim fallback reply dan mencatat pertanyaan ke unanswered_leads.

Web-Based Knowledge Management

Admin dapat mengelola knowledge dari dashboard web. Knowledge ini menjadi sumber utama jawaban RAG.

Fitur knowledge:

• Membuat artikel knowledge.
• Mengedit artikel knowledge.
• Menghapus artikel knowledge.
• Mencari knowledge berdasarkan judul atau isi.
• Reindex knowledge ke Qdrant.
• Melihat status indexing seperti pending, indexed, atau error.

Knowledge disimpan di PostgreSQL sebagai structured content, lalu saat reindex akan dipecah menjadi chunks dan dimasukkan ke Qdrant sebagai vector points.

Conversation Inbox

Dashboard menyediakan inbox untuk memantau conversation pelanggan.

Fitur inbox:

• List conversation.
• Search berdasarkan nomor atau nama pelanggan.
• Filter status conversation.
• Preview pesan terakhir.
• Detail histori chat.
• Status open, takeover, atau closed.
• Pagination.

Manual Takeover

Manual takeover digunakan ketika admin ingin mengambil alih percakapan dari AI.

Flow takeover:

• Admin mengaktifkan takeover dari dashboard.
• Conversation berubah status menjadi takeover.
• Bot berhenti membalas otomatis.
• Admin dapat membalas manual dari dashboard.
• Admin dapat release takeover agar bot aktif kembali.

Selain itu, jika admin membalas langsung dari WhatsApp dan pesan terdeteksi sebagai outgoing manual message, sistem dapat mengaktifkan takeover otomatis agar AI tidak ikut membalas thread yang sedang dipegang admin.

Lead and Fallback Tracking

Balesin mencatat pertanyaan yang tidak bisa dijawab dengan cukup yakin sebagai fallback lead.

Data yang disimpan:

• Nomor pelanggan.
• Pertanyaan pelanggan.
• Reason seperti no_match, low_confidence, llm_error, atau system_error.
• Status open atau closed.
• Metadata retrieval seperti top score, search query, dan lead score.

Dashboard menampilkan fallback terbaru agar admin bisa memperbaiki knowledge.

Lead Scoring

Sistem mendeteksi intent dari pesan pelanggan dan menaikkan lead score.

Contoh intent:

• Harga atau biaya.
• Syarat atau dokumen.
• Jadwal.
• Lokasi.
• Pendaftaran.
• Kontak admin.

Lead score kemudian dipakai untuk menentukan stage:

• new
• discovery
• interested
• hot
• handoff

Jika lead sudah hot atau perlu admin, sistem dapat memberi sinyal handoff.

AI Training Wizard

Dashboard menyediakan wizard untuk membantu admin mengatur perilaku AI tanpa harus masuk ke konfigurasi teknis.

Bagian utama AI training:

• Informasi bisnis.
• Nama AI.
• Business context.
• Greeting message.
• Clarify message.
• Fallback message.
• Pengetahuan bisnis.
• Gaya dan aturan jawaban.
• Simulasi chat.

AI training ini membantu mengubah konfigurasi RAG dan assistant flow agar jawaban lebih sesuai dengan karakter bisnis.

Assistant Template Configuration

Platform memiliki konsep assistant template.

Template dapat berisi:

• Profile assistant.
• Intent.
• Field collection.
• Action.
• Routing rule.
• Advanced retrieval settings.

Template dapat dibuat dan diedit oleh admin, lalu dipakai sebagai dasar konfigurasi assistant.

Tenant and User Management

Project ini memiliki modul tenant dan user management.

Fitur tenant:

• Create tenant.
• Update tenant.
• List tenant.
• Generate slug tenant.
• Generate WhatsApp instance name per tenant.
• Assign assistant template.

Fitur user:

• Create user.
• Update user.
• Reset password.
• Assign role.
• Assign tenant.
• Activate/deactivate user.
• Delete user dengan proteksi agar platform admin terakhir tidak terhapus.

Role user:

• platform_admin
• tenant_admin
• tenant_staff

Dashboard Analytics

Dashboard overview menampilkan ringkasan operasional:

• Jumlah chat hari ini.
• Jumlah fallback hari ini.
• Takeover aktif.
• Open leads.
• Status koneksi WhatsApp.
• Knowledge readiness.
• Recent conversations.
• Recent fallbacks.
• Readiness check seperti WhatsApp connected, knowledge indexed, dan fallback rate.

4. High-Level Architecture

Customer WhatsApp
    |
    v
Evolution API
    |
    v
NestJS Webhook Handler
    |
    +--> PostgreSQL: conversations, messages, leads
    |
    +--> RAG Service
            |
            +--> Embedding API
            |
            +--> Qdrant Vector Search
            |
            +--> LLM Chat API
            |
            v
        Generated Reply
    |
    v
Evolution API Send Message
    |
    v
Customer WhatsApp

Admin mengelola sistem melalui Vue dashboard:

Vue Dashboard
    |
    v
NestJS REST API
    |
    +--> PostgreSQL
    +--> Qdrant
    +--> Evolution API

5. Detailed Workflow

A. Admin Setup Workflow

1. Admin login ke dashboard.
2. Admin membuka halaman Connection.
3. Backend membuat atau mengambil WhatsApp instance.
4. Evolution API menyediakan QR code.
5. Admin scan QR code dari WhatsApp.
6. Backend menyimpan status instance sebagai connected.
7. Admin mengisi knowledge bisnis melalui dashboard.
8. Admin menjalankan reindex.
9. Knowledge diubah menjadi chunks, dibuat embedding, lalu disimpan ke Qdrant.
10. Bot siap menjawab pesan pelanggan.

B. Incoming Chat Workflow

1. Pelanggan mengirim pesan WhatsApp.
2. Evolution API mengirim webhook ke backend.
3. Backend mengambil instanceName, phone, messageId, dan isi pesan.
4. Backend mengabaikan pesan grup atau payload tidak valid.
5. Backend melakukan deduplication berdasarkan tenantId dan messageId.
6. Backend membuat atau memperbarui conversation.
7. Pesan pelanggan disimpan ke conversation_messages.
8. Backend menghitung intent, lead score, dan lead stage.
9. Jika takeover aktif, bot tidak membalas.
10. Jika takeover tidak aktif, pesan diproses oleh RAG service.
11. Jawaban AI dikirim ke WhatsApp.
12. Jawaban disimpan di database.

C. RAG Workflow

1. RAG service menerima pertanyaan user, normalized text, histori chat, dan sales context.
2. Sistem membaca konfigurasi assistant dari tenant.
3. Sistem mendeteksi greeting, thanks, clarify, dan intent.
4. Search query dibangun dari pertanyaan user dan histori chat.
5. Search query dikirim ke embedding API.
6. Embedding dipakai untuk mencari top matches di Qdrant.
7. Jika context ditemukan, sistem membangun prompt dengan:
   • system instructions
   • business context
   • conversation history
   • flow data
   • knowledge context
8. LLM menghasilkan jawaban.
9. Jawaban dibersihkan dari format yang tidak diinginkan.
10. Jika jawaban valid, dikembalikan ke webhook service.
11. Jika tidak valid, sistem mengembalikan fallback.

D. Fallback Improvement Workflow

1. Jika RAG gagal menemukan jawaban, pertanyaan dicatat sebagai unanswered lead.
2. Dashboard menampilkan fallback terbaru.
3. Admin membuka AI Training atau Knowledge.
4. Admin menambahkan jawaban yang benar ke knowledge.
5. Admin menjalankan reindex.
6. Pertanyaan serupa berikutnya dapat dijawab oleh RAG.

E. Manual Takeover Workflow

1. Admin membuka conversation detail.
2. Admin mengaktifkan takeover.
3. Conversation status berubah menjadi takeover.
4. Pesan user tetap masuk ke inbox.
5. Bot berhenti menjawab otomatis.
6. Admin membalas manual dari dashboard.
7. Setelah selesai, admin release takeover.
8. Bot kembali aktif untuk conversation tersebut.

6. Database Model Overview

Beberapa table utama:

• tenants: data bisnis/tenant.
• app_users: user dashboard dan role.
• wa_instances: status WhatsApp instance per tenant.
• conversations: thread percakapan pelanggan.
• conversation_messages: histori pesan user, assistant, admin, dan system.
• knowledge_sources: sumber knowledge yang dikelola admin.
• unanswered_leads: pertanyaan yang gagal dijawab AI.
• processed_messages: deduplication webhook.
• rag_configs: konfigurasi RAG per tenant.
• assistant_templates: template assistant global/custom.

7. Deployment Workflow

Deployment disiapkan menggunakan Docker Compose untuk Dokploy.

Service utama:

• frontend: Vue dashboard yang diserve via Nginx.
• backend: NestJS API.
• postgres: database utama.
• redis: dependency cache untuk Evolution API.
• qdrant: vector database.
• evolution-api: WhatsApp gateway.

Volume persisten:

• postgres_data
• redis_data
• qdrant_data
• evolution_instances
• uploads_data
• knowledge_data

Environment penting:

• DATABASE_URL
• JWT_SECRET
• COOKIE_SECRET
• EVOLUTION_API_KEY
• EVOLUTION_API_URL
• EVOLUTION_WEBHOOK_URL
• LLM_BASE_URL
• LLM_API_KEY
• CHAT_MODEL
• EMBEDDING_BASE_URL
• EMBEDDING_API_KEY
• EMBEDDING_MODEL
• QDRANT_URL
• QDRANT_COLLECTION

8. Talking Points

Why RAG?

Saya menggunakan RAG karena chatbot customer support harus menjawab berdasarkan informasi bisnis yang bisa berubah, seperti harga, jadwal, syarat, alamat, atau prosedur. Dengan RAG, knowledge bisa diperbarui dari dashboard tanpa perlu retrain model.

Why Qdrant?

Qdrant digunakan sebagai vector database untuk mencari knowledge yang paling relevan berdasarkan semantic similarity. Ini lebih fleksibel dibanding pencarian keyword biasa, terutama untuk pertanyaan pelanggan yang bahasanya tidak selalu sama dengan isi knowledge.

Why NestJS?

NestJS cocok untuk backend yang modular. Project ini punya banyak domain seperti auth, WhatsApp, webhook, conversation, knowledge, RAG, dashboard, tenant, dan user. Dengan NestJS, setiap domain bisa dipisah menjadi module, controller, dan service.

How does the system prevent duplicate webhook processing?

Setiap webhook message memiliki messageId. Backend menyimpan kombinasi tenantId dan messageId di table processed_messages. Jika webhook yang sama masuk lagi, insert akan gagal karena unique constraint, lalu request dianggap deduplicated.

How does manual takeover work?

Conversation memiliki field takeoverEnabled dan status. Jika takeover aktif, webhook tetap menyimpan pesan user, tetapi tidak menjalankan RAG auto-reply. Admin bisa membalas manual dari dashboard, lalu release takeover untuk mengaktifkan bot lagi.

What happens when AI cannot answer?

Jika Qdrant tidak menemukan context yang cukup relevan atau LLM tidak menghasilkan jawaban valid, sistem mengirim fallback reply dan menyimpan pertanyaan ke unanswered_leads. Data ini ditampilkan di dashboard agar admin bisa memperbaiki knowledge.

How is tenant isolation handled?

Data utama seperti conversation, message, knowledge, lead, RAG config, dan WhatsApp instance memiliki tenantId. Query backend memfilter data berdasarkan tenant user yang sedang login, sehingga setiap tenant hanya mengakses data miliknya.

What was the hardest part?

Bagian paling menantang adalah mengatur flow percakapan agar AI tetap natural tetapi tidak mengarang informasi. Untuk itu sistem memakai RAG, fallback handling, prompt rules, conversation history, lead context, dan manual takeover agar automation tetap bisa dikontrol admin.