← Dokumentasi

Panduan Kiosapi Konek

Kiosapi Konek membalas pesan pelanggan Anda secara otomatis memakai AI, berdasarkan dokumen (FAQ, daftar harga, info produk/jasa) yang Anda unggah sendiri. Telegram, widget Website, dan WhatsApp aktif sekarang — daftar sendiri lewat dashboard tanpa menunggu proses apa pun. Panduan ini mencakup semua langkah dari nol: menghubungkan channel di setiap platform, mengunggah & menghubungkan dokumen, mengustomisasi tampilan widget Website, sampai pemecahan masalah umum.

1. Apa itu Konek

Konek menghubungkan channel Telegram, widget Website, atau nomor WhatsApp Business Anda ke asisten AI Kiosapi. Saat pelanggan mengirim pesan, bot mencari jawaban di dokumen yang sudah Anda unggah (mekanisme disebut RAG — Retrieval-Augmented Generation: cari bagian dokumen yang paling relevan, lalu minta AI menjawab berdasarkan bagian itu saja), dan membalas otomatis di channel yang sama. Jika pertanyaan tidak bisa dijawab dari dokumen yang tersedia, bot menjawab jujur bahwa ia tidak tahu (tidak mengarang jawaban) dan Anda mendapat notifikasi email agar bisa menindaklanjuti secara manual.

Setiap channel punya dokumen sendiri-sendiri — Anda bisa punya beberapa channel (lintas platform maupun beberapa channel di platform yang sama, mis. dua bot Telegram untuk dua lini bisnis) untuk beberapa lini bisnis/produk berbeda, masing-masing hanya menjawab dari dokumennya sendiri. Lihat /dashboard/konek untuk mulai, atau halaman /konek untuk gambaran umum produk.

2. Mendaftarkan channel

Buka /dashboard/konek dan pilih jenis channel yang ingin didaftarkan. Telegram, Website, dan WhatsApp bisa langsung dihubungkan sendiri, aktif seketika tanpa menunggu proses apa pun.

Channel Telegram

Yang dibutuhkan: akun Telegram (untuk bicara ke @BotFather). Tidak perlu server, domain, atau nomor telepon.

1. Di Telegram, buka chat dengan @BotFather → kirim /newbot.
2. Isi nama tampilan bot, lalu username bot — WAJIB diakhiri "bot"
   (mis. tokoku_cs_bot).
3. @BotFather membalas dengan token, bentuknya  123456789:AAExxxxxxxxxxxx
4. Dashboard → Konek → Tambah Channel → pilih Telegram.
5. Tempel token bot, pilih tier model (§7), (opsional) email notifikasi.
6. Klik "Daftarkan Channel". Kiosapi mendaftarkan webhook ke bot Anda
   otomatis — bot langsung aktif.

Catatan. Token bocor atau di-revoke di @BotFather? Buat token baru (/revoke) lalu tempel yang baru lewat Edit pada baris channel (§8) — webhook otomatis didaftarkan ulang. Menghapus channel Telegram di Kiosapi juga otomatis melepas webhook dari bot. Satu bot hanya boleh terhubung ke satu channel Konek pada satu waktu.

Channel Website (widget)

Yang dibutuhkan: situs web ber-HTTPS yang Anda kelola dan bisa menempelkan satu tag <script>.

1. Dashboard → Konek → Tambah Channel → pilih Website.
2. Masukkan domain tempat widget dipasang — satu per baris, mis.
   https://tokoku.com
   https://www.tokoku.com
3. Pilih tier model (§7), (opsional) email notifikasi & reranker.
4. Klik "Daftarkan Channel".
5. Pada baris channel, klik ikon </>  untuk menyalin kode embed:
   <script src="https://api.kiosapi.id/widget.js" data-channel="ID"></script>
6. Tempel kode itu tepat sebelum </body> di halaman situs Anda.

Catatan. Widget hanya dimuat dari domain yang terdaftar di langkah 2 — permintaan dari domain lain ditolak. Untuk uji di localhost atau domain staging, tambahkan domain itu sebagai baris tersendiri. Warna, ikon, teks sapaan, posisi, dan ukuran widget diatur di panel Kustomisasi Widget (§4), bisa diubah kapan saja tanpa mengganti kode embed. Widget menyimpan ID pengunjung di localStorage browser agar riwayat percakapan tetap nyambung saat halaman dibuka lagi.

Channel WhatsApp

Yang dibutuhkan: akun Facebook Business + sebuah nomor telepon baru (belum pernah dipakai di aplikasi WhatsApp / WhatsApp Business — lihat peringatan penting di §3).

1. Dashboard → Konek → Tambah Channel → pilih WhatsApp.
2. Pilih tier model (§7) dan, kalau perlu, email notifikasi.
3. Klik "Hubungkan WhatsApp" — halaman resmi Meta terbuka.
4. Di halaman Meta: pilih Portofolio Bisnis → akun WhatsApp Business →
   nomor telepon → verifikasi kode SMS/telepon bila diminta.
5. Selesai — Anda kembali ke dashboard, channel langsung Aktif.
   Tidak ada token, App ID, atau webhook yang perlu Anda salin.

Alur ini memakai Embedded Signup resmi Meta. Detail penting — kenapa nomornya harus baru, dan cara mengganti/memperbaiki koneksi — ada di §3.

3. Menghubungkan WhatsApp

Menghubungkan WhatsApp memakai alur resmi Meta — Anda tidak perlu membuat token, mencari ID, atau menyetel apa pun secara manual. Semua itu diurus otomatis setelah Anda memberi izin lewat halaman Meta.

Langkah-langkah

1. Buka Dashboard → Konek → Tambah Channel → WhatsApp.
2. Pilih tier model (§7) dan, kalau perlu, email notifikasi.
3. Klik "Hubungkan WhatsApp" — halaman resmi Meta terbuka.
4. Pilih Portofolio Bisnis, WhatsApp Business Account, dan
   nomor telepon (masukkan nomor baru bila diminta, lalu
   verifikasi lewat SMS/panggilan).
5. Selesai — channel langsung aktif, tanpa menyalin token
   atau ID apa pun.

Kalau Anda kembali dari Meta sebelum selesai, tidak ada channel yang dibuat — cukup klik Hubungkan WhatsApp lagi untuk mengulang. Satu nomor telepon hanya bisa dihubungkan sekali; menghubungkan nomor yang sama dua kali akan ditolak.

Untuk mengganti nomor atau memperbaiki koneksi WhatsApp sebuah channel, putuskan dulu (ikon tempat sampah pada baris channel — untuk WhatsApp ini melepas koneksi Meta, bukan sekadar menghapus data, §8), lalu hubungkan ulang. Tidak ada token yang perlu diperbarui secara manual.

Penting untuk semua jenis channel: channel baru belum punya dokumen apa pun terhubung. Sebelum bot bisa menjawab pertanyaan pelanggan dengan berguna, lanjut ke bagian §5 dan §6 untuk mengunggah dan menghubungkan dokumen.

4. Kustomisasi widget Website

Khusus channel Website, tampilan widget bisa disesuaikan dengan identitas merek Anda. Buka Edit pada channel Website yang sudah didaftarkan (§8) untuk melihat panel Kustomisasi Widget:

• Warna utama — warna bubble, header jendela chat, dan tombol kirim.
• Ikon bubble — ketik emoji apa saja, atau unggah gambar/logo sendiri (PNG/JPEG/WebP, maks 500 KB) — unggah gambar tersedia setelah channel disimpan sekali.
• Posisi, ukuran, sudut — kiri/kanan; kompak/standar/besar; kotak/membulat/pil.
• Teks header, placeholder input, pesan sapaan — sesuaikan bahasa widget dengan gaya bisnis Anda.
• Sapaan otomatis — gelembung kecil yang muncul sendiri di samping bubble setelah beberapa detik (bisa diatur), maksimal sekali per sesi kunjungan.
• Animasi berdenyut — bubble berdenyut halus untuk menarik perhatian pengunjung.

Setiap perubahan langsung terlihat di panel Pratinjau langsung di bawah form — ini me-render widget yang sesungguhnya (bukan tiruan), jadi apa yang Anda lihat di pratinjau akan identik dengan yang dilihat pengunjung situs Anda setelah Anda klik Simpan Perubahan. Kustomisasi bersifat opsional sepenuhnya — channel tanpa kustomisasi apa pun memakai tampilan bawaan Kiosapi.

5. Basis pengetahuan (dokumen)

Dokumen adalah sumber jawaban bot Anda. Kelola dokumen di /dashboard/documents — halaman yang sama dipakai oleh fitur Chat Kiosapi, jadi dokumen yang sudah Anda unggah sebelumnya bisa langsung dipakai ulang untuk Konek (lihat §6 untuk cara menghubungkannya ke channel tertentu).

Format & batasan file

Bagaimana isi dokumen diproses

Saat Anda mengunggah dari dashboard, PDF bertipe teks asli dan Excel (.xlsx) dibaca langsung di browser Anda — cepat, tanpa OCR/AI. Gambar dan PDF hasil pindai/foto (tanpa lapisan teks) otomatis dialihkan ke OCR (pengenalan teks otomatis) di server untuk mengekstrak teksnya. Setelah itu, teksnya dipecah menjadi potongan-potongan kecil yang bisa dicari AI saat menjawab pertanyaan. Karena itu:

• Dokumen berbasis teks (PDF hasil export Word/Google Docs, file Excel, screenshot teks yang jelas) memberi hasil paling akurat.
• Hasil pindai/foto yang buram, miring, atau resolusi rendah bisa gagal diproses (OCR tidak menemukan teks) — akan ditolak dengan pesan error, coba foto ulang dengan pencahayaan & fokus lebih baik.
• Isi yang melanggar kebijakan konten (mis. konten ilegal/berbahaya) akan ditolak saat proses moderasi otomatis, sebelum sempat tersimpan.

Jenis konten yang cocok diunggah

Konek bekerja paling baik untuk pertanyaan yang jawabannya benar-benar ada di dokumen Anda — bukan pertanyaan umum di luar bisnis Anda. Contoh dokumen yang efektif:

• FAQ — daftar pertanyaan & jawaban yang paling sering ditanyakan pelanggan (jam operasional, cara pemesanan, kebijakan retur/refund, area pengiriman).
• Daftar harga / katalog produk — nama produk/jasa, harga, varian, spesifikasi singkat.
• Info bisnis — alamat, metode pembayaran yang diterima, cara menghubungi manusia untuk kasus yang lebih rumit.
• Syarat & ketentuan layanan — kebijakan garansi, pembatalan, atau SOP layanan pelanggan yang ingin dijawab bot secara konsisten.

Semakin jelas dan terstruktur dokumen Anda (poin-poin, tabel, judul per topik), semakin mudah bot menemukan potongan yang tepat saat menjawab.

6. Menghubungkan dokumen ke channel

Mengunggah dokumen di /dashboard/documents saja belum membuatnya terlihat oleh channel manapun — setiap channel punya daftar dokumen sendiri yang harus dihubungkan secara eksplisit. Ini sengaja dipisahkan supaya channel untuk lini bisnis berbeda tidak saling mencampur jawaban (channel A tidak akan menjawab pakai info produk channel B).

Caranya, dari halaman Konek:

/dashboard/konek
  1. Pada baris channel yang dituju, klik ikon dokumen
     ("Kelola Dokumen")
  2. Muncul daftar semua dokumen berstatus "siap" milik Anda
  3. Centang dokumen yang relevan untuk channel ini
     (boleh lebih dari satu — mis. FAQ + daftar harga sekaligus)
  4. Klik "Simpan"

Satu dokumen boleh dicentang di banyak channel sekaligus (mis. FAQ umum yang berlaku untuk semua nomor toko Anda) — dokumen tidak perlu diunggah ulang per channel. Klik "Simpan" menggantikan seluruh daftar dokumen channel tersebut dengan yang baru dicentang (bukan menambah), jadi pastikan semua dokumen yang masih ingin dipakai tetap tercentang sebelum menyimpan.

Jika sebuah channel belum punya dokumen terhubung sama sekali, bot akan langsung menjawab dengan pesan bahwa ia belum bisa membantu untuk setiap pesan masuk (tidak mencoba menjawab tanpa sumber), dan Anda menerima notifikasi email untuk channel tersebut. Hubungkan minimal satu dokumen agar bot bisa mulai menjawab.

7. Tier model & harga

Setiap channel memilih satu dari tiga tier model saat didaftarkan (bisa diganti kapan saja lewat Edit, §8). Ketiganya dikenai biaya flat per balasan — bukan per token seperti Chat biasa, sehingga biaya per pesan selalu bisa diprediksi dan tidak berubah ikut kurs.

Biaya hanya dipotong dari saldo Rupiah Anda setelah balasan berhasil terkirim ke pelanggan — jika pengiriman gagal, tidak ada biaya yang dikenakan.

8. Edit, nonaktifkan, hapus channel

Setiap baris channel di /dashboard/konek punya beberapa aksi cepat:

• Kelola Dokumen (ikon dokumen) — lihat §6.
• Kode embed (ikon </>, khusus channel Website) — lihat/salin ulang kode embed widget, lihat §2.
• Edit (ikon pensil) — mengisi ulang form pendaftaran dengan data channel tersebut, termasuk domain, tier model, email notifikasi, dan (khusus Website) kustomisasi widget (§4). Untuk Telegram, kolom token bot sengaja dikosongkan saat edit — biarkan kosong jika hanya ingin mengubah field lain, atau isi token baru jika yang lama sudah dicabut. WhatsApp tidak punya kolom kredensial sama sekali — kalau koneksinya bermasalah, putuskan lalu hubungkan ulang (lihat butir Hapus di bawah).
• Aktifkan / Nonaktifkan — toggle satu klik. Channel nonaktif berhenti membalas pesan sama sekali tanpa perlu menghapus data channel/dokumennya — berguna untuk menjeda sementara (mis. sedang libur) tanpa kehilangan riwayat pengaturan.
• Hapus (ikon tempat sampah) — meminta konfirmasi, lalu menghapus channel secara permanen (bot berhenti total membalas nomor ini). Riwayat percakapan & keterhubungan dokumen channel tersebut ikut terhapus; dokumen itu sendiri (yang mungkin masih dipakai channel lain) tidak ikut terhapus. Untuk channel WhatsApp, aksi ini juga memutus koneksi ke Meta — pesannya berbunyi "Putuskan koneksi WhatsApp". Nomor yang sama bisa dihubungkan lagi kapan pun lewat Hubungkan WhatsApp.

Email Notifikasi — opsional, di form pendaftaran/edit. Kosongkan untuk memakai email akun Kiosapi Anda (default); isi untuk mengarahkan notifikasi channel ini (pertanyaan belum terjawab, saldo habis, tanpa dokumen) ke email lain — berguna kalau Anda punya beberapa channel untuk lini bisnis berbeda.

9. Cara bot menjawab pesan

Ringkasan alur satu pesan masuk, sama untuk Telegram, Website, maupun WhatsApp — agar ekspektasi jelas:

Pelanggan kirim pesan (Telegram/widget Website/WhatsApp)
  → diteruskan ke Kiosapi (untuk WhatsApp lewat webhook Meta)
  → Kiosapi cek dokumen yang terhubung ke channel ini (§6)
     - kosong → balas "belum bisa membantu" + email notifikasi ke Anda
     - ada → cari potongan dokumen paling relevan dengan pertanyaan
  → jika kecocokan cukup kuat → model AI (tier channel, §7) menyusun jawaban
  → jika kecocokan lemah/tidak yakin → balas jujur "belum bisa membantu"
    + email notifikasi (tidak mengarang jawaban)
  → balasan terkirim ke pelanggan → biaya dipotong (§7)

Bot mempertimbangkan beberapa pesan terakhir dalam percakapan yang sama untuk memahami konteks (mis. pertanyaan lanjutan seperti "kalau yang itu berapa?"), bukan hanya pesan tunggal yang baru masuk.

Tautan halaman. Jika dokumen yang terhubung memuat URL (mis. link halaman produk, formulir pemesanan, atau kebijakan lengkap), bot boleh menyertakan URL itu apa adanya di dalam jawaban — ia tidak pernah mengarang atau menebak alamat. Di Telegram dan WhatsApp, URL polos otomatis jadi tautan yang bisa diklik; di widget Website, URL dalam balasan otomatis dirender sebagai tautan (buka di tab baru). Supaya fitur ini berguna, tuliskan URL lengkap (diawali https://) di dalam dokumen Anda.

10. Memasang widget di berbagai platform

Widget Website hanyalah satu tag <script> — tidak ada paket npm, tanpa langkah build. Tujuannya sama di semua platform: menaruh baris berikut sekali di setiap halaman tempat widget ingin muncul, idealnya tepat sebelum penutup </body>. ID channel diambil dari tombol </> pada baris channel di /dashboard/konek (§2).

<script src="https://api.kiosapi.id/widget.js" data-channel="ID_CHANNEL_ANDA"></script>

Pastikan domain tempat widget dipasang sudah terdaftar di daftar "Domain yang Diizinkan" channel tersebut (§2) — kalau tidak, widget menolak memuat.

HTML statis / situs buatan sendiri

Buka file template yang dipakai semua halaman (mis. index.html, layout.html) dan tempel tag <script> tepat sebelum </body>. Selesai.

WordPress

Tanpa plugin (tema klasik):
  Appearance → Theme File Editor → footer.php
  → tempel <script...> tepat sebelum </body> → Update File
  (lebih aman: pakai child theme agar tidak hilang saat tema di-update)

Lewat plugin (disarankan, tahan update tema):
  Pasang "WPCode" atau "Insert Headers and Footers"
  → Footer / "Before </body>" → tempel tag <script...> → Save

Block theme (Full Site Editing, tanpa footer.php):
  pakai plugin WPCode di atas — cara paling andal.

Shopify

Online Store → Themes → ... → Edit code
  → Layout/theme.liquid → tempel <script...> tepat sebelum </body>
  → Save. Widget muncul di semua halaman etalase.

Laravel (Blade)

resources/views/layouts/app.blade.php  (atau layout utama Anda)
  ...
      @stack('scripts')
      <script src="https://api.kiosapi.id/widget.js"
              data-channel="ID_CHANNEL_ANDA"></script>
    </body>
  </html>

Kalau hanya di halaman tertentu, bungkus dengan @push('scripts') ... @endpush
di view terkait, dan pastikan layout memanggil @stack('scripts') sebelum </body>.

React / Next.js / Vue / SPA lain

Muat script sekali di level dokumen, bukan di dalam komponen yang sering re-render.

Next.js (App Router) — app/layout.tsx:
  import Script from 'next/script';
  ...
  <body>
    {children}
    <Script src="https://api.kiosapi.id/widget.js"
            data-channel="ID_CHANNEL_ANDA" strategy="afterInteractive" />
  </body>

Next.js (Pages Router) — pages/_document.tsx: taruh <script ...> di dalam <body>
  setelah <Main /> dan <NextScript />.

Vite/CRA/Vue: tempel tag <script...> di public/index.html sebelum </body>.

Google Tag Manager

Tags → New → Custom HTML → isi:
  <script src="https://api.kiosapi.id/widget.js"
          data-channel="ID_CHANNEL_ANDA"></script>
Trigger: All Pages (atau halaman tertentu) → Save → Submit/Publish.

Catatan: GTM menyuntik script ke <head>. Widget tetap jalan
(ia menunggu DOM siap sendiri), jadi ini aman.

Wix / Squarespace / Webflow

Wix:         Settings → Custom Code → Add Custom Code → tempel tag,
             pasang di "Body - end", Apply to "All pages".
Squarespace: Settings → Advanced → Code Injection → Footer → tempel tag.
Webflow:     Project Settings → Custom Code → Footer Code → tempel tag → Publish.

Prinsipnya sama di mana pun: satu tag <script>, sebelum </body> (atau slot "footer"/"before body end" yang disediakan platform), dan domainnya terdaftar. Tidak perlu memuat ulang kode saat Anda mengubah warna/teks/ikon widget — kustomisasi (§4) diterapkan otomatis dari server.

11. Kotak Masuk — balas manual

Tab Kotak Masuk di /dashboard/konek memungkinkan Anda membaca percakapan dan membalas pelanggan sendiri — berguna saat bot mengoper pertanyaan ke tim, atau ketika Anda ingin mengambil alih percakapan. Tersedia untuk channel Telegram dan widget Website. Channel WhatsApp tidak ada di sini karena nomor telepon/SMS-nya sudah jadi jalur fallback yang bisa Anda pakai langsung.

• Daftar percakapan — satu baris per pelanggan, dengan penanda jumlah pesan belum dibaca dan tanda percakapan yang di-eskalasi bot (pertanyaan yang tidak bisa dijawab dari dokumen atau kepercayaan jawabannya rendah).
• Buka percakapan — lihat seluruh riwayat; membukanya menandai pesan pelanggan sebagai sudah dibaca.
• Kirim balasan — untuk Telegram, balasan langsung dikirim ke pelanggan lewat bot/Page (kalau pengiriman gagal, Anda diberi tahu — tidak disimpan seolah terkirim). Untuk widget Website, balasan disimpan dan muncul di widget pengunjung saat mereka membukanya lagi (widget mengecek pesan baru secara berkala selama jendela chat terbuka).

Balasan manual tidak dikenai biaya dan tidak melewati moderasi (dianggap konten resmi dari Anda). Membalas sebuah percakapan yang di-eskalasi otomatis menandainya selesai. Notifikasi email untuk pertanyaan yang di-eskalasi (§9) kini menautkan langsung ke Kotak Masuk untuk Telegram/Website.

12. Pemecahan masalah

13. Batasan saat ini

• Nomor WhatsApp harus khusus untuk Konek — sebuah nomor yang sedang aktif di aplikasi WhatsApp Business di HP tidak bisa dipakai; menghubungkannya ke Konek akan memutusnya dari aplikasi di HP sepenuhnya (§3). Siapkan nomor baru.
• Dukungan platform lain di luar Telegram, Website, dan WhatsApp (mis. Shopee Message) belum tersedia.

Butuh akses lewat API/SDK langsung untuk kebutuhan lain (chat, gambar, dsb.)? Lihat dokumentasi utama di /docs, atau kembali ke /dashboard/konek untuk mulai mendaftarkan channel.