AI Assistant

AI assistant membalas pesan inbound secara otomatis per inbox. Owner menyiapkan provider. Owner atau admin mengatur perilaku inbox, basis pengetahuan, dan memantau job. Agen dapat mengambil alih percakapan kapan saja.

Alur kerja

1. Pesan inbound masuk ke inbox dengan AI aktif.
2. Sistem membatalkan job queued lama pada percakapan itu, lalu membuat satu job baru setelah Debounce.
3. Worker hanya memproses job saat percakapan berstatus ai_handling.
4. Worker membaca riwayat pesan non-private, sampai batas History limit yang dikonfigurasi deployment.
5. Worker mencari source knowledge yang published, lalu menerapkan mode knowledge dan fallback inbox.
6. Jika provider boleh dipanggil, worker meminta respons dari model, menyimpan pesan keluar berlabel nama assistant, lalu mengantrikan pengiriman kanal.
7. Job tercatat sebagai completed, failed, cancelled, atau status retry. Recent AI jobs menampilkan sampai 100 job terbaru.

Pesan baru selama masa debounce menggantikan job queued sebelumnya. Mengambil alih percakapan membatalkan job queued atau running; worker juga membatalkan job bila status percakapan bukan ai_handling.

Prasyarat deployment

• Inbox dan provider kanal harus sudah berfungsi.
• Jalankan migrasi AI, termasuk 076_ai_chatbot.sql sampai 083_ai_takeover_message.sql pada deployment ini.
• Set OPENAI_CONFIG_ENCRYPTION_KEY menjadi key AES-256 base64 32-byte. Server menolak start worker bila key kosong atau tidak valid.
• Gunakan URL provider API yang dapat dijangkau API server.
• Untuk refresh URL source otomatis, set opsional KNOWLEDGE_REFRESH_DATABASE_URL. Scanner tidak pernah memakai DATABASE_URL sebagai fallback.

Jangan simpan API key, token, password, cookie, URL berkredensial, atau data pelanggan tidak perlu dalam prompt, source knowledge, tiket, maupun log.

1. Siapkan provider AI

Hanya owner dapat membuka Settings → AI provider.

1. Isi Provider URL.
2. Isi API key.
3. Simpan.

API key terenkripsi saat disimpan dan write-only: GET tidak pernah mengembalikan nilainya. Untuk mengganti URL tanpa merotasi key, kosongkan field API key sebelum menyimpan.

API owner-only: GET dan PUT /api/v1/admin/openai-settings.

2. Atur assistant per inbox

Buka sidebar AI, pilih inbox, lalu atur:

• Enable AI responses — mengaktifkan atau menonaktifkan job balasan inbox.
• Model — model provider untuk inbox.
• Debounce (ms) — 250–60000 ms sebelum job dibuat.
• Requests per minute — 1–10000 request per menit untuk inbox.
• Daily token budget — 1–100000000 token per hari untuk inbox.
• Takeover message — pesan saat agen mengambil alih. Wajib memuat {{name}}; placeholder diganti nama agen.
• Assistant name — nama publik pesan AI, 1–100 karakter. Default AI assistant.
• Operator instructions — instruksi tambahan untuk provider, maksimal 8000 karakter.
• Knowledge mode — grounded_only atau hybrid.
• When knowledge is insufficient — handover atau no_reply.

Simpan dengan Save AI configuration. Owner dan admin dapat memakai API GET/PUT /api/v1/inboxes/:inbox_id/ai-config.

Gunakan Send test untuk memeriksa konfigurasi tersimpan tanpa membuat pesan percakapan atau job. Endpoint POST /api/v1/inboxes/:inbox_id/ai-config/test menerima prompt 1–4000 karakter. Test butuh provider terkonfigurasi serta AI inbox aktif.

3. Kelola knowledge

Buka Settings → AI knowledge sebagai owner atau admin.

Source library

Buat source dengan salah satu kind:

• FAQ — satu pertanyaan/jawaban yang disetujui.
• Article — konten manual lebih panjang.
• URL — halaman publik yang diimpor.

Title wajib, maksimal 500 karakter. Content maksimal 1 MiB. Source baru default draft; hanya published ikut grounding. Archive source yang tidak lagi berlaku.

Untuk source URL:

• URL harus http atau https, publik, tanpa userinfo/kredensial.
• Import menolak alamat private/internal untuk mencegah SSRF.
• Fetch dibatasi 2 MiB, teks ekstrak 1 MiB, dan maksimal tiga redirect.
• Import membuat draft. Review lalu publish sebelum dipakai assistant.
• Pilih refresh manual, daily, atau weekly. Refresh memicu import ulang sekarang.
• Refresh gagal tidak menghapus konten published terakhir; perbaiki URL atau layanan lalu ulangi.

API knowledge owner/admin:

GET/POST /api/v1/knowledge-sources
GET/PATCH/DELETE /api/v1/knowledge-sources/:id
POST /api/v1/knowledge-sources/import
POST /api/v1/knowledge-sources/:id/refresh

Knowledge gaps

Saat knowledge tidak cukup, worker dapat mencatat topic sebagai knowledge gap. Buka daftar Knowledge gaps, pilih outcome, lalu simpan:

• source_added
• not_applicable
• needs_human_handover

API: GET /api/v1/knowledge-gaps dan POST /api/v1/knowledge-gaps/:id/resolve.

Mode knowledge dan fallback

Mode	Source cukup	Source tidak cukup
grounded_only	Provider boleh menjawab dengan context source	Provider tidak dipanggil. Sistem merekam gap lalu menjalankan handover atau no_reply.
hybrid	Provider boleh menjawab dengan context source	Provider boleh menjawab tanpa grounding; gap tetap direkam.

Pilih grounded_only untuk jawaban yang harus didukung knowledge published. Pilih hybrid hanya bila risiko jawaban di luar source diterima oleh pemilik proses.

Pengambilan alih oleh agen

Agen dapat memilih takeover pada percakapan untuk mengubah status menjadi human_handling dan menghentikan AI. Sistem mencoba mengirim Takeover message sekali untuk tiap transisi takeover.

Pada WhatsApp, pengumuman tidak dikirim bila consent delivery tidak tersedia atau window free-form 24 jam sudah tertutup. UI menampilkan notice; takeover tetap terjadi. Resume mengubah status kembali menjadi ai_handling.

API percakapan:

POST /api/v1/conversations/:id/ai/takeover
POST /api/v1/conversations/:id/ai/resume
GET  /api/v1/conversations/:id/ai/status

Rate limit, budget, dan retry

Worker menerapkan request limit akun dan inbox serta daily token budget. Provider 429 dan respons 5xx dapat di-retry; kegagalan konfigurasi, grounding, atau batas budget tidak boleh diselesaikan dengan menyalin credential ke log.

Buka AI → Recent AI jobs untuk status, model, percobaan, latensi, dan token. Job failed atau dlq dapat diulang dari UI setelah penyebab diperbaiki. API: GET /api/v1/ai/jobs, GET /api/v1/ai/jobs/:id, dan POST /api/v1/ai/jobs/:id/retry.

Verifikasi setup

1. Konfigurasi provider pada workspace uji.
2. Buat source FAQ published untuk pertanyaan uji.
3. Aktifkan AI pada inbox uji, pilih grounded_only, lalu simpan.
4. Jalankan Send test untuk memastikan provider merespons.
5. Kirim pesan inbound yang cocok dengan FAQ.
6. Setelah debounce, refresh Recent AI jobs. Pastikan job selesai dan balasan memakai nama assistant.
7. Kirim pertanyaan tanpa bukti source. Pastikan tidak ada balasan provider pada grounded_only; gap tercatat dan fallback inbox berlaku.
8. Ambil alih percakapan, lalu kirim pesan inbound lagi. Pastikan AI tidak membalas sampai percakapan di-resume.