# CSKU Docs

> CSKU adalah platform customer service berbasis AI: satu inbox untuk WhatsApp, Telegram, Instagram, Facebook, Intercom, Slack, dan webchat, dengan AI agent yang membalas otomatis. Dokumentasi ini mencakup panduan dashboard dan referensi developer (Public API, webhook, webchat, WhatsApp API).

Fakta penting untuk integrasi:
- Base URL Public API: https://api.csku.ai. Auth: header `Business` + `Secret`, atau `Authorization: Bearer base64(biz_id:secret)`.
- Error dikirim sebagai HTTP 200 dengan `"status": 0` dan `error_msg`; cek body, bukan kode HTTP. Tidak ada rate limit.
- Webhook mengirim 3 event: channel.message_in, ai.message_generated, agent.message_out. Header `Authorization` berisi Secret Key. Balas body `{"success": true}`; kode HTTP diabaikan. Maksimal 4 percobaan.
- Proxy WhatsApp API memakai Bearer base64(biz_id|secret) dengan pemisah pipe, berbeda dari Public API.

---

Sumber: https://docs.csku.ai/

# Dokumentasi CSKU

> Panduan memakai dashboard CSKU dan referensi developer untuk Public API, webhook, webchat, dan WhatsApp API.


CSKU adalah platform customer service berbasis AI. Semua chat pelanggan dari WhatsApp, Telegram, Instagram, Facebook, Intercom, dan webchat masuk ke satu inbox. AI agent membalas otomatis, dan tim Anda mengambil alih kapan saja.

Dokumentasi ini dibagi untuk dua pembaca:

- [Panduan pengguna](https://docs.csku.ai/panduan/memulai): Hubungkan channel, buat AI agent, balas chat, dan atur tim dari dashboard.
- [Public API](https://docs.csku.ai/api/autentikasi): Kirim dan ambil pesan, tambah catatan, dan tandai percakapan butuh CS dari sistem Anda.
- [Webhook](https://docs.csku.ai/webhook/setup): Terima event pesan masuk, balasan AI, dan balasan agen secara real-time.
- [Webchat](https://docs.csku.ai/webchat/pasang): Pasang tombol chat di website atau tampilkan chat di aplikasi Android.

## Mulai cepat untuk developer

1. Pastikan paket Anda punya fitur **API** (dan **Webhook** jika perlu). Lihat [Berlangganan & kredit](https://docs.csku.ai/panduan/berlangganan).
2. Ambil **Business ID** dan buat **Secret Key** di dashboard. Lihat [Autentikasi](https://docs.csku.ai/api/autentikasi).
3. Kirim pesan pertama:

```bash
curl -X POST https://api.csku.ai/v1/message \
  -H "Business: BIZ_ID_ANDA" \
  -H "Secret: SECRET_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "CO_01J9Z3K8V2", "text": "Halo kak, pesanan sudah dikirim ya"}'
```

4. Pasang [webhook](https://docs.csku.ai/webhook/setup) agar sistem Anda tahu saat pelanggan membalas.

> **Catatan: Base URL**
>
> Semua endpoint Public API memakai `https://api.csku.ai`.

---

Sumber: https://docs.csku.ai/mulai/konsep

# Konsep dasar

> Istilah utama di CSKU, dari workspace dan channel sampai status percakapan dan kredit AI.


Halaman ini menjelaskan istilah yang dipakai di dashboard dan dokumentasi. Baca sekali sebelum mulai setup agar langkah di panduan lain lebih mudah diikuti.

## Workspace (bisnis)

Satu akun pemilik (owner) memiliki satu workspace. Nama bisnis diisi saat daftar dan bisa diubah di **Settings → Informasi Bisnis**. Semua channel, AI agent, kontak, percakapan, dan anggota tim berada di dalam workspace ini. Paket berlangganan dan kredit AI juga melekat ke workspace.

Untuk Public API, workspace dikenali lewat **Business ID**. Lihat [Autentikasi](https://docs.csku.ai/api/autentikasi).

## Channel

Channel adalah sumber chat pelanggan yang Anda hubungkan, misalnya satu nomor WhatsApp atau satu bot Telegram. Satu workspace bisa punya banyak channel, sesuai kuota paket. Setiap channel bisa diberi satu AI agent dan satu atau lebih divisi.

Jenis channel yang tersedia: WhatsApp (Scan QR), WhatsApp API (Token manual), WhatsApp API (Login Meta), Telegram, Instagram, Facebook, Intercom, Slack, SocialChat, dan Webchat. Detailnya ada di [Hubungkan channel](https://docs.csku.ai/panduan/channel).

## Percakapan

Setiap pelanggan yang menghubungi satu channel membentuk satu percakapan. Semua percakapan dari semua channel masuk ke menu **Chat**.

Setiap percakapan punya status. Status dipakai sebagai tab filter di inbox:

| Status | Arti |
| --- | --- |
| Belum Dibaca | Ada pesan masuk yang belum dibuka. |
| Butuh CS | AI mengalihkan ke manusia, atau sistem Anda menandainya lewat API. |
| Belum Ditangani | Pelanggan menunggu, belum ada penanganan. |
| Ditangani | Sudah dibalas oleh AI atau tim. |
| Selesai | Ditandai selesai oleh tim. |
| Diblokir | Pengguna diblokir. AI tidak membalas. |
| Dilewati | Percakapan di-skip. AI tidak membalas. |

Apakah balasan AI membuat status menjadi **Ditangani** atau tetap **Belum Ditangani** tergantung opsi **Tandai sebagai ditangani** di pengaturan AI agent.

## Mode AI dan ditangani manusia

Setiap percakapan selalu berada di salah satu dari dua mode:

- **Mode AI**: AI agent membalas pesan pelanggan secara otomatis.
- **Ditangani manusia**: anggota tim membalas. AI dijeda di percakapan ini.

Klik **Ambil alih** di header chat untuk pindah ke mode manusia. Klik **Kembalikan ke AI** untuk menyerahkan lagi ke AI. Menandai percakapan **Selesai** juga mengaktifkan AI kembali untuk pesan berikutnya.

AI bisa mengalihkan sendiri ke manusia jika kondisinya cocok dengan instruksi **CS Manusia** di AI agent. Percakapan lalu berstatus **Butuh CS**.

## Catatan internal

Catatan adalah pesan yang hanya terlihat oleh tim. Catatan tidak dikirim ke pelanggan. Pakai untuk serah terima antar-agen atau mencatat konteks. Varian khususnya, **Perbaikan AI**, dipakai untuk menulis koreksi atas jawaban AI. Lihat [Balas chat](https://docs.csku.ai/panduan/chat).

## AI agent

AI agent adalah "petugas virtual" yang membalas pelanggan. Anda mengatur perilakunya (prompt), pengetahuannya (teks, FAQ, file, website, produk), model AI, jadwal aktif, dan trigger untuk memanggil API Anda. Satu AI agent bisa dipakai di banyak channel. Lihat [AI Agent](https://docs.csku.ai/panduan/ai-agent).

## Kontak

Kontak tercatat otomatis saat pelanggan pertama kali chat. Menu **Kontak** menampilkan kontak dari semua channel. Anda bisa mencari berdasarkan nama atau nomor dan membuka chat langsung dari daftar.

## Divisi, tim, dan role

- **Tim**: anggota yang login ke dashboard atau aplikasi mobile untuk membalas chat.
- **Divisi**: kelompok anggota. Divisi menentukan channel mana yang terlihat oleh anggotanya.
- **Role**: kumpulan izin menu, misalnya boleh melihat Chat tapi tidak boleh membuka Berlangganan.

Pemilik akun (owner) melihat semua. Lihat [Tim & role](https://docs.csku.ai/panduan/tim).

## Kredit AI

Setiap balasan AI memotong kredit sesuai harga model yang dipilih. Paket memberi kredit gratis bulanan. Jika habis, sistem memakai kredit berbayar hasil top up. Jika keduanya habis, AI berhenti membalas. Lihat [Berlangganan & kredit](https://docs.csku.ai/panduan/berlangganan).

## Glosarium

| Istilah | Penjelasan singkat |
| --- | --- |
| Workspace | Bisnis Anda di CSKU, berisi semua data. |
| Channel | Satu sumber chat: nomor WA, bot, akun, widget. |
| Percakapan | Riwayat chat dengan satu pelanggan di satu channel. |
| Ambil alih | Pindah percakapan dari AI ke manusia. |
| Kembalikan ke AI | Serahkan percakapan lagi ke AI. |
| Catatan | Pesan internal, tidak terlihat pelanggan. |
| CSAT | Penilaian kepuasan 1–5 dari pelanggan. |
| FRT | First Response Time, waktu balasan pertama tim. |
| Template WABA | Pesan resmi yang disetujui Meta untuk WhatsApp API. |
| Kredit AI | Saldo untuk membayar balasan AI. |

---

Sumber: https://docs.csku.ai/panduan/memulai

# Memulai di dashboard

> Daftar akun, verifikasi, kenali menu, lalu siapkan channel dan AI agent pertama Anda.


Dashboard CSKU ada di `https://app.csku.ai`. Halaman ini memandu Anda dari daftar akun sampai AI agent pertama membalas pelanggan.

## Daftar akun

1. Buka `https://app.csku.ai` dan klik **Daftar**.
2. Isi **Nama**, **Email**, **Nomor HP**, dan **Nama Bisnis**, lalu klik **Lanjut**.
3. Buat **Password** dan ulangi di **Confirm Password**. Password minimal 8 karakter dan wajib berisi huruf, angka, dan karakter khusus.
4. Klik **Daftar**.

Anda juga bisa memakai **Daftar dengan Google**.

## Verifikasi akun

Setelah daftar, halaman **Verifikasi Akun** muncul. Verifikasi email dan nomor HP Anda:

1. Klik **Kirim OTP** di bagian **Email**, lalu masukkan kode yang masuk ke email.
2. Lakukan hal yang sama untuk nomor HP. Kode bisa dikirim lewat WhatsApp atau SMS.
3. Setelah keduanya berstatus **Terverifikasi**, klik **Lanjutkan ke Dashboard**.

## Login

Buka `https://app.csku.ai`, isi **Email** dan **Password**, lalu klik **Login**. Anda juga bisa memakai **Masuk dengan Google**. Lupa password? Klik **Lupa Password?** untuk menerima link reset.

> **Catatan: Akun anggota tim**
>
> Anggota tim tidak mendaftar sendiri. Owner membuat akun mereka dari **Settings → Manajemen Tim**. Lihat [Tim & role](https://docs.csku.ai/panduan/tim).

## Kenali menu

Menu ada di sidebar kiri. Anggota tim hanya melihat menu yang diizinkan oleh role mereka.

| Menu | Fungsi |
| --- | --- |
| Dashboard | Ringkasan: total channel, AI agent, kontak, dan sisa AI kredit. |
| Chat | Inbox semua percakapan dari semua channel. |
| Kontak | Daftar pelanggan dari semua channel. |
| AI Agent | Buat dan atur agent yang membalas otomatis. |
| Tools → MCP Server, NPX Server | Hubungkan tools eksternal yang bisa dipakai AI agent. |
| Analitik → CSAT, FRT | Kepuasan pelanggan dan kecepatan respons tim. |
| Integrasi | Hubungkan dan kelola channel. |
| Settings | Profil, informasi bisnis, password, tim, webhook, secret key. |
| Berlangganan | Paket, invoice, dan mutasi AI kredit. |
| Help | Panduan langkah demi langkah di dalam dashboard. |

Klik nama Anda di bawah sidebar untuk membuka **Profil**, mengganti **Tema gelap**, atau **Keluar**.

## Urutan setup pertama

Ikuti urutan ini agar tidak ada langkah yang terlewat.

### 1. Pilih paket

Buka **Berlangganan** dan pastikan paket Anda aktif. Paket menentukan jumlah channel, AI agent, anggota tim, dan kredit AI gratis bulanan. Lihat [Berlangganan & kredit](https://docs.csku.ai/panduan/berlangganan).

### 2. Hubungkan channel

Buka **Integrasi**, pilih jenis channel, lalu klik **Setup**. Ikuti langkah sesuai channel. Lihat [Hubungkan channel](https://docs.csku.ai/panduan/channel).

### 3. Buat AI agent

Buka **AI Agent**, klik **Tambah Agent**. Pilih template sesuai jenis bisnis atau tulis sendiri **Perilaku AI**, lalu klik **Buat Agent**. Lengkapi pengetahuan bisnis Anda. Lihat [AI Agent](https://docs.csku.ai/panduan/ai-agent).

### 4. Hubungkan AI ke channel

Kembali ke **Integrasi**, buka channel Anda, lalu klik **Pilih AI** di kartu channel. Pilih agent dan klik **Simpan**. Tanpa langkah ini, AI tidak membalas di channel tersebut.

### 5. Tes

1. Di halaman AI agent, klik **Uji Chat** untuk mencoba jawaban AI tanpa mengirim pesan ke pelanggan.
2. Kirim pesan dari nomor atau akun lain ke channel Anda.
3. Buka **Chat**. Pesan harus muncul, dan AI membalas jika mode AI aktif.

> **Tips: AI tidak membalas?**
>
> Periksa empat hal: channel berstatus **Terhubung**, AI agent sudah dipilih di channel, jadwal AI sedang aktif, dan AI kredit masih tersedia.

## Langkah berikutnya

- [Balas chat](https://docs.csku.ai/panduan/chat): Ambil alih, catatan, balasan cepat, dan CSAT.
- [Tim & role](https://docs.csku.ai/panduan/tim): Tambah anggota dan atur siapa melihat channel apa.
- [Aplikasi mobile](https://docs.csku.ai/panduan/aplikasi-mobile): Balas chat dari HP.

---

Sumber: https://docs.csku.ai/panduan/channel

# Hubungkan channel

> Cara menghubungkan WhatsApp, Telegram, Instagram, Facebook, Intercom, Slack, SocialChat, dan Webchat ke CSKU.


Semua channel dikelola dari menu **Integrasi**. Setiap kartu menampilkan jenis channel dan status **Terhubung** atau **Belum**. Klik **Setup** untuk channel baru atau **Kelola** untuk channel yang sudah ada.

## Ringkasan channel

| Channel | Yang Anda perlukan | Cara hubung |
| --- | --- | --- |
| WhatsApp (Scan QR) | HP dengan WhatsApp aktif | Scan QR |
| WhatsApp API (Token manual) | Token, WABA ID dari Meta | Isi form 3 langkah |
| WhatsApp API (Login Meta) | Akun Facebook Business Manager | Popup Facebook |
| Telegram | Bot token dari @BotFather | Isi token |
| Instagram | Akun Business/Creator yang tersambung ke Facebook Page | Login with Instagram |
| Facebook | Admin Facebook Page | Login Facebook |
| Intercom | Access Token Intercom | Isi token, validasi |
| Slack | App ID, Bot Token, Verification Token | Isi form, validasi |
| SocialChat | API Key SocialChat | Isi API key, pilih channel |
| Webchat | Website atau aplikasi Anda | Pasang widget |

> **Catatan: Kuota channel**
>
> Jumlah channel dibatasi paket. Angka **Channel Terpakai** ada di atas daftar channel. Jika kuota penuh, tombol **Tambah Channel** nonaktif.

## Pengaturan umum setiap channel

Setelah channel dibuat, Anda bisa mengatur:

- **Label Channel**: nama internal agar mudah dikenali tim.
- **AI Agent**: agent yang membalas di channel ini. Klik **Pilih AI** atau **Ganti AI** di kartu channel. Untuk melepas, pakai **Putuskan AI Agent**.
- **Divisi**: hanya anggota divisi terpilih yang melihat chat channel ini. Lihat [Tim & role](https://docs.csku.ai/panduan/tim).

Status di kartu channel:

| Status | Arti |
| --- | --- |
| Terhubung | Channel aktif, pesan masuk dan keluar normal. |
| Terputus | Koneksi lepas atau token kedaluwarsa. Klik tombol hubungkan lagi. |
| Belum terhubung | Channel dibuat tapi belum selesai disambungkan. |

> **Penting: Hapus channel**
>
> Menghapus channel juga menghapus semua kontak, riwayat percakapan, dan konfigurasi channel tersebut. Tindakan ini tidak bisa dibatalkan.

## WhatsApp (Scan QR)

Memakai nomor WhatsApp biasa atau WhatsApp Business app, tersambung seperti WhatsApp Web.

1. Buka **Integrasi → WhatsApp**, klik **Tambah Channel**.
2. Isi nomor dengan format internasional, contoh `6281234567890`. Angka `0` di depan otomatis diubah ke `62`.
3. Pilih AI agent dan divisi, lalu klik **Simpan**.
4. Klik **Scan QR** di kartu channel.
5. Di HP, buka WhatsApp → **Perangkat tertaut** → **Tautkan perangkat**, lalu scan QR di layar.
6. Status berubah menjadi **Terhubung**.

QR berlaku sekitar 60 detik. Jika habis, minta QR baru. Jika status menjadi **Terputus**, scan ulang. Jangan keluarkan perangkat tertaut dari HP.

## WhatsApp API (Token manual)

Untuk nomor WhatsApp Business API yang sudah Anda kelola sendiri di Meta. Form punya tiga langkah:

1. **Akun Meta**: isi **Token** (Permanent Access Token dari Meta App) dan **WABA ID** (WhatsApp Business Account ID dari Meta Business Manager). Klik **Lanjut**.
2. **Nomor**: pilih nomor telepon dari daftar nomor di WABA tersebut. Klik **Lanjut**.
3. **Penanganan**: isi **Label Channel**, pilih **AI Agent** dan **Divisi**, lalu klik **Simpan**.

Kirim pesan dari nomor lain untuk tes. Untuk memakai nomor ini dari sistem Anda sendiri lewat API, lihat [WhatsApp API proxy](https://docs.csku.ai/waba/proxy).

## WhatsApp API (Login Meta)

Cara termudah untuk WhatsApp Business API. Webhook, token, WABA ID, dan Phone Number ID diatur otomatis.

1. Buka **Integrasi**, pilih WhatsApp API (Login Meta), klik **Tambah Channel**.
2. Klik **Setup dengan Facebook**. Izinkan popup di browser.
3. Di popup, login Facebook, pilih **Business Portfolio**, **WhatsApp Business Account**, dan nomor telepon.
4. Verifikasi nomor dengan kode OTP lewat SMS atau telepon.
5. Kembali ke dashboard, pilih nomor, klik **Hubungkan**.
6. Isi **Label Channel**, pilih AI agent dan divisi, klik **Simpan Perubahan**.

Nomor yang sudah dipakai di WhatsApp Business app bisa dihubungkan tanpa kehilangan riwayat (mode coexistence). Konfirmasi koneksi dilakukan di app WhatsApp Business.

> **Peringatan: Jendela 24 jam**
>
> Di WhatsApp API, Anda hanya bisa mengirim pesan bebas dalam 24 jam sejak pesan terakhir pelanggan. Di luar itu, wajib memakai template yang disetujui Meta. Lihat [Balas chat](https://docs.csku.ai/panduan/chat).

## Telegram

1. Di Telegram, buka `@BotFather` dan kirim `/newbot`.
2. Isi nama bot, lalu username yang diakhiri `bot`, contoh `cs_toko_bot`.
3. Salin token bot, formatnya seperti `123456789:ABCdefGHIjklMNO`.
4. Di CSKU, buka **Integrasi → Telegram**, klik **Tambah Channel**.
5. Tempel token di **Bot Token**, pilih AI agent dan divisi, klik **Simpan**.

Webhook diatur otomatis. Jika bot dipakai di grup, matikan privacy mode: kirim `/mybots` ke BotFather → pilih bot → **Bot Settings** → **Group Privacy** → **Turn Off**.

> **Peringatan: Jaga token**
>
> Token bot memberi akses penuh ke bot Anda. Jangan bagikan ke siapa pun.

## Instagram

Syarat: akun Instagram **Business** atau **Creator** yang tersambung ke Facebook Page, dan Anda admin Page tersebut.

1. Buka **Integrasi → Instagram**, klik **Tambah Channel**.
2. Klik **Login with Instagram**, login, dan berikan izin messaging.
3. Setelah kembali ke CSKU, isi label dan pilih AI agent.
4. Klik **Simpan**.

Balasan hanya bisa dikirim dalam 24 jam sejak pesan terakhir pelanggan. Jika token kedaluwarsa, status menjadi **Terputus**. Klik **Hubungkan** atau **Ganti Akun** untuk login ulang.

## Facebook

1. Buka **Integrasi → Facebook**, klik **Tambah Channel**.
2. Anda diarahkan ke Facebook. Login dan berikan izin.
3. Di halaman **Pilih Facebook Page**, pilih Page yang ingin dihubungkan.
4. Klik **Hubungkan**, lalu **Kembali ke Integrasi**.
5. Atur label, AI agent, dan divisi di kartu channel.

## Intercom

1. Ambil **Access Token** dari Intercom Developer Hub.
2. Di CSKU, buka **Integrasi → Intercom**, klik **Tambah Channel**.
3. Tempel token di **Access Token**, klik **Validasi Intercom**.
4. **App ID**, **Admin ID**, **Admin Name**, dan **Admin Email** terisi otomatis.
5. Pilih AI agent, klik **Simpan**.

Tes dengan mengirim pesan dari Intercom Messenger di website Anda.

## Slack

1. Buat app di `api.slack.com/apps` → **Create New App** → **From scratch**.
2. Di **OAuth & Permissions**, tambahkan scope `chat:write`, `channels:history`, `groups:history`, `im:history`, `mpim:history`, `users:read`.
3. Klik **Install to Workspace** dan salin **Bot User OAuth Token** (`xoxb-...`).
4. Di CSKU, buka **Integrasi → Slack**, klik **Tambah Channel**. Isi **App ID**, **Auth Token**, dan **Verification Token**, lalu klik **Validasi Slack**.
5. Salin URL webhook yang ditampilkan. Di Slack, buka **Event Subscriptions**, aktifkan, dan tempel sebagai **Request URL**.
6. Subscribe ke event `message.channels`, `message.groups`, `message.im`, `message.mpim`.
7. Undang bot ke channel Slack dengan `/invite @nama_bot`.

## SocialChat

1. Buka **Integrasi → SocialChat**, klik **Tambah Channel**.
2. Isi **API Key** dari dashboard SocialChat.
3. Pilih **Channel ID** dari daftar channel SocialChat Anda.
4. Pilih AI agent dan divisi, klik **Simpan**.

## Webchat

Webchat adalah widget chat untuk website atau aplikasi Anda sendiri. Buat channel di **Integrasi → Webchat**, lalu pasang kodenya. Langkah lengkap ada di [Pasang widget](https://docs.csku.ai/webchat/pasang). Untuk aplikasi Android, lihat [Integrasi Android](https://docs.csku.ai/webchat/android).

---

Sumber: https://docs.csku.ai/panduan/ai-agent

# AI Agent

> Buat AI agent, tulis perilakunya, isi pengetahuan, pilih model, atur jadwal, dan uji sebelum dipakai.


AI agent membalas pelanggan secara otomatis berdasarkan instruksi dan pengetahuan yang Anda berikan. Satu agent bisa dipakai di banyak channel. Jumlah agent dibatasi paket, terlihat di **AI Agent Terpakai**.

## Buat agent baru

1. Buka menu **AI Agent**, klik **Tambah Agent**.
2. Pilih template sesuai jenis bisnis, misalnya toko online, restoran, klinik, pendidikan, travel, properti, keuangan, topup game, atau salon. Template mengisi **Perilaku AI** secara otomatis.
3. Isi **Nama AI**, contoh `Customer Service Bot`.
4. Ubah **Perilaku AI** sesuai kebutuhan. Klik **Reset Template** untuk kembali ke isi template.
5. Klik **Buat Agent**.

Agent baru langsung terbuka di halaman pengaturan. Setelah agent tersimpan, fitur file, website, trigger, jadwal, dan tools menjadi tersedia.

## Informasi dasar

- **Nama AI Agent**: nama yang dipakai AI saat menyapa pelanggan.
- **Label Internal**: untuk identifikasi tim, tidak terlihat pelanggan.

Klik **Simpan** setiap selesai mengubah pengaturan.

## Perilaku AI

Tab **Perilaku AI** berisi **Instruksi Perilaku AI**: cara AI berbicara, bersikap, dan merespons. Tulis dengan jelas:

- Peran dan nada bicara, misalnya ramah dan profesional.
- Bahasa yang dipakai.
- Hal yang boleh dan tidak boleh dijawab.
- Contoh jawaban yang Anda inginkan.

Contoh:

```text
Anda adalah customer service Toko Maju yang ramah. Jawab singkat dalam bahasa Indonesia yang sopan. Jika pelanggan menanyakan stok, minta nama produk dan ukurannya. Jangan menjanjikan diskon yang tidak ada di informasi bisnis.
```

## Pengetahuan

Tab **Pengetahuan** punya empat sumber:

| Sumber | Isi |
| --- | --- |
| Text | **Informasi Bisnis**: produk/layanan, jam operasional, kebijakan, cara pembayaran, kontak. |
| FAQ | Pasangan **Pertanyaan** dan **Jawaban** yang sering ditanyakan. |
| File | Dokumen PDF, DOCX, XLSX, CSV, atau TXT, misalnya katalog atau SOP. |
| Website | URL halaman yang konten-nya diambil, misalnya halaman produk. |

Untuk **File**, klik **Upload** dan pilih dokumen. Untuk **Website**, masukkan URL lalu klik **Scrape**. Klik **Lihat konten** untuk memeriksa hasil yang diambil. Jumlah URL website dibatasi paket.

> **Tips: Pengetahuan yang baik**
>
> Semakin lengkap dan terbaru informasinya, semakin akurat jawaban AI. Perbarui pengetahuan saat harga, stok, atau kebijakan berubah.

## CS Manusia

Tab **CS Manusia** mengatur kapan AI menyerahkan percakapan ke tim:

- **Instruksi Pengalihan ke CS Manusia**: situasi yang membuat AI berhenti dan mengalihkan, misalnya komplain atau permintaan refund.
- **Pesan Notifikasi ke User**: pesan yang dikirim ke pelanggan saat dialihkan.
- **Email Notifikasi (Opsional)**: email tim yang diberi tahu. Ketik email lalu tekan Enter.
- **Grup Telegram (Opsional)**: Chat ID grup Telegram. Undang `@cskuai_bot` ke grup, ketik `/start`, lalu salin Chat ID yang dikirim bot.
- **Webhook URL (Opsional)**: URL yang dipanggil saat AI mengalihkan.

Saat dialihkan, percakapan berstatus **Butuh CS** dan AI dijeda sampai tim mengembalikannya.

## Model AI

Di kartu **Model AI**:

- **Pilih Model AI**: setiap model menampilkan harga dalam kredit per jawaban. Model lebih mahal biasanya lebih pintar.
- **Tingkat kreativitas**: dari **Konsisten** ke **Kreatif**. Untuk CS, pilih yang dekat ke Konsisten.
- **Delay min/maks (dtk)**: jeda acak sebelum AI membalas agar terasa natural.
- **Zona Waktu**: WIB, WITA, atau WIT. Dipakai untuk jadwal.
- **Tandai sebagai dibaca**: pesan otomatis ditandai sudah dibaca.
- **Tandai sebagai ditangani**: percakapan yang dibalas AI berstatus **Ditangani**.

Kredit dipotong setiap AI membalas. Lihat [Berlangganan & kredit](https://docs.csku.ai/panduan/berlangganan).

## Trigger

Trigger memungkinkan AI memanggil API Anda lewat function calling, misalnya cek status pesanan atau cek tagihan. Trigger hanya berjalan jika model yang dipilih mendukung function calling. Jika tidak, muncul peringatan dan tombol **Ganti Model AI**.

1. Buka tab **Trigger**, lalu tambah trigger.
2. Isi **Nama Trigger** dan **Deskripsi**. Jelaskan kapan AI harus memakai trigger ini, data apa yang dihasilkan, dan contoh pertanyaan pelanggan yang memicunya. Klik **Simpan & Lanjutkan**.
3. Di bagian **API**, tambahkan data input yang perlu ditanyakan AI ke pelanggan, misalnya `id_tagihan`. Pilih **Method** (GET, POST, PUT, PATCH, DELETE) dan isi **URL**. Anda juga bisa memakai **Import cURL**.
4. Tes dengan **Live response** dari API Anda, atau isi **Sample response** jika API belum siap. Klik **Test Response**.
5. Di bagian **Data**, isi **Keterangan Tambahan** agar AI memahami respons, contoh `status 1=Sukses, status 2=Gagal`.
6. Klik **Simpan**.

## Analisis Image

Aktifkan **Aktifkan Analisis Image** agar AI bisa membaca gambar dari pelanggan, misalnya foto produk, bukti transfer, atau nota.

- **Instruksi Analisis Image**: jenis gambar yang relevan dan informasi yang perlu dicari.
- **Instruksi AI untuk Image**: cara AI memakai hasil analisis saat menjawab.

## Jadwal AI

Tab **Jadwal AI** mengatur kapan AI aktif. Di luar jadwal, AI tidak membalas otomatis.

- Pilih **Gunakan Template Jadwal**, misalnya **Senin - Jumat (09:00 - 17:00)** atau **Setiap Hari (24 Jam)**.
- Atau atur jam per hari, lalu klik **Simpan** di hari tersebut.
- Tanpa jadwal, AI aktif 24/7.

## Tools

Tab **Tools** di bagian atas form menghubungkan agent ke server yang sudah Anda daftarkan di menu **Tools → MCP Server** atau **NPX Server**. Pilih server, lalu klik **Assign**.

## Uji Chat

Klik **Uji Chat** di kanan atas untuk mencoba agent. Percakapan di sini tidak dikirim ke pelanggan. Ubah perilaku atau pengetahuan, simpan, lalu uji lagi sampai jawabannya sesuai.

## Hubungkan ke channel

Agent belum membalas siapa pun sampai dipasang di channel. Buka **Integrasi**, pilih channel, klik **Pilih AI**, pilih agent, lalu **Simpan**. Lihat [Hubungkan channel](https://docs.csku.ai/panduan/channel).

---

Sumber: https://docs.csku.ai/panduan/chat

# Balas chat

> Kelola inbox, ambil alih dari AI, balas pelanggan, tulis catatan, kirim lampiran, dan minta penilaian CSAT.


Semua percakapan dari semua channel masuk ke menu **Chat**. Daftar percakapan ada di kiri, isi chat di kanan. Di HP, Anda juga bisa memakai [aplikasi mobile](https://docs.csku.ai/panduan/aplikasi-mobile).

## Inbox, tab, dan filter

Tab di atas daftar percakapan memfilter berdasarkan status: **Semua**, **Belum Dibaca**, **Butuh CS**, **Belum Ditangani**, **Ditangani**, **Selesai**, **Diblokir**, dan **Dilewati**. Arti tiap status ada di [Konsep dasar](https://docs.csku.ai/mulai/konsep).

- **Cari**: ketik nama, nomor, atau isi pesan di kolom **Cari percakapan…**.
- **Filter**: klik ikon filter untuk memilih **Status Pesan**, **Tipe Channel**, **AI Agent**, dan **Label**. Klik **Reset** untuk menghapus filter.
- **Suara**: klik ikon lonceng untuk menyalakan atau mematikan suara notifikasi.
- **Unduh riwayat chat**: unduh semua chat dalam file Excel (`.xlsx`) berdasarkan rentang tanggal.

Anda hanya melihat percakapan dari channel divisi Anda. Owner melihat semua.

## Ambil alih dari AI

Header chat menampilkan mode saat ini: **Mode AI** atau **Ditangani manusia**. Kotak balas hanya muncul saat percakapan ditangani manusia.

1. Buka percakapan.
2. Klik **Ambil alih** di header, atau **Ambil alih & balas** di bawah chat.
3. AI dijeda di percakapan ini sampai Anda mengembalikannya.

Untuk menyerahkan lagi ke AI, klik **Kembalikan ke AI**.

## Balas pelanggan

1. Pastikan mode tulis **Balas** aktif.
2. Ketik pesan di **Tulis balasan…**.
3. Tekan Enter untuk kirim. Shift+Enter untuk baris baru.

Untuk membalas pesan tertentu, arahkan kursor ke pesan, buka menu pesan, lalu pilih **Balas**. Kutipan pesan muncul di atas kotak tulis. Klik **×** untuk batal.

Di Telegram, pesan teks yang Anda kirim bisa diubah lewat menu pesan → **Edit**.

## Catatan internal

Catatan hanya terlihat oleh tim. Catatan tidak dikirim ke pelanggan.

1. Pilih mode tulis **Catatan**. Kotak tulis berubah warna kuning.
2. Tulis catatan, lalu kirim.

Catatan tampil di riwayat chat dengan label **Catatan internal**.

## Perbaikan AI

**Perbaikan AI** adalah catatan khusus untuk menulis koreksi atas jawaban AI. Catatan ini juga tidak dikirim ke pelanggan.

1. Klik **Perbaiki jawaban AI** di bawah kotak tulis. Kotak tulis berubah warna ungu.
2. Tulis instruksi koreksi, contoh `Ongkir ke Bandung Rp15.000, bukan Rp20.000`.
3. Kirim.

Catatan tampil dengan label **Perbaikan AI** agar mudah dibedakan dari catatan biasa.

> **Tips: Perbaikan permanen**
>
> Jika AI berulang kali salah di topik yang sama, perbarui juga **Pengetahuan** atau **Perilaku AI** di [AI Agent](https://docs.csku.ai/panduan/ai-agent).

## Lampiran

Klik ikon lampiran untuk mengirim **Image**, **Video**, **Audio**, atau **Dokumen**. Anda juga bisa menempel gambar langsung ke kotak tulis.

- Gambar: JPG dan PNG.
- Dokumen: misalnya PDF.

> **Peringatan: WebP belum didukung**
>
> Gambar WebP tidak bisa dikirim ke chat. Ubah ke JPG atau PNG lebih dulu.

## Balasan cepat

Balasan cepat adalah template pesan yang sering dipakai.

1. Ketik `/` di awal kotak tulis atau setelah spasi.
2. Lanjutkan mengetik untuk mencari template.
3. Klik template untuk memakainya. Tekan ESC untuk menutup.

Klik **Kelola** di daftar template untuk menambah, mengubah, atau menghapus template. Template bisa berisi media.

## Label

Label membantu mengelompokkan percakapan, misalnya `VIP` atau `Komplain`.

1. Klik ikon titik tiga di header chat → **Ubah Label**.
2. Pilih label yang ada, atau klik **Buat Label Baru**.

Label bisa dipakai di filter inbox.

## Menu lainnya

Ikon titik tiga di header chat juga berisi:

- **Lihat Profil**: info kontak pelanggan.
- **Copy Conversation ID**: untuk dipakai di [Public API](https://docs.csku.ai/api/autentikasi).
- **Pin Percakapan**: menyematkan percakapan di atas daftar.
- **Skip Percakapan**: status menjadi **Dilewati**. AI tidak membalas.
- **Blokir Pengguna**: status menjadi **Diblokir**. AI tidak membalas.

## Selesai dan CSAT

Saat masalah pelanggan beres, tutup percakapan dengan salah satu tombol di header:

- **Selesai**: percakapan ditandai selesai tanpa penilaian.
- **CSAT** (di HP: **Kirim CSAT & selesai**): percakapan ditandai selesai dan pelanggan menerima permintaan penilaian.

Setelah selesai, AI aktif kembali untuk pesan berikutnya dari pelanggan tersebut.

Pesan CSAT yang diterima pelanggan:

```text
Kendala Anda telah kami selesaikan. Mohon beri penilaian untuk layanan kami dari 1 sampai 5.

1 = sangat tidak puas
2 = tidak puas
3 = cukup
4 = puas
5 = sangat puas

Balas dengan angka 1-5.
```

Jika pelanggan membalas angka 1–5, nilainya tercatat dan pelanggan menerima `Terima kasih atas penilaian Anda.` Hasilnya bisa dilihat di [Analitik](https://docs.csku.ai/panduan/analitik).

## Template WABA di luar 24 jam

Di channel WhatsApp API, pesan bebas hanya bisa dikirim dalam 24 jam sejak pesan terakhir pelanggan. Di luar jendela itu, kirim template yang sudah disetujui Meta:

1. Klik **Template WABA** di bawah kotak tulis.
2. Cari dan pilih template.
3. Isi variabel header dan body jika ada.
4. Klik **Kirim**.

Template dibuat dan diajukan di Meta WhatsApp Manager. Template yang disetujui muncul otomatis di daftar.

## Notifikasi

Saat Anda membuka dashboard, pesan baru muncul sebagai pop-up kecil di pojok layar, dengan suara jika suara aktif. Klik pop-up untuk membuka chatnya.

Untuk notifikasi browser saat tab CSKU tidak sedang dilihat:

1. Buka **Pengaturan → Notifikasi**.
2. Nyalakan **Notifikasi pesan masuk**.
3. Izinkan notifikasi saat browser bertanya.

Pengaturan ini berlaku per browser. Jika izin pernah diblokir, buka pengaturan situs di browser (ikon gembok di address bar), izinkan **Notifikasi**, lalu nyalakan lagi.

---

Sumber: https://docs.csku.ai/panduan/tim

# Tim & role

> Tambah anggota tim, kelompokkan dalam divisi, dan atur izin menu lewat role.


Tim diatur dari **Settings → Manajemen Tim**. Halaman ini punya tiga tab: **Divisi**, **Tim**, dan **Role**. Hanya owner atau role yang punya izin Team Management yang bisa membukanya.

## Owner dan anggota

| | Owner | Anggota tim |
| --- | --- | --- |
| Akun | Dibuat saat daftar | Dibuat owner dari tab **Tim** |
| Akses menu | Semua menu | Sesuai role |
| Percakapan | Semua channel | Hanya channel di divisinya |
| Dashboard | Ringkasan bisnis | **Performa Saya** |

Jumlah anggota tim dibatasi paket. Angka **Anggota Terpakai** tampil di tab **Tim**. Jika kuota penuh, tombol **Tambah Anggota** nonaktif dan Anda perlu **Upgrade Paket**.

## Urutan setup

Buat dalam urutan ini, karena anggota butuh role dan divisi:

1. **Role**: tentukan izin menu.
2. **Divisi**: kelompokkan channel.
3. **Tim**: tambahkan anggota, pilih role dan divisinya.

## Role

Role menentukan menu dan aksi apa yang boleh dipakai anggota.

1. Buka tab **Role**, klik **Tambah Role**.
2. Isi **Nama Role**, contoh `Customer Service` atau `Supervisor`.
3. Di **Pilih Permissions**, centang menu dan aksi yang diizinkan.
4. Klik **Simpan Role**.

Izin dikelompokkan per menu. Contoh:

| Menu | Aksi yang bisa dipilih |
| --- | --- |
| Chat | Lihat Chat, Kirim Pesan |
| Kontak | Lihat, Tambah, Edit, Hapus Kontak |
| AI Agent | Lihat, Tambah, Edit, Hapus AI Agent |
| Integrasi | Lihat Integrasi, Tambah Integrasi |
| Analitik | CSAT, FRT |
| Settings | Profile, Password, Info Merchant, Secret Key, Team Management, Webhook |

Menu yang tidak dicentang tidak muncul di sidebar anggota.

> **Tips: Role untuk CS**
>
> Untuk agen CS biasa, cukup beri izin **Chat** dan **Kontak**. Tambahkan **Analitik** hanya untuk supervisor yang perlu melihat performa seluruh tim.

## Divisi

Divisi menentukan channel mana yang terlihat oleh anggotanya. Anggota hanya melihat percakapan dari channel yang terhubung ke divisinya.

1. Buka tab **Divisi**, klik **Tambah Divisi**.
2. Isi nama divisi, contoh `Sales` atau `Support`. Klik **Simpan**.
3. Klik **Kelola Channel** di baris divisi. Pilih channel lalu **Tambah Channel**.
4. Klik **Kelola Tim** untuk melihat atau menambah anggota divisi.

Anda juga bisa memilih divisi langsung saat membuat atau mengedit channel di **Integrasi**. Satu channel bisa masuk lebih dari satu divisi.

## Tambah anggota

1. Buka tab **Tim**, klik **Tambah Anggota**.
2. Isi **Email** dan **Nama**.
3. Pilih **Role**.
4. Pilih satu atau lebih **Divisi**.
5. Klik **Tambah**.

Setelah berhasil, muncul email dan password login anggota baru.

> **Peringatan: Simpan data login**
>
> Password hanya ditampilkan sekali. Salin email dan password, lalu kirim ke anggota lewat jalur yang aman. Jendela tidak bisa ditutup sebelum keduanya disalin.

Anggota login di `https://app.csku.ai` atau di [aplikasi mobile](https://docs.csku.ai/panduan/aplikasi-mobile) dengan data tersebut.

## Ubah dan hapus anggota

- Klik ikon edit di baris anggota untuk mengubah nama, **Nomor HP**, role, atau divisi.
- Klik ikon hapus untuk menghapus anggota. Tindakan ini tidak bisa dibatalkan.

## Siapa melihat apa

- Anggota tanpa divisi tidak melihat percakapan channel mana pun.
- Anggota yang role-nya tidak punya izin **Analitik** hanya melihat angka miliknya sendiri di **Performa Saya**. Lihat [Analitik](https://docs.csku.ai/panduan/analitik).
- Owner selalu melihat semua channel dan semua menu.

---

Sumber: https://docs.csku.ai/panduan/analitik

# Analitik

> Pantau kepuasan pelanggan (CSAT) dan kecepatan respons pertama tim (FRT).


Menu **Analitik** punya dua laporan: **CSAT** untuk kepuasan pelanggan dan **FRT** untuk kecepatan respons tim. Keduanya bisa difilter berdasarkan rentang tanggal.

## CSAT

CSAT (Customer Satisfaction) adalah nilai 1 sampai 5 dari pelanggan setelah percakapan selesai.

### Cara nilai dikumpulkan

1. Agen menutup percakapan dengan tombol **CSAT** di header chat. Lihat [Balas chat](https://docs.csku.ai/panduan/chat).
2. Pelanggan menerima pesan yang meminta nilai 1–5.
3. Pelanggan membalas dengan satu angka, contoh `5`.
4. Nilai tercatat dan pelanggan menerima `Terima kasih atas penilaian Anda.`

Hanya balasan teks berupa angka 1–5 yang dihitung. Balasan lain tidak dianggap sebagai nilai. Percakapan yang ditutup dengan **Selesai** biasa tidak mengirim permintaan penilaian.

### Isi laporan CSAT

| Angka | Arti |
| --- | --- |
| Total Request | Jumlah permintaan penilaian yang dikirim. |
| Total Respon | Jumlah pelanggan yang memberi nilai. |
| Rata-rata Skor | Rata-rata nilai, skala 1 sampai 5. |
| Response Rate | Persentase request yang dijawab pelanggan. |

Di bawahnya ada:

- **Tren Harian**: request dan respon per hari.
- **Distribusi Skor**: jumlah respon per nilai.
- **Performa Tim**: per agen, diurutkan dari rata-rata skor tertinggi.
- **Data Terbaru**: request dan respon terakhir.

Klik **Lihat request** atau **Lihat semua** untuk membuka daftar lengkap. Daftar ini bisa difilter berdasarkan tanggal, status (**Menunggu**, **Terisi**, **Dilewati**, **Expired**), dan skor. Klik percakapan untuk membuka chatnya.

Nilai CSAT dihitung untuk agen yang menutup percakapan.

## FRT

FRT (First Response Time) adalah waktu dari pelanggan mulai menunggu sampai agen manusia mengirim balasan pertama.

### Kapan FRT mulai dihitung

FRT dimulai dari salah satu sumber berikut:

- **Pesan masuk**: pelanggan mengirim pesan di percakapan yang sedang ditangani manusia.
- **Human takeover**: agen menekan **Ambil alih**, atau AI mengalihkan percakapan ke CS.

Status FRT saat itu adalah **Menunggu**.

### Kapan FRT selesai

FRT selesai saat agen manusia mengirim balasan pertama ke pelanggan. Statusnya berubah menjadi **Direspon**.

Yang tidak dihitung sebagai respons:

- Balasan AI.
- Catatan internal dan Perbaikan AI.

### Isi laporan FRT

| Angka | Arti |
| --- | --- |
| Rata-rata FRT | Rata-rata waktu respons pertama agen. |
| Sudah Direspon | Jumlah FRT yang selesai. |
| Menunggu | Percakapan yang belum dibalas agen. |
| Response rate | Persentase FRT yang selesai. |

Di bawahnya ada tren harian, **Ringkasan Durasi** (**Tercepat** dan **Terlama**), dan **Performa Tim CC** yang diurutkan dari FRT paling cepat. Klik **Export** untuk mengunduh data.

Halaman detail menampilkan **Daftar Request FRT** per percakapan, dengan filter sumber (**Pesan masuk** atau **Human takeover**), waktu **Mulai**, **Respon Pertama**, dan **Durasi**.

> **Tips: Menurunkan FRT**
>
> Pantau tab **Butuh CS** di inbox dan aktifkan notifikasi browser atau [aplikasi mobile](https://docs.csku.ai/panduan/aplikasi-mobile) agar agen cepat tahu ada pesan baru.

## Performa Saya

Anggota tim (bukan owner) melihat kartu **Performa Saya** di **Dashboard**. Isinya hanya angka dari chat yang mereka balas sendiri:

| Kartu | Arti |
| --- | --- |
| Rata-rata Respons | Rata-rata waktu balasan pertama Anda. |
| Chat Dibalas | Jumlah chat yang Anda balas, plus yang masih menunggu. |
| Skor CSAT | Rata-rata nilai dari percakapan yang Anda tutup. |
| Response Rate | Chat terbalas dibanding chat masuk. |

Ada juga grafik **Chat dibalas per hari** dan peringkat Anda di tim. Rentang default adalah 7 hari terakhir.

Anggota hanya bisa membuka laporan **Analitik** lengkap jika role-nya punya izin menu Analitik. Lihat [Tim & role](https://docs.csku.ai/panduan/tim).

---

Sumber: https://docs.csku.ai/panduan/berlangganan

# Berlangganan & kredit

> Pilih paket, pahami kredit AI gratis dan berbayar, top up, perpanjang, ganti paket, dan bayar invoice.


Menu **Berlangganan** berisi paket aktif, pemakaian kuota, saldo AI kredit, dan riwayat pembayaran. Ada tiga tab: **Paket Berlangganan**, **Invoice**, dan **Mutasi AI Kredit**.

## Isi paket

Setiap paket menentukan batas berikut. Pemakaian saat ini tampil di bagian atas halaman.

| Batas | Arti |
| --- | --- |
| Kontak | Jumlah kontak pelanggan. |
| Channel | Jumlah channel yang bisa dihubungkan. |
| Human Agent | Jumlah anggota tim. |
| AI Agent | Jumlah AI agent. |
| Website URL Knowledge | Jumlah URL website untuk pengetahuan AI. |
| Free AI Kredit Bulanan | Kredit gratis yang diisi ulang setiap bulan. |

Paket juga menentukan fitur tambahan, misalnya **Notif Human Support**, **Integrasi API**, dan **Integrasi Webhook**. Bandingkan paket di tab **Paket Berlangganan**.

> **Catatan: API dan webhook**
>
> [Public API](https://docs.csku.ai/api/autentikasi) hanya bisa dipakai jika paket Anda punya **Integrasi API**. [Webhook](https://docs.csku.ai/webhook/setup) hanya bisa dipakai jika paket punya **Integrasi Webhook**. Cek tanda centang di detail paket sebelum mulai integrasi.

## Berlangganan paket

1. Buka tab **Paket Berlangganan**.
2. Pilih durasi: **Bulanan**, **3 Bulan**, **6 Bulan**, atau **Setahun**. Durasi lebih panjang biasanya lebih hemat.
3. Klik **Pilih Paket** di paket yang Anda inginkan.
4. Periksa ringkasan, lalu klik **Lanjut Pembayaran**.
5. Bayar invoice yang terbentuk. Caranya ada di bagian Invoice di bawah.

Paket gratis langsung aktif tanpa pembayaran. Untuk kebutuhan khusus, klik **Hubungi Kami**.

## Kredit AI

Setiap balasan AI memotong kredit sesuai harga model, misalnya `2 kredit / jawaban`. Harga tiap model tampil di pilihan model AI agent. Lihat [AI Agent](https://docs.csku.ai/panduan/ai-agent).

Ada dua jenis kredit:

| Jenis | Sumber | Catatan |
| --- | --- | --- |
| AI Kredit Gratis | Bonus paket setiap bulan | Direset ke jumlah paket setiap bulan. |
| AI Kredit Berbayar | Top up | Dipakai saat kredit gratis tidak cukup. |

Sistem selalu memakai kredit gratis lebih dulu. Jika kredit gratis kurang dari harga satu jawaban, sistem memakai kredit berbayar. Jika keduanya tidak cukup, AI berhenti membalas sampai Anda top up.

Saldo **AI Kredit Gratis**, **AI Kredit Berbayar**, dan **Total AI Kredit** tampil di halaman Berlangganan. Sisa kredit juga tampil di **Dashboard**.

> **Peringatan: Kredit gratis tidak menumpuk**
>
> Sisa kredit gratis tidak dibawa ke bulan berikutnya. Setiap bulan saldonya diisi ulang sesuai paket.

## Top up kredit

1. Klik **Top Up** di kartu AI Kredit.
2. Atur **Jumlah Paket**. Satu paket berisi 1.000 kredit. Minimal pembelian 5 paket.
3. Periksa **Total Pembayaran**, lalu klik **Lanjut Pembayaran**.
4. Bayar invoice yang terbentuk.

Kredit masuk setelah pembayaran terkonfirmasi.

## Mutasi AI Kredit

Tab **Mutasi AI Kredit** mencatat setiap perubahan saldo:

- **Penggunaan AI**: kredit terpakai untuk balasan AI, dengan tanda **Gratis** atau **Berbayar**.
- **Top Up**: kredit masuk dari pembelian.
- **Bonus Paket**: kredit gratis bulanan.

Setiap baris menampilkan saldo sebelum dan sesudah.

## Perpanjang paket

Banner peringatan muncul saat paket hampir berakhir atau sudah berakhir.

1. Klik **Perpanjang Paket** atau **Perpanjang Sekarang**.
2. Pilih durasi perpanjangan. Durasi yang tidak tersedia ditandai **Belum Tersedia**.
3. Klik **Lanjut Pembayaran** dan bayar invoice.

## Ganti paket

1. Klik **Ganti Paket**.
2. Pilih paket baru dan durasinya.
3. Klik **Lanjut Pembayaran**, atau **Aktifkan Paket** jika paket gratis.

> **Penting: Sisa waktu paket lama hangus**
>
> Saat ganti paket, sisa waktu berlangganan paket lama hangus dan tidak dapat dikembalikan. Paket baru aktif setelah pembayaran.

## Invoice

Tab **Invoice** berisi semua tagihan dengan **Tanggal**, **Nominal**, dan **Status**.

1. Klik **Bayar** pada invoice yang belum dibayar, atau **Detail** untuk melihat rincian.
2. Di halaman invoice, klik **Pilih metode** dan pilih metode pembayaran.
3. Ikuti instruksi yang muncul, misalnya nomor Virtual Account atau QR Code Pembayaran. Klik **Salin** untuk menyalin nomor.
4. Setelah membayar, klik **Refresh Status**.

Halaman invoice menampilkan subtotal, biaya admin, PPN, dan total. Klik **Unduh PDF** untuk menyimpan invoice. Klik **Ganti Metode** untuk mengganti metode pembayaran.

---

Sumber: https://docs.csku.ai/panduan/aplikasi-mobile

# Aplikasi mobile

> Balas chat pelanggan dari HP dengan aplikasi CSKU untuk agen, lengkap dengan notifikasi pesan baru.


Aplikasi CSKU untuk agen dipakai untuk membalas chat dari HP. Aplikasi tersedia untuk Android dan iOS. Pengaturan seperti AI agent, channel, dan tim tetap dilakukan di dashboard web.

## Pasang aplikasi

Aplikasi belum tersedia di Play Store atau App Store. Untuk saat ini, minta file APK ke admin, lalu pasang di HP Android Anda. Izinkan pemasangan dari sumber tersebut jika HP memintanya.

## Masuk

1. Buka aplikasi.
2. Isi **Email** dan **Password** akun Anda. Ini akun yang sama dengan dashboard web.
3. Centang **Ingat saya** jika ingin tetap masuk.
4. Ketuk **Masuk**.

Aplikasi hanya mendukung login email dan password. Login dengan Google belum tersedia.

Belum punya akun? Minta owner menambahkan Anda dari **Settings → Manajemen Tim**. Lihat [Tim & role](https://docs.csku.ai/panduan/tim). Lupa password? Ketuk **Lupa password?**. Link reset dikirim ke email pemilik akun workspace, jadi agen tim sebaiknya minta admin untuk reset.

> **Peringatan: Satu sesi aktif per akun**
>
> Satu akun hanya bisa aktif di satu tempat. Masuk di HP akan mengeluarkan akun yang sama dari dashboard web, dan sebaliknya. Jika perlu membuka keduanya, pakai akun berbeda.

## Menu utama

Aplikasi punya empat tab di bawah:

| Tab | Isi |
| --- | --- |
| Chat | Daftar percakapan dan isi chat. |
| Performa | Angka FRT dan CSAT Anda sendiri. |
| Notifikasi | Pesan pelanggan yang belum dibaca. |
| Akun | Profil, izin notifikasi, dan keluar. |

## Daftar percakapan

Tab di atas daftar memfilter status: **Semua**, **Belum Dibaca**, **Butuh CS**, **Belum Ditangani**, **Ditangani**, dan **Selesai**. Ketik di kolom **Cari nama, nomor, atau pesan...** untuk mencari. Anda hanya melihat percakapan dari channel divisi Anda.

## Membalas chat

Saat AI sedang menangani, muncul pesan **AI sedang membalas**. Ketuk **Ambil alih percakapan** untuk membalas sendiri.

Di kotak tulis ada tiga mode:

- **Balas**: pesan dikirim ke pelanggan.
- **Catatan**: catatan internal, hanya tim yang melihat.
- **Perbaiki jawaban AI**: catatan koreksi untuk jawaban AI, berlabel **Perbaikan AI**.

Fitur lain:

- **Balas pesan tertentu**: tekan lama pesan pelanggan atau pesan agen. Kutipan muncul di atas kotak tulis.
- **Lampiran**: ketuk **Lampirkan**, lalu pilih **Kamera**, **Galeri foto**, atau **Dokumen**. Gambar WebP tidak bisa dikirim, pakai JPG atau PNG.
- **Balasan cepat**: ketik `/` di awal atau setelah spasi, lalu pilih template. Template dikelola dari dashboard web.
- **Template WABA**: di channel WhatsApp API, ketuk **Template WABA** untuk mengirim template yang disetujui Meta. Di luar jendela 24 jam, hanya template yang bisa dikirim.

Penjelasan lengkap fitur chat ada di [Balas chat](https://docs.csku.ai/panduan/chat).

## Kembalikan ke AI dan selesai

Di header chat:

- **Ke AI**: serahkan percakapan kembali ke AI.
- **Selesai**: tutup percakapan. Pilih **Selesai & minta penilaian** untuk mengirim permintaan CSAT, atau **Selesai tanpa penilaian**. AI aktif kembali untuk pesan berikutnya.

Menu **Lainnya** berisi **Info kontak**, **Salin nomor**, **Lewati percakapan**, dan **Blokir**.

## Info kontak

Halaman **Info Kontak** menampilkan telepon, label, channel, email, dan sejak kapan pelanggan tercatat. Label hanya bisa dibuat dari dashboard web.

## Performa

Tab **Performa** menampilkan data yang sama dengan **Performa Saya** di dashboard web: **Rata-rata FRT**, **CSAT**, **Response rate**, dan jumlah yang **Menunggu**. Ada juga grafik percakapan dibalas per hari, distribusi skor CSAT, dan **Peringkat tim** yang diurutkan dari FRT tercepat. Lihat [Analitik](https://docs.csku.ai/panduan/analitik).

## Notifikasi

Saat pertama kali masuk, izinkan notifikasi. Status izin bisa dicek di tab **Akun → Izin notifikasi**. Jika izin ditolak, aktifkan dari pengaturan HP.

Notifikasi pesan baru muncul saat aplikasi terbuka atau berjalan di latar belakang. Ketuk notifikasi untuk langsung membuka chatnya.

> **Peringatan: Jangan tutup paksa aplikasi**
>
> Notifikasi tidak masuk jika aplikasi ditutup paksa (force close) atau di-swipe dari daftar aplikasi terbaru. Biarkan aplikasi berjalan di latar belakang. Di beberapa HP Android, matikan juga penghemat baterai untuk aplikasi ini.

## Akun dan keluar

Tab **Akun** menampilkan nama, email, dan peran Anda (**Owner** atau **Agent**). Ketuk **Buka dashboard web** untuk mengelola AI agent, channel, dan tim.

Untuk keluar, ketuk **Keluar** lalu konfirmasi. Setelah keluar, HP ini berhenti menerima notifikasi pesan.

## Batasan

- Pengaturan AI agent, channel, tim, label, dan balasan cepat hanya bisa dilakukan di dashboard web.
- Tab status **Diblokir** dan **Dilewati** belum ada di aplikasi.
- Satu akun hanya bisa aktif di satu perangkat atau browser pada satu waktu.
- Notifikasi tidak berjalan saat aplikasi ditutup paksa.

---

Sumber: https://docs.csku.ai/api/autentikasi

# Autentikasi

> Setiap request Public API memakai Business ID dan Secret Key bisnis Anda.


Public API CSKU memakai dua nilai milik bisnis Anda: **Business ID** dan **Secret Key**. Keduanya dikirim di setiap request. Tidak ada token yang kedaluwarsa, jadi satu pasang kredensial berlaku sampai Anda membuat Secret Key baru.

## Syarat

- Paket Anda punya fitur **API**. Tanpa fitur ini menu Secret Key tidak muncul, dan endpoint pesan menolak request. Lihat [Berlangganan & kredit](https://docs.csku.ai/panduan/berlangganan).
- Anda punya akses ke email akun yang login, karena membuat Secret Key butuh kode OTP.

## Ambil kredensial

1. Buka **Pengaturan → Informasi Bisnis**. Salin **Business ID**.
2. Buka **Pengaturan → Secret Key**, lalu klik **Buat Secret Key Baru**.
3. Masukkan kode OTP yang dikirim ke email. Kode berlaku 5 menit. Setelah 3 kali salah, Anda harus menunggu 5 menit.
4. Secret Key ditampilkan **sekali saja**. Salin dan simpan di tempat aman sebelum menutup jendela.

> **Peringatan: Secret Key lama langsung tidak berlaku**
>
> Membuat Secret Key baru membatalkan yang lama saat itu juga. Semua integrasi yang memakai secret lama, termasuk pengecekan header di [webhook](https://docs.csku.ai/webhook/keamanan-retry), harus diperbarui.

## Cara mengirim kredensial

Pilih salah satu cara. Keduanya setara.

### Cara 1: header Business dan Secret

```http
Business: BIZ_ID_ANDA
Secret: SECRET_ANDA
```

### Cara 2: Authorization Bearer

Gabungkan `BIZ_ID:SECRET` (dipisah titik dua), encode dengan Base64, lalu kirim sebagai Bearer token.

```bash
TOKEN=$(printf '%s' "BIZ_ID_ANDA:SECRET_ANDA" | base64)
curl https://api.csku.ai/v1/conversation/need-human/total \
  -H "Authorization: Bearer $TOKEN"
```

Header `Authorization` hanya dibaca jika header `Secret` kosong.

> **Tips**
>
> Nilai yang ditampilkan dashboard saat membuat Secret Key sudah dalam format Base64 `BIZ_ID:SECRET`. Nilai itu bisa langsung dipakai sebagai Bearer token.

## Contoh lengkap

```js
const res = await fetch('https://api.csku.ai/v1/message', {
  method: 'POST',
  headers: {
    Business: process.env.CSKU_BUSINESS_ID,
    Secret: process.env.CSKU_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ conversation_id: 'CO_01J…', text: 'Halo kak' }),
})
const data = await res.json()
```

## Keamanan

- Simpan Business ID dan Secret Key di server (variabel lingkungan atau secret manager). Jangan taruh di aplikasi mobile, JavaScript browser, atau repository.
- Secret Key memberi akses penuh ke API bisnis Anda. Jika bocor, buat Secret Key baru segera.
- API tidak menerapkan batas request (rate limit), tapi tetap kirim request secukupnya dan antrekan pengiriman massal di sisi Anda.

## Error autentikasi

| Pesan `error_msg` | Penyebab |
|---|---|
| `Data tidak valid. Mohon periksa kembali parameter dan header` | Format Bearer salah (bukan Base64 `BIZ_ID:SECRET`) |
| `business not found` / `biz not found` | Business ID tidak dikenal |
| `secret not valid ` | Secret salah atau sudah diganti |
| `Anda belum memiliki paket aktif.` | Paket tidak aktif |
| `Paket user tidak memiliki fitur API.` | Paket aktif, tapi tanpa fitur API |

Lihat [Format respons & error](https://docs.csku.ai/api/respons) untuk bentuk lengkap respons error.

---

Sumber: https://docs.csku.ai/api/respons

# Format respons & error

> Bentuk respons sukses dan error Public API, dan cara memeriksanya dengan benar.


## Cek `status`, bukan kode HTTP

Public API CSKU membalas **HTTP 200** untuk sukses maupun sebagian besar error. Penentunya adalah isi body.

| Kondisi | Body |
|---|---|
| Sukses dengan data | `{"status": 1, "rc": 200, "message": "…", "data": {…}, "ts": 1760000000}` |
| Sukses aksi | Objek hasil, misalnya `{"success": true, "conversation_id": "CO_…"}` |
| Error | `{"status": 0, "rc": 500, "error_msg": "pesan error"}` |

Rekomendasi: anggap request **berhasil** jika body punya `"status": 1` atau `"success": true`. Selain itu, baca `error_msg`.

```js
const body = await res.json()
const ok = body.status === 1 || body.success === true
if (!ok) throw new Error(body.error_msg || 'Request CSKU gagal')
```

> **Catatan**
>
> Endpoint [Proxy WhatsApp API](https://docs.csku.ai/waba/proxy) berbeda: endpoint itu memakai kode HTTP sungguhan (400, 401, 403, 404, 500) dan format error sendiri.

## Kode HTTP selain 200

| HTTP | Arti |
|---|---|
| 404 | Path tidak ada. Body: `{"status":0,"rc":404,"error_msg":"Page Not Found!"}` |
| 200 + `rc: 500` | Error validasi, autentikasi, atau data tidak ditemukan |

## Waktu

Field waktu seperti `sent_at` memakai format `YYYY-MM-DD HH:MM:SS` dalam zona **WIB (Asia/Jakarta, UTC+7)** tanpa penanda zona. Field `ts` dan `timestamp` adalah Unix detik.

## Daftar error umum

| `error_msg` | Endpoint | Arti |
|---|---|---|
| `conversation id is required` / `conversation_id is required` | semua | `conversation_id` kosong |
| `conversation not found` | semua | Percakapan tidak ada di bisnis Anda |
| `text or media is required` | kirim pesan | Isi `text` atau `media` |
| `media type not supported` | kirim pesan | `media.type` bukan `image`, `video`, `audio`, atau `document` |
| `media mime type not supported` | kirim pesan | MIME tidak didukung, lihat [Kirim pesan](https://docs.csku.ai/api/kirim-pesan) |
| `reply_to_message_id not found` | kirim pesan | `message_id` yang dibalas tidak ditemukan |
| `note is required` | catatan | `note` kosong |
| `secret not valid ` | semua | Lihat [Autentikasi](https://docs.csku.ai/api/autentikasi) |
| `Paket user tidak memiliki fitur API.` | kirim & ambil pesan | Paket tanpa fitur API |

---

Sumber: https://docs.csku.ai/api/kirim-pesan

# Kirim pesan

> Kirim teks atau media ke pelanggan di percakapan yang sudah ada.

`POST https://api.csku.ai/v1/message`

Kirim balasan ke percakapan yang sudah berjalan, di channel apa pun (WhatsApp, Telegram, Instagram, webchat, dan lainnya). CSKU meneruskan pesan ke channel percakapan tersebut.

> **Catatan: Butuh conversation_id**
>
> Endpoint ini hanya membalas percakapan yang sudah ada. `conversation_id` didapat dari [webhook](https://docs.csku.ai/webhook/event) `channel.message_in` atau dari URL chat di dashboard.

## Request

```http
POST /v1/message
Business: BIZ_ID_ANDA
Secret: SECRET_ANDA
Content-Type: application/json
```

| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
| `conversation_id` | string | ya | ID percakapan, contoh `CO_01J9…` |
| `text` | string | salah satu | Isi pesan teks |
| `media` | object | salah satu | Lampiran. Jika `media` diisi, `text` diabaikan |
| `reply_to_message_id` | string | tidak | `message_id` pesan yang dibalas |

Objek `media`:

| Field | Tipe | Keterangan |
|---|---|---|
| `url` | string | URL publik file (https) |
| `type` | string | `image`, `video`, `audio`, atau `document` |
| `mime_type` | string | `image/jpeg`, `image/png`, `video/mp4`, `audio/mp3`, atau `text/plain` |
| `name` | string | Nama file (opsional) |
| `caption` | string | Teks di bawah media (opsional) |
| `thumbnail` | string | URL thumbnail (opsional) |

## Contoh: teks

```bash
curl -X POST https://api.csku.ai/v1/message \
  -H "Business: BIZ_ID_ANDA" \
  -H "Secret: SECRET_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "CO_01J9Z3K8V2",
    "text": "Pesanan #INV-2291 sudah dikirim via JNE ya kak."
  }'
```

## Contoh: gambar

```json
{
  "conversation_id": "CO_01J9Z3K8V2",
  "media": {
    "url": "https://cdn.toko-anda.com/resi/INV-2291.jpg",
    "type": "image",
    "mime_type": "image/jpeg",
    "caption": "Foto resi pengiriman"
  }
}
```

## Respons

```json
{ "conversation_id": "CO_01J9Z3K8V2", "success": true }
```

`success: true` berarti pesan diterima CSKU dan diteruskan ke channel. Status terkirim ke pelanggan bisa dicek lewat [Ambil pesan](https://docs.csku.ai/api/ambil-pesan).

## Perilaku yang perlu diketahui

- Pesan tampil di inbox dashboard sebagai balasan agent dengan nama bisnis Anda.
- Mengirim pesan lewat API **tidak** memicu webhook `agent.message_out`.
- Jika `text` berisi kalimat sekaligus link, CSKU memeriksa setiap link. Link gambar dikirim sebagai pesan gambar terpisah, dan link yang tidak bisa diakses dihapus dari teks. Teks yang isinya hanya satu link dikirim apa adanya.
- Aturan channel tetap berlaku. Misalnya di WhatsApp API, pesan bebas hanya bisa dikirim dalam 24 jam sejak pesan terakhir pelanggan. Di luar itu, kirim template lewat [Proxy WhatsApp API](https://docs.csku.ai/waba/proxy).

---

Sumber: https://docs.csku.ai/api/ambil-pesan

# Ambil pesan

> Ambil riwayat pesan sebuah percakapan, urut dari yang terlama.

`GET https://api.csku.ai/v1/message/{conversation_id}`

Ambil semua pesan dalam satu percakapan, termasuk pesan pelanggan, balasan AI, balasan agent, dan catatan internal.

## Request

```http
GET /v1/message/{conversation_id}?limit=50&last_id=0
Business: BIZ_ID_ANDA
Secret: SECRET_ANDA
```

| Parameter | Lokasi | Keterangan |
|---|---|---|
| `conversation_id` | path | ID percakapan |
| `limit` | query | Jumlah pesan. Kosong atau `0` = semua pesan |
| `last_id` | query | Ambil pesan dengan `id` **lebih besar** dari nilai ini. Pakai untuk ambil pesan baru saja |

Pesan diurutkan dari yang **terlama** (`id` naik).

## Contoh

```bash
curl "https://api.csku.ai/v1/message/CO_01J9Z3K8V2?limit=50" \
  -H "Business: BIZ_ID_ANDA" \
  -H "Secret: SECRET_ANDA"
```

## Respons

```json
{
  "status": 1,
  "rc": 200,
  "message": "list message",
  "data": {
    "list": [
      {
        "id": 10231,
        "message_id": "MSG_01J9Z3M1AB",
        "conversation_id": "CO_01J9Z3K8V2",
        "sender": "user",
        "sender_name": "Budi Santoso",
        "message": "Kak, pesanan saya kapan dikirim?",
        "caption": "",
        "message_type": "text",
        "mime_type": "text/plain",
        "sent_at": "2026-10-14 09:40:12",
        "delivery_status": "read"
      }
    ],
    "last_id": 10231
  },
  "ts": 1760409612
}
```

| Field | Keterangan |
|---|---|
| `sender` | `user` (pelanggan), `agent` (AI, agent manusia, atau API), atau `system` |
| `sender_name` | Nama pengirim. Balasan AI berformat `Nama AI - Label` |
| `message` | Teks pesan, atau URL file untuk pesan media |
| `caption` | Keterangan media |
| `message_type` | `text`, `image`, `video`, `audio`, `document`, dan lainnya |
| `delivery_status` | `pending`, `sent`, `delivered`, `read`, atau `failed` |
| `reply_to_message_id` | ID pesan yang dibalas di channel (hanya ada jika pesan berupa balasan) |
| `sent_at` | Waktu WIB, format `YYYY-MM-DD HH:MM:SS` |

## Ambil pesan baru saja

Simpan `last_id` dari respons, lalu kirim lagi sebagai query untuk mendapat pesan setelahnya:

```bash
curl "https://api.csku.ai/v1/message/CO_01J9Z3K8V2?last_id=10231" \
  -H "Business: BIZ_ID_ANDA" -H "Secret: SECRET_ANDA"
```

Jika tidak ada pesan baru, `list` bernilai `null` dan `last_id` `0`.

> **Tips**
>
> Untuk tahu kapan ada pesan baru, pakai [webhook](https://docs.csku.ai/webhook/setup) daripada memanggil endpoint ini berulang kali.

> **Catatan**
>
> `conversation_id` yang tidak dikenal mengembalikan daftar kosong, bukan error. Catatan internal ikut tercantum dan tidak punya penanda khusus.

---

Sumber: https://docs.csku.ai/api/catatan

# Kirim catatan

> Tambahkan catatan internal ke percakapan. Catatan tidak dikirim ke pelanggan.

`POST https://api.csku.ai/v1/note`

Catatan internal tampil di chat dashboard untuk tim Anda, misalnya hasil pengecekan dari sistem Anda ("Pembayaran INV-2291 sudah diterima"). Pelanggan tidak menerima catatan ini.

## Request

| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
| `conversation_id` | string | ya | ID percakapan |
| `note` | string | ya | Isi catatan |

```bash
curl -X POST https://api.csku.ai/v1/note \
  -H "Business: BIZ_ID_ANDA" \
  -H "Secret: SECRET_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "CO_01J9Z3K8V2",
    "note": "Pembayaran INV-2291 terverifikasi pukul 09.41"
  }'
```

## Respons

```json
{ "message_id": "MSG_01J9Z3P7QW", "success": true }
```

Catatan tampil di dashboard dengan nama pengirim `api`.

## Error

| `error_msg` | Penyebab |
|---|---|
| `conversation_id is required` | `conversation_id` kosong |
| `note is required` | `note` kosong |
| `conversation not found` | Percakapan tidak ditemukan |

---

Sumber: https://docs.csku.ai/api/butuh-cs

# Tandai butuh CS

> Hentikan balasan AI dan masukkan percakapan ke antrean Butuh CS.

`POST https://api.csku.ai/v1/conversation/need-human`

Pakai saat sistem Anda mendeteksi percakapan yang harus ditangani manusia, misalnya komplain, refund, atau pelanggan VIP. Setelah dipanggil:

- AI berhenti membalas percakapan ini.
- Percakapan masuk tab **Butuh CS** di dashboard.

## Request

| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
| `conversation_id` | string | ya | ID percakapan |

```bash
curl -X POST https://api.csku.ai/v1/conversation/need-human \
  -H "Business: BIZ_ID_ANDA" \
  -H "Secret: SECRET_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "CO_01J9Z3K8V2"}'
```

## Respons

```json
{ "success": true, "conversation_id": "CO_01J9Z3K8V2" }
```

Memanggil ulang pada percakapan yang sudah ditandai tetap mengembalikan sukses.

> **Catatan: Mengembalikan ke AI**
>
> Belum ada endpoint untuk mengembalikan percakapan ke AI. Agent melakukannya dari dashboard atau aplikasi dengan tombol **Kembalikan ke AI** atau **Selesai**.

---

Sumber: https://docs.csku.ai/api/butuh-cs-total

# Total butuh CS

> Jumlah percakapan yang sedang ditangani manusia.

`GET https://api.csku.ai/v1/conversation/need-human/total`

Hitung percakapan yang AI-nya sedang dijeda karena ditangani manusia, termasuk yang ditandai lewat [Tandai butuh CS](https://docs.csku.ai/api/butuh-cs) dan yang diambil alih agent. Cocok untuk indikator antrean di sistem internal Anda.

## Request

```bash
curl https://api.csku.ai/v1/conversation/need-human/total \
  -H "Business: BIZ_ID_ANDA" \
  -H "Secret: SECRET_ANDA"
```

## Respons

```json
{ "success": true, "total": 7 }
```

---

Sumber: https://docs.csku.ai/webhook/setup

# Setup webhook

> Daftarkan URL webhook di dashboard dan siapkan server yang menerima event dari CSKU.


Webhook membuat CSKU mengirim `POST` ke server Anda setiap kali ada pesan masuk dari pelanggan, balasan AI, atau balasan agen. Anda tidak perlu polling ke [Ambil pesan](https://docs.csku.ai/api/ambil-pesan).

## Prasyarat

- Paket Anda punya fitur **Webhook**. Jika tidak, menu Webhook menampilkan ajakan upgrade. Lihat [Berlangganan & kredit](https://docs.csku.ai/panduan/berlangganan).
- Anda login sebagai **owner** bisnis. OTP hanya dikirim ke email owner.
- **Secret Key** sudah dibuat di **Pengaturan → Secret Key**. Nilai ini dikirim di header `Authorization` setiap request webhook. Lihat [Autentikasi](https://docs.csku.ai/api/autentikasi).
- Server Anda bisa diakses publik lewat `https`. Dashboard menolak URL `http`, `localhost`, dan alamat IP privat.

## Daftarkan URL

1. Buka **Pengaturan → Webhook**.
2. Isi **Webhook URL**, misalnya `https://api.toko-anda.com/csku/webhook`.
3. Klik **Perbarui Webhook**, lalu konfirmasi. CSKU mengirim kode OTP 6 digit ke email owner. Kode berlaku 5 menit.
4. Masukkan kode OTP, lalu klik **Perbarui Webhook**.

Setelah tersimpan, semua event langsung dikirim ke URL tersebut.

> **Catatan: Satu URL, semua event**
>
> Setiap bisnis punya satu URL webhook. Semua event dikirim ke URL itu dan tidak bisa difilter dari dashboard. Abaikan event yang tidak Anda perlukan di server Anda. Daftar event ada di [Event & payload](https://docs.csku.ai/webhook/event).

## Contoh penerima

Server Anda wajib:

1. Mencocokkan header `Authorization` dengan Secret Key Anda.
2. Membalas body JSON `{"success": true}` secepatnya (di bawah 30 detik).

Status HTTP tidak dibaca. Yang menentukan sukses hanya field `success` di body. Detail ada di [Keamanan & retry](https://docs.csku.ai/webhook/keamanan-retry).

### Node.js (Express)

```js
import express from 'express'
import crypto from 'node:crypto'

const app = express()
app.use(express.json())

const SECRET = process.env.CSKU_SECRET

function isValid(header) {
  const a = Buffer.from(header || '')
  const b = Buffer.from(SECRET)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

app.post('/csku/webhook', (req, res) => {
  if (!isValid(req.get('Authorization'))) {
    return res.status(401).json({ success: false })
  }

  res.json({ success: true })

  // Proses setelah membalas
  const { event, message } = req.body
  console.log(event, message.id)
})

app.listen(3000)
```

### PHP

```php
<?php
$secret = getenv('CSKU_SECRET');
$auth = $_SERVER['HTTP_AUTHORIZATION'] ?? '';

header('Content-Type: application/json');

if (!hash_equals($secret, $auth)) {
    http_response_code(401);
    echo json_encode(['success' => false]);
    exit;
}

$payload = json_decode(file_get_contents('php://input'), true);

// Simpan ke antrean, lalu balas
echo json_encode(['success' => true]);
```

> **Tips: Header Authorization di Apache**
>
> Beberapa konfigurasi Apache + PHP-FPM tidak meneruskan header `Authorization`. Jika `$_SERVER['HTTP_AUTHORIZATION']` kosong, tambahkan `SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1` di `.htaccess`.

### Python (Flask)

```python
import hmac
import os
from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET = os.environ["CSKU_SECRET"]

@app.post("/csku/webhook")
def csku_webhook():
    auth = request.headers.get("Authorization", "")
    if not hmac.compare_digest(auth, SECRET):
        return jsonify(success=False), 401

    payload = request.get_json(silent=True) or {}
    # Kirim ke antrean / background job
    print(payload.get("event"), payload.get("message", {}).get("id"))

    return jsonify(success=True)
```

### Go

```go
package main

import (
	"crypto/subtle"
	"encoding/json"
	"net/http"
	"os"
)

var secret = []byte(os.Getenv("CSKU_SECRET"))

func webhook(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")

	auth := []byte(r.Header.Get("Authorization"))
	if subtle.ConstantTimeCompare(auth, secret) != 1 {
		w.WriteHeader(http.StatusUnauthorized)
		w.Write([]byte(`{"success":false}`))
		return
	}

	var payload map[string]any
	if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
		w.Write([]byte(`{"success":false}`))
		return
	}

	// Proses di goroutine / antrean
	w.Write([]byte(`{"success":true}`))
}

func main() {
	http.HandleFunc("/csku/webhook", webhook)
	http.ListenAndServe(":3000", nil)
}
```

## Uji saat development

Belum ada tombol "kirim webhook uji". Untuk mencoba:

1. Pakai URL publik sementara:
   - [webhook.site](https://webhook.site) untuk melihat isi request tanpa menulis kode. Ingat: webhook.site tidak membalas `{"success": true}` secara default, jadi CSKU akan mencoba ulang.
   - Tunnel ke server lokal, misalnya `ngrok http 3000` atau `cloudflared tunnel --url http://localhost:3000`. Daftarkan URL `https` yang diberikan tunnel.
2. Picu event sungguhan: kirim pesan ke salah satu channel Anda (misalnya lewat Webchat atau WhatsApp). Anda akan menerima `channel.message_in`, lalu `ai.message_generated` jika AI agent aktif.
3. Balas dari menu **Chat** di dashboard untuk menerima `agent.message_out`.

> **Peringatan: Ganti URL setelah selesai**
>
> URL tunnel biasanya berubah setiap kali dijalankan ulang. Daftarkan URL produksi sebelum go-live, agar event tidak terkirim ke alamat yang sudah mati.

## Reset webhook

Buka **Pengaturan → Webhook**, klik **Reset**, lalu konfirmasi. URL dihapus dan CSKU berhenti mengirim event. Untuk mengaktifkan lagi, daftarkan URL baru dengan OTP.

## Selanjutnya

- [Event & payload](https://docs.csku.ai/webhook/event): Daftar event dan isi lengkap payload.
- [Keamanan & retry](https://docs.csku.ai/webhook/keamanan-retry): Verifikasi request, aturan sukses, dan jadwal retry.

---

Sumber: https://docs.csku.ai/webhook/event

# Event & payload

> Tiga event webhook CSKU, contoh JSON lengkap, dan arti setiap field.


Setiap request webhook berisi satu pesan dan satu event. Bentuk payload sama untuk semua event; hanya field `message.agent` dan `message.ai` yang muncul sesuai event.

## Daftar event

| Event | Kapan dikirim |
| --- | --- |
| `channel.message_in` | Pesan pelanggan masuk dan tersimpan. Berlaku untuk semua channel, termasuk Webchat, dan tetap dikirim walau percakapan sedang ditangani agen. |
| `ai.message_generated` | AI agent selesai membuat balasan dan balasan tersimpan, tepat sebelum dikirim ke pelanggan. |
| `agent.message_out` | Balasan agen dari dashboard atau aplikasi mobile berhasil terkirim ke channel. Termasuk pesan sistem CSAT (permintaan penilaian dan ucapan terima kasih). |

> **Catatan: Jeda balasan AI**
>
> AI agent menunggu sekitar 30 detik untuk menggabungkan beberapa pesan pelanggan sebelum membalas. Jadi `ai.message_generated` biasanya datang beberapa detik sampai sekitar 30 detik setelah `channel.message_in` terakhir.

> **Peringatan: Pesan dari Public API tidak memicu webhook**
>
> Pesan yang Anda kirim lewat [Kirim pesan](https://docs.csku.ai/api/kirim-pesan) (`POST /v1/message`) atau lewat [Proxy WABA](https://docs.csku.ai/waba/proxy) **tidak** memicu `agent.message_out`. Sistem Anda sudah tahu pesan itu, jadi catat langsung di sisi Anda.

## Contoh payload

### channel.message_in

```json
{
  "event": "channel.message_in",
  "timestamp": 1792041600,
  "conversation_id": "CO_01JQ8Z3K4M5N6P7R8S9T0V1W2X",
  "conversation_label": "Budi Santoso",
  "need_human": 0,
  "message": {
    "id": "MSG_01JQ8Z3M2A7B8C9D0E1F2G3H4J",
    "sender_name": "Budi Santoso",
    "channel": {
      "id": "WHATSAPP_01JP4R6T8V0X2Z4B6D8F0H2K4M",
      "name": "CS Toko Utama",
      "engine": "whatsapp"
    },
    "bisnis": {
      "id": "BIZ241005ABC1234",
      "name": "Rina Wijaya"
    },
    "user": {
      "id": "MER241005XYZ0001",
      "name": "Rina Wijaya"
    },
    "content": {
      "type": "text",
      "text": "Halo kak, pesanan saya sudah dikirim belum?"
    }
  }
}
```

### ai.message_generated

```json
{
  "event": "ai.message_generated",
  "timestamp": 1792041631,
  "conversation_id": "CO_01JQ8Z3K4M5N6P7R8S9T0V1W2X",
  "conversation_label": "Budi Santoso",
  "need_human": 0,
  "message": {
    "id": "MSG_01JQ8Z4N9Q1R2S3T4U5V6W7X8Y",
    "sender_name": "Asisten - Sari",
    "channel": {
      "id": "WHATSAPP_01JP4R6T8V0X2Z4B6D8F0H2K4M",
      "name": "CS Toko Utama",
      "engine": "whatsapp"
    },
    "bisnis": {
      "id": "BIZ241005ABC1234",
      "name": "Rina Wijaya"
    },
    "user": {
      "id": "MER241005XYZ0001",
      "name": "Rina Wijaya"
    },
    "content": {
      "type": "text",
      "text": "Halo Kak Budi, pesanan Kakak sudah dikirim hari ini via JNE ya."
    },
    "ai": {
      "name": "Sari",
      "id": "AI241005QWE5678"
    }
  }
}
```

### agent.message_out

```json
{
  "event": "agent.message_out",
  "timestamp": 1792041900,
  "conversation_id": "CO_01JQ8Z3K4M5N6P7R8S9T0V1W2X",
  "conversation_label": "Budi Santoso",
  "need_human": 1,
  "message": {
    "id": "MSG_01JQ8Z8D3F4G5H6J7K8L9M0N1P",
    "sender_name": "Dewi",
    "channel": {
      "id": "WHATSAPP_01JP4R6T8V0X2Z4B6D8F0H2K4M",
      "name": "CS Toko Utama",
      "engine": "whatsapp"
    },
    "bisnis": {
      "id": "BIZ241005ABC1234",
      "name": "Rina Wijaya"
    },
    "user": {
      "id": "MER241005XYZ0001",
      "name": "Rina Wijaya"
    },
    "content": {
      "type": "image",
      "attachments": [
        {
          "url": "https://bukakios-storage.b-cdn.net/chat/resi-budi.jpg",
          "mime_type": "image/jpeg"
        }
      ]
    },
    "agent": {
      "name": "Dewi"
    }
  }
}
```

## Referensi field

| Field | Tipe | Keterangan |
| --- | --- | --- |
| `event` | string | Nama event. Lihat [daftar event](#daftar-event). |
| `timestamp` | integer | Unix time (detik) saat request dikirim. Berubah di setiap retry, jadi jangan dipakai untuk deduplikasi. |
| `conversation_id` | string | ID percakapan. Sama dengan `conversation_id` di Public API. |
| `conversation_label` | string | Nama tampilan percakapan, biasanya nama pelanggan. |
| `need_human` | integer | `1` jika percakapan sedang ditangani agen (AI berhenti membalas), `0` jika tidak. |
| `message.id` | string | ID unik pesan. Pakai untuk deduplikasi. |
| `message.sender_name` | string | Nama pengirim: pelanggan, AI agent, atau agen. Bisa kosong untuk pesan sistem. |
| `message.channel.id` | string | ID channel di CSKU. |
| `message.channel.name` | string | Label channel yang Anda isi di **Integrasi**. |
| `message.channel.engine` | string | Jenis channel. Lihat [nilai engine](#nilai-engine). |
| `message.bisnis.id` | string | Business ID Anda. |
| `message.bisnis.name` | string | Nama akun pemilik bisnis. |
| `message.user.id` | string | ID akun pemilik bisnis. |
| `message.user.name` | string | Nama akun pemilik bisnis. |
| `message.content` | object | Isi pesan. Lihat [tipe konten](#tipe-konten). |
| `message.agent.name` | string | Hanya di `agent.message_out`. Nama agen yang membalas. |
| `message.ai.name` | string | Hanya di `ai.message_generated`, jika channel punya AI agent. Label AI agent. |
| `message.ai.id` | string | ID AI agent. |

## Tipe konten

Pesan teks:

```json
{ "type": "text", "text": "Halo kak" }
```

Pesan selain teks memakai `attachments`. `url` berisi alamat file, `mime_type` berisi tipe file.

```json
{
  "type": "document",
  "attachments": [
    { "url": "https://bukakios-storage.b-cdn.net/chat/invoice.pdf", "mime_type": "application/pdf" }
  ]
}
```

Contoh nilai `type`: `image`, `video`, `audio`, `document`. Nilai lain bisa muncul tergantung channel. Perlakukan `type` selain `text` yang tidak Anda kenal sebagai lampiran biasa.

> **Catatan: Caption tidak ikut**
>
> Untuk pesan media, payload hanya berisi `url` dan `mime_type`. Teks caption tidak disertakan.

## Nilai engine

| `engine` | Channel |
| --- | --- |
| `whatsapp` | WhatsApp (Scan QR) |
| `waba` | WhatsApp API (Token manual) |
| `whatsapp_meta` | WhatsApp API (Login Meta) |
| `telegram` | Telegram |
| `instagram` | Instagram |
| `facebook` | Facebook |
| `intercom` | Intercom |
| `slack` | Slack |
| `socialchat` | SocialChat |
| `webchat` | Webchat |

---

Sumber: https://docs.csku.ai/webhook/keamanan-retry

# Keamanan & retry

> Cara memverifikasi request webhook, aturan sukses, jadwal retry, dan checklist saat webhook tidak masuk.


Siapa pun yang tahu URL webhook Anda bisa mengirim request palsu. Karena itu, setiap request dari CSKU membawa Secret Key Anda di header `Authorization`. Tolak semua request yang nilainya tidak cocok.

## Format request

```http
POST /csku/webhook HTTP/1.1
Host: api.toko-anda.com
Content-Type: application/json
Authorization: 3f9a1c7e5b2d4f6a8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f3a

{"event":"channel.message_in","timestamp":1792041600, ...}
```

- `Authorization` berisi Secret Key Anda **apa adanya**: tanpa awalan `Bearer`, tanpa base64.
- Tidak ada header signature atau timestamp terpisah. Verifikasi cukup dengan mencocokkan `Authorization`.
- Secret Key ada di **Pengaturan → Secret Key**. Lihat [Autentikasi](https://docs.csku.ai/api/autentikasi).

## Verifikasi Authorization

Bandingkan dengan fungsi constant-time, bukan `==`, agar waktu perbandingan tidak membocorkan isi secret.

```js
import crypto from 'node:crypto'

function isFromCsku(header, secret) {
  const a = Buffer.from(header || '')
  const b = Buffer.from(secret)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}
```

```php
<?php
$ok = hash_equals(getenv('CSKU_SECRET'), $_SERVER['HTTP_AUTHORIZATION'] ?? '');
```

```python
import hmac
ok = hmac.compare_digest(request.headers.get("Authorization", ""), SECRET)
```

```go
ok := subtle.ConstantTimeCompare([]byte(r.Header.Get("Authorization")), secret) == 1
```

Jika tidak cocok, balas `{"success": false}` dan jangan proses payload.

> **Penting: Simpan secret di server**
>
> Secret Key yang sama dipakai untuk memanggil Public API. Simpan hanya di server (environment variable atau secret manager). Jangan taruh di kode frontend, aplikasi mobile, repository publik, atau log.

## Ganti (rotate) secret

Reset Secret Key di **Pengaturan → Secret Key** (butuh OTP ke email owner). Yang berubah:

- Webhook berikutnya, termasuk retry, langsung memakai secret baru di header `Authorization`.
- Panggilan Public API dengan secret lama ditolak.

Urutan aman:

1. Siapkan server agar sementara menerima secret lama **atau** baru.
2. Reset secret di dashboard, lalu simpan secret baru di server.
3. Hapus secret lama dari server.

## Aturan sukses

CSKU menganggap pengiriman **sukses** hanya jika body respons Anda berupa JSON dengan field `success` bernilai benar:

```json
{ "success": true }
```

Nilai `true`, `"true"`, atau `1` diterima. Status HTTP **tidak** dibaca, jadi `200` dengan body kosong tetap dianggap gagal.

Dianggap **gagal**:

- Tidak ada respons dalam 30 detik (timeout).
- Koneksi gagal (DNS, TLS, server mati).
- Body bukan JSON, atau field `success` tidak ada.
- `success` bernilai `false`.

## Jadwal retry

Pengiriman yang gagal dicoba ulang otomatis. Total maksimal 4 percobaan:

| Percobaan | Waktu (perkiraan) |
| --- | --- |
| 1 | Saat event terjadi |
| 2 | Langsung setelah percobaan 1 gagal |
| 3 | Sekitar 30 detik setelah percobaan 2 |
| 4 | Sekitar 30 detik setelah percobaan 3 |

Setelah percobaan ke-4 gagal, event itu dilepas dan tidak dikirim lagi. Jika server Anda mati lebih dari sekitar satu menit, ambil pesan yang terlewat lewat [Ambil pesan](https://docs.csku.ai/api/ambil-pesan).

## Idempotensi dan urutan

- **Deduplikasi dengan `message.id`.** Event yang sama bisa datang lebih dari sekali, misalnya jika server Anda sudah memproses tetapi respons terlambat. Simpan `message.id` yang sudah diproses dan abaikan duplikat. Jangan pakai `timestamp`, karena nilainya berubah di setiap percobaan.
- **Urutan tidak dijamin.** Setiap event dikirim sendiri-sendiri. Retry bisa membuat event lama datang setelah event baru. Jika urutan penting, urutkan di sisi Anda, atau ambil riwayat lewat [Ambil pesan](https://docs.csku.ai/api/ambil-pesan).

## Respons cepat, proses belakangan

Batas waktu 30 detik termasuk semua yang Anda kerjakan sebelum membalas. Pola yang aman:

1. Verifikasi `Authorization`.
2. Simpan payload ke antrean atau database.
3. Balas `{"success": true}`.
4. Proses (panggil sistem lain, kirim notifikasi) di background job.

## Checklist jika webhook tidak masuk

- Paket Anda masih punya fitur **Webhook** dan masih aktif. Lihat [Berlangganan & kredit](https://docs.csku.ai/panduan/berlangganan).
- URL di **Pengaturan → Webhook** benar, memakai `https`, dan bisa diakses dari internet (bukan `localhost` atau IP privat).
- Sertifikat TLS server valid dan tidak kedaluwarsa.
- Firewall atau WAF (misalnya proteksi bot) tidak memblokir request `POST` dari server CSKU.
- Server membaca header `Authorization` dengan benar. Di Apache + PHP, header ini kadang tidak diteruskan.
- Secret di server sama dengan Secret Key terbaru. Jika Anda baru reset, perbarui juga di server.
- Respons Anda berupa JSON `{"success": true}`, bukan teks atau body kosong.
- Respons dikirim dalam waktu kurang dari 30 detik.
- Event yang Anda tunggu memang dikirim. Pesan dari Public API dan Proxy WABA tidak memicu `agent.message_out`. Lihat [Event & payload](https://docs.csku.ai/webhook/event).

---

Sumber: https://docs.csku.ai/webchat/pasang

# Pasang widget

> Buat channel Webchat di dashboard, bagikan link chat, lalu pasang tombol chat melayang di website Anda.


Webchat adalah channel chat untuk website Anda. Pengunjung bisa chat lewat link khusus atau lewat tombol chat melayang di pojok website. Semua percakapan masuk ke menu **Chat** di dashboard, dan AI agent yang Anda pilih bisa menjawab otomatis.

## Buat channel Webchat

1. Buka menu **Integrasi**, lalu klik kartu **Webchat**.
2. Klik **Tambah Channel**. Jika belum ada channel, klik **Tambah Channel Pertama**.
3. Isi form di sisi kiri. **Pratinjau** di sisi kanan ikut berubah saat Anda mengetik.
4. Klik **Simpan Channel**. Bagian **Pasang** muncul di bawah form, berisi link dan kode embed.

| Isian | Fungsi | Catatan |
|---|---|---|
| Nama channel | Tampil di bagian atas jendela chat. | Wajib, maksimal 60 karakter. |
| AI Agent | AI agent yang menjawab pengunjung. | Opsional. Pilih **Tanpa AI agent** jika chat dijawab manual. |
| Divisi | Tim yang bisa melihat channel dan percakapannya. | Wajib minimal satu jika akun punya divisi. Tidak bisa diubah setelah channel dibuat. |
| Warna utama | Warna tombol chat, kepala jendela, dan gelembung pesan pengunjung. | Kode warna seperti `#4152e9`. |
| Logo brand | Tampil bulat di kepala jendela chat dan di tombol widget. | Opsional. PNG, JPG, atau WebP, maksimal 1 MB. |
| Salam pembuka | Kalimat pertama yang dilihat pengunjung. | Boleh kosong, maksimal 300 karakter. |
| Posisi tombol widget | Tombol muncul di sisi **Kanan** atau **Kiri**. | Pilih salah satu. |
| Form pra-chat | Meminta nama dan nomor HP sebelum chat dimulai. | Email opsional. |

> **Peringatan: Centang divisi Anda sendiri**
>
> Hanya anggota divisi yang dicentang yang bisa melihat channel dan percakapannya. Divisi tidak bisa diubah setelah channel dibuat.

## Bagikan link chat

Cara tercepat tanpa mengubah website. Di bagian **Pasang**, klik **Salin** pada **Link webchat**. Bentuk linknya:

```bash
https://app.csku.ai/webchat/<ID_CHANNEL>
```

Pengunjung yang membuka link langsung melihat halaman chat. Bagikan di bio Instagram, status WhatsApp, tanda tangan email, atau brosur digital. Klik **Buka demo** untuk melihat tampilan pengunjung.

## Pasang widget di website

Di bagian **Pasang**, klik **Salin kode** pada **Kode embed widget**. Bentuk kodenya:

```html
<script>window.cskuSettings = {"channelKey": "<ID_CHANNEL>", "position": "right"};</script>
<script src="https://app.csku.ai/widget/widget.js" async></script>
```

Tempel kode tepat sebelum tag penutup `</body>`. Jika website punya satu template untuk semua halaman, tempel di template itu supaya tombol muncul di semua halaman.

> **Tips: Salin dari dashboard**
>
> Kode dari dashboard sudah berisi ID channel yang benar. Jangan mengetik ulang contoh di atas.

Kode cukup dipasang sekali. Warna, logo, posisi, salam pembuka, dan form pra-chat diambil dari dashboard setiap halaman dimuat. Domain website tidak perlu didaftarkan.

### HTML biasa

Buka file halaman, cari `</body>`, lalu tempel kode tepat di atasnya.

### WordPress

Pakai plugin penyisip kode yang punya kolom footer, misalnya "Insert Headers and Footers". Tempel kode di kolom footer, lalu simpan. Cara lain: tempel di `footer.php` tema Anda, tepat sebelum `</body>`. Jika memakai plugin cache, kosongkan cache setelahnya.

### Next.js, Nuxt, dan SPA lain

Widget harus dimuat satu kali per halaman, hanya di browser. Pemasangan kedua di halaman yang sama diabaikan, dan widget tidak perlu dimuat ulang saat pindah route. Pasang di layout induk, bukan di komponen halaman.

Next.js (App Router), di `app/layout.tsx`:

```js
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html lang="id">
      <body>
        {children}
        <Script id="csku-settings" strategy="afterInteractive">
          {`window.cskuSettings = {"channelKey": "<ID_CHANNEL>", "position": "right"};`}
        </Script>
        <Script src="https://app.csku.ai/widget/widget.js" strategy="afterInteractive" />
      </body>
    </html>
  )
}
```

Nuxt 3, di `nuxt.config.ts`:

```js
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        { innerHTML: 'window.cskuSettings = {"channelKey": "<ID_CHANNEL>", "position": "right"};', tagPosition: 'bodyClose' },
        { src: 'https://app.csku.ai/widget/widget.js', async: true, tagPosition: 'bodyClose' },
      ],
    },
  },
})
```

Pastikan `window.cskuSettings` sudah ada sebelum `widget.js` berjalan. Untuk SPA biasa (Vite, Create React App), tempel kode di `index.html`.

## Periksa pemasangan

Buka website Anda di jendela penyamaran atau di HP, lalu periksa:

1. Tombol chat muncul di sisi dan warna yang Anda pilih.
2. Klik tombol, jendela chat terbuka dengan nama channel dan salam pembuka yang benar.
3. Kirim pesan. AI agent membalas jika channel memakai AI agent.
4. Buka menu **Chat** di dashboard, pastikan percakapan masuk.

Jika tombol tidak muncul, buka Console browser dan cari pesan berawalan `[CSKU Webchat]`. Lihat juga [Content Security Policy](https://docs.csku.ai/webchat/csp).

## Lepas atau hapus

- **Lepas dari website.** Hapus kedua tag `<script>` dari website. Tombol hilang, tetapi link chat tetap berfungsi.
- **Hapus channel.** Di **Integrasi** → **Webchat**, klik ikon hapus pada channel, lalu **Ya, Hapus**. Link chat dan widget yang terpasang berhenti berfungsi. Percakapan lama tetap ada di menu **Chat**.

Channel tidak bisa dimatikan sementara. Pilih salah satu cara di atas.

---

Sumber: https://docs.csku.ai/webchat/konfigurasi

# Konfigurasi

> Opsi snippet widget Webchat, pengaturan tampilan dari dashboard, dan perilaku widget di website.


Snippet widget hanya punya sedikit opsi. Hampir semua pengaturan, termasuk tampilan, diatur di dashboard dan berlaku otomatis di widget yang sudah terpasang.

## Opsi snippet

Opsi diisi di objek `window.cskuSettings`, sebelum `widget.js` dimuat.

```html
<script>window.cskuSettings = {"channelKey": "<ID_CHANNEL>", "position": "right", "zIndex": 2147483000};</script>
<script src="https://app.csku.ai/widget/widget.js" async></script>
```

| Opsi | Tipe | Keterangan |
|---|---|---|
| `channelKey` | string | Wajib. ID channel dari dashboard. 8–64 karakter: huruf, angka, `_`, `-`. |
| `position` | string | `right` (bawaan) atau `left`. Posisi yang tersimpan di dashboard menimpa nilai ini. |
| `zIndex` | integer | Tumpukan tombol terhadap elemen lain. Bawaan `2147483000`. Jendela chat memakai nilai ini + 1. |
| `primaryColor` | string | Opsional, format `#rrggbb`. Hanya mewarnai tombol sampai pengaturan dashboard selesai dimuat. |

Opsi lain di `window.cskuSettings` diabaikan. Nama channel, salam pembuka, dan form pra-chat hanya bisa diatur dari dashboard.

> **Peringatan: Jangan taruh data rahasia di snippet**
>
> Snippet terlihat oleh semua pengunjung. `secretKey` dan `merchantId` tidak dipakai lagi; jika masih ada, hapus dari snippet. Cukup `channelKey`.

## Tampilan dari dashboard

Ubah di **Integrasi** → **Webchat** → ikon edit, lalu klik **Simpan Perubahan**. Kode di website tidak perlu diganti; pengunjung melihat perubahan setelah halaman dimuat ulang.

| Pengaturan | Berlaku di |
|---|---|
| Warna utama | Tombol, kepala jendela, gelembung pesan pengunjung. |
| Logo brand | Kepala jendela dan tombol widget. |
| Posisi tombol widget | Sisi tombol dan jendela chat. |
| Nama channel, salam pembuka | Jendela chat. |
| Form pra-chat | Pengunjung baru diminta nama dan nomor HP. |

Saat halaman dimuat, widget mengambil warna, posisi, dan logo dari `https://api.csku.ai/v1/webchat/config/<ID_CHANNEL>`. Jika permintaan gagal, tombol tetap tampil dengan warna dan posisi dari snippet. Logo hanya ditampilkan jika berasal dari `https://cdn.aplikasikreasi.id`, yaitu lokasi file yang diunggah lewat dashboard.

## Perilaku widget

- **Jendela chat dimuat saat dibutuhkan.** Jendela chat berupa iframe ke `https://app.csku.ai/webchat/<ID_CHANNEL>?embed=1`. Iframe baru dimuat saat tombol pertama kali diklik, jadi widget tidak memperlambat halaman Anda.
- **Badge belum dibaca.** Saat jendela tertutup, balasan baru menampilkan angka di tombol, maksimal 99. Badge hilang saat jendela dibuka.
- **Layar kecil.** Di layar dengan lebar di bawah 480 px, jendela chat tampil layar penuh.
- **Menutup jendela.** Klik tombol chat lagi, tombol tutup di jendela, atau tekan `Escape`.
- **Riwayat pengunjung.** Pengunjung yang kembali dengan browser yang sama melihat percakapan sebelumnya. Jika ganti browser, ganti perangkat, atau menghapus data browser, pengunjung mulai dari awal.
- **Percakapan selesai.** Setelah agen menekan **Selesai**, pengunjung bisa memulai percakapan baru. Jika punya lebih dari satu percakapan, pengunjung bisa membuka **Riwayat percakapan** dari ikon jam.

## Lampiran dan batas

| Batas | Nilai |
|---|---|
| Panjang satu pesan | 2000 karakter |
| Ukuran lampiran | 5 MB |
| Format lampiran | JPG, PNG, WEBP, GIF, PDF |

File di luar format ini ditolak dengan pesan "Format tidak didukung". File lebih dari 5 MB ditolak dengan pesan "Ukuran file melebihi 5 MB". Tampilan chat berbahasa Indonesia dan bertema terang.

## Pemeriksaan keamanan

Pengunjung baru melewati pemeriksaan anti-spam otomatis (Cloudflare Turnstile) saat memulai chat. Pemeriksaan berjalan di dalam iframe, jadi website Anda tidak perlu memuat atau mengizinkan Turnstile. Jika gagal, pengunjung melihat "Verifikasi keamanan gagal. Coba lagi."

---

Sumber: https://docs.csku.ai/webchat/csp

# Content Security Policy

> Directive CSP yang perlu diizinkan agar widget Webchat tampil di website Anda.


Jika website Anda memakai Content Security Policy (CSP), browser memblokir widget sampai sumbernya diizinkan. Tambahkan sumber berikut ke policy yang sudah ada. Jangan mengganti seluruh policy Anda dengan contoh di halaman ini.

## Directive yang dibutuhkan

| Directive | Sumber | Untuk |
|---|---|---|
| `script-src` | `https://app.csku.ai` | `widget.js` |
| `style-src` | `https://app.csku.ai` | `widget.css` |
| `frame-src` | `https://app.csku.ai` | Jendela chat (iframe) |
| `connect-src` | `https://api.csku.ai` | Mengambil warna, posisi, dan logo dari dashboard |
| `img-src` | `https://cdn.aplikasikreasi.id` | Logo di tombol widget |

Baris `window.cskuSettings = ...` adalah script inline. Izinkan dengan salah satu cara di [Script inline](#script-inline).

Pemeriksaan anti-spam (Cloudflare Turnstile) berjalan di dalam iframe CSKU, jadi website Anda tidak perlu mengizinkan `challenges.cloudflare.com`.

## Contoh header

Contoh ini memakai nonce untuk script inline. Ganti `RANDOM_NONCE` dengan nilai acak baru di setiap respons.

```http
Content-Security-Policy: default-src 'self'; script-src 'self' https://app.csku.ai 'nonce-RANDOM_NONCE'; style-src 'self' https://app.csku.ai; frame-src https://app.csku.ai; connect-src 'self' https://api.csku.ai; img-src 'self' https://cdn.aplikasikreasi.id
```

```html
<script nonce="RANDOM_NONCE">window.cskuSettings = {"channelKey": "<ID_CHANNEL>", "position": "right"};</script>
<script src="https://app.csku.ai/widget/widget.js" async></script>
```

## Contoh meta tag

Jika Anda tidak bisa mengatur header server, pakai tag `<meta>` di `<head>`:

```html
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' https://app.csku.ai 'unsafe-inline'; style-src 'self' https://app.csku.ai; frame-src https://app.csku.ai; connect-src 'self' https://api.csku.ai; img-src 'self' https://cdn.aplikasikreasi.id">
```

## Script inline

Pilih salah satu:

- **Nonce.** Tambahkan `'nonce-<nilai>'` ke `script-src` dan atribut `nonce="<nilai>"` ke tag settings. Nilai harus acak dan baru di setiap respons.
- **Hash.** Tambahkan hash SHA-256 isi script settings ke `script-src`, misalnya `'sha256-...'`. Hash berubah jika isi script berubah, termasuk spasi.
- **File eksternal.** Pindahkan baris settings ke file JavaScript di domain Anda, lalu muat sebelum `widget.js`. Tidak perlu mengubah `script-src` selain `'self'`.
- **`'unsafe-inline'`.** Paling mudah, tetapi melemahkan CSP untuk seluruh halaman. Hindari jika bisa.

Contoh file eksternal:

```js
// /js/csku-settings.js
window.cskuSettings = { channelKey: '<ID_CHANNEL>', position: 'right' }
```

```html
<script src="/js/csku-settings.js"></script>
<script src="https://app.csku.ai/widget/widget.js" async></script>
```

Muat file settings tanpa `async`, supaya selesai sebelum `widget.js` berjalan.

## Troubleshooting

Buka Console browser (F12). Pesan widget berawalan `[CSKU Webchat]`. Pelanggaran CSP muncul sebagai pesan "Refused to load ..." atau "Refused to execute inline script ...".

| Gejala | Penyebab | Solusi |
|---|---|---|
| `[CSKU Webchat] channelKey tidak valid atau belum diisi.` | `channelKey` kosong atau salah format, atau script settings diblokir CSP. | Salin ulang kode dari dashboard. Izinkan script inline. |
| `[CSKU Webchat] Gagal memuat widget.css.` | `style-src` belum mengizinkan `https://app.csku.ai`. | Tambahkan ke `style-src`. |
| `[CSKU Webchat] Loader harus dimuat lewat <script src="...">.` | `widget.js` disalin isinya ke script inline atau dimuat lewat cara lain. | Muat dengan `<script src="https://app.csku.ai/widget/widget.js" async>`. |
| `[CSKU Webchat] secretKey dan merchantId tidak dipakai lagi.` | Snippet versi lama. | Hapus `secretKey` dan `merchantId`, pakai `channelKey`. |
| Tombol muncul, jendela chat kosong | `frame-src` belum mengizinkan `https://app.csku.ai`. | Tambahkan ke `frame-src`. |
| Warna atau posisi tidak sesuai dashboard | `connect-src` belum mengizinkan `https://api.csku.ai`. | Tambahkan ke `connect-src`. |
| Logo tidak tampil di tombol | `img-src` belum mengizinkan `https://cdn.aplikasikreasi.id`. | Tambahkan ke `img-src`. |
| Tidak ada pesan, tombol tidak muncul | `script-src` memblokir `widget.js`. | Tambahkan `https://app.csku.ai` ke `script-src`. |

Jika `frame-src` tidak ada di policy Anda, browser memakai `child-src` lalu `default-src`. Tambahkan `https://app.csku.ai` di directive yang berlaku.

---

Sumber: https://docs.csku.ai/webchat/android

# Integrasi Android

> Tampilkan Webchat di aplikasi Android lewat WebView, dengan data user yang login langsung terisi dan riwayat chat yang ikut pindah perangkat.


Webchat bisa dibuka layar penuh di dalam aplikasi Android lewat `WebView`. Aplikasi mengirim nama dan nomor HP user yang login, sehingga form pra-chat dilewati. Contoh di halaman ini memakai Kotlin.

## URL chat

Ambil ID channel di **Integrasi** → **Webchat** → ikon edit → bagian **Pasang**. Buka URL berikut di `WebView`:

```bash
https://app.csku.ai/webchat/<ID_CHANNEL>?embed=app
```

| Parameter | Wajib | Keterangan |
|---|---|---|
| `embed=app` | Ya | Mode aplikasi: layar penuh, langsung terbuka, menerima pesan dari aplikasi. |
| `header=0` | Tidak | Menyembunyikan header chat (nama, logo, tombol riwayat, tombol tutup). Pakai jika aplikasi punya toolbar sendiri. |
| `name`, `phone`, `email` | Tidak | Data user yang login, aturannya sama dengan [identify](#data-user-identify). Jika `name` dan `phone` valid, form pra-chat dilewati. Data tidak valid diabaikan. |
| `autostart=1` | Tidak | Sesi chat langsung dibuat saat halaman dibuka, tidak menunggu pesan pertama. Event `session` langsung terkirim. |

Parameter `header`, `name`, `phone`, `email`, dan `autostart` hanya berlaku bersama `embed=app`, dan nilainya harus persis seperti di tabel.

Cara tercepat: buka URL dengan data user, tanpa kode tambahan.

```kotlin
val url = Uri.parse("https://app.csku.ai/webchat/$CHANNEL_KEY").buildUpon()
    .appendQueryParameter("embed", "app")
    .appendQueryParameter("autostart", "1")
    .appendQueryParameter("name", user.name)
    .appendQueryParameter("phone", user.phone)
    .appendQueryParameter("email", user.email ?: "")
    .build()

webView.loadUrl(url.toString())
```

> **Catatan: Data di URL tercatat**
>
> Parameter URL tersimpan di riwayat dan log server seperti URL lainnya. Token chat tidak bisa dikirim lewat URL; kirim lewat `identify`.

## Setup WebView

Aktifkan JavaScript dan DOM storage (sesi chat disimpan di `localStorage`), daftarkan bridge bernama `CskuWebchatBridge`, lalu muat URL chat.

```kotlin
class SupportChatActivity : AppCompatActivity() {

    private lateinit var webView: WebView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        webView = WebView(this)
        setContentView(webView)

        webView.settings.apply {
            javaScriptEnabled = true
            domStorageEnabled = true
        }

        webView.addJavascriptInterface(ChatBridge(), "CskuWebchatBridge")
        webView.webViewClient = ChatWebViewClient()
        webView.webChromeClient = ChatChromeClient(this)

        webView.loadUrl("https://app.csku.ai/webchat/$CHANNEL_KEY?embed=app")
    }

    // Tombol back menutup chat, bukan halaman sebelumnya di WebView
    @Deprecated("Deprecated in Java")
    override fun onBackPressed() = finish()
}
```

## Data user (identify)

Kirim data user setelah `onPageFinished`. Jika data tiba sebelum chat selesai dimuat, datanya tetap dipakai.

```kotlin
private inner class ChatWebViewClient : WebViewClient() {

    override fun onPageFinished(view: WebView, url: String) {
        val user = Session.currentUser ?: return

        val payload = JSONObject()
            .put("name", user.name)
            .put("phone", user.phone)
            .put("email", user.email ?: "")
        // Token chat dari server Anda (event session); lewati jika belum ada
        user.chatToken?.let { payload.put("token", it) }

        postToChat(view, "identify", payload)
    }

    // Link di dalam pesan dibuka di browser, bukan di WebView chat
    override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
        val url = request.url
        if (url.host == "app.csku.ai") return false
        startActivity(Intent(Intent.ACTION_VIEW, url))
        return true
    }
}

fun postToChat(view: WebView, type: String, payload: JSONObject? = null) {
    val msg = JSONObject().put("source", "csku-webchat").put("type", type)
    if (payload != null) msg.put("payload", payload)
    view.evaluateJavascript("window.postMessage($msg, '*')", null)
}
```

| Field | Wajib | Aturan |
|---|---|---|
| `name` | Ya | 2–60 karakter. |
| `phone` | Ya | 8–15 digit, boleh diawali `+`. Spasi, `-`, `(`, `)`, dan `.` dibuang dulu. Contoh: `081234567890`, `+6281234567890`. |
| `email` | Tidak | Format email valid, maksimal 120 karakter. |
| `token` | Tidak | Token chat dari event `session`. 16–128 karakter: huruf, angka, `_`, `-`. Token salah format diabaikan. |

- Data valid: form pra-chat dilewati, dan tim CS melihat nama serta nomor ini di menu **Chat**.
- Data tidak valid: diabaikan, user melihat form pra-chat seperti biasa.
- Hanya `identify` valid pertama di setiap pemuatan halaman yang dipakai.
- Tanpa `token`: jika perangkat ini sudah pernah chat, profil yang tersimpan tidak ditimpa.
- Dengan `token`: chat di perangkat ini diganti dengan chat milik token tersebut, termasuk riwayatnya.

## Pesan dari aplikasi ke chat

Semua dikirim lewat `postToChat(webView, type)` dengan format `{"source":"csku-webchat","type":"...","payload":{...}}`.

| `type` | Payload | Fungsi |
|---|---|---|
| `identify` | `{ name, phone, email, token }` | Mengisi data user. |
| `open` | - | Menandai chat sedang dilihat. Jumlah belum dibaca direset ke 0. |
| `close` | - | Menandai chat tidak sedang dilihat. Pesan baru dihitung belum dibaca. |
| `history` | - | Membuka daftar riwayat percakapan. Hanya berlaku jika user punya lebih dari satu percakapan. Pakai dari toolbar aplikasi saat `header=0`. |

> **Tips: WebView di background**
>
> Jika WebView chat disimpan di background (misalnya di bottom sheet), kirim `close` saat disembunyikan dan `open` saat ditampilkan lagi, supaya badge belum dibaca akurat.

## Event dari chat ke aplikasi

Chat memanggil `CskuWebchatBridge.postMessage(json)` dengan string JSON `{"source":"csku-webchat","type":"...","payload":{...}}`.

```kotlin
private inner class ChatBridge {
    @JavascriptInterface
    fun postMessage(json: String) {
        val msg = runCatching { JSONObject(json) }.getOrNull() ?: return
        if (msg.optString("source") != "csku-webchat") return

        runOnUiThread {
            when (msg.optString("type")) {
                "ready" -> { /* halaman chat siap */ }
                "unread" -> updateBadge(msg.optJSONObject("payload")?.optInt("count") ?: 0)
                "close" -> finish() // user menekan tombol tutup di header chat
                "session" -> msg.optJSONObject("payload")?.optString("token")
                    ?.takeIf { it.isNotEmpty() }
                    ?.let { saveChatTokenToServer(it) }
            }
        }
    }
}
```

| `type` | Payload | Kapan dikirim |
|---|---|---|
| `ready` | - | Halaman chat sudah dimuat. |
| `unread` | `{ count }` (0–99) | Jumlah belum dibaca berubah. Bertambah hanya saat chat berstatus `close`. |
| `close` | - | User menekan tombol tutup di header, atau `Escape` di keyboard fisik. Aplikasi yang memutuskan apa yang ditutup. |
| `session` | `{ token }` | Setiap kali sesi chat dibuka atau dibuat. Hanya dikirim di mode aplikasi. |

Selain `session`, event tidak pernah membawa data user atau isi pesan. Tanpa bridge, chat tetap berjalan, tetapi tombol tutup di header tidak berfungsi. Daftarkan bridge atau pakai `header=0`.

## Token sesi

Token dari event `session` mengikat percakapan ke user. Simpan di server Anda untuk user yang login, lalu kirim lagi lewat `identify.token`. Dengan begitu riwayat chat user tetap muncul setelah instal ulang atau di HP lain.

1. Terima event `session`, kirim token ke server Anda bersama ID user yang login.
2. Saat user membuka chat, ambil token user dari server Anda.
3. Kirim token di field `token` pada `identify`.

Tanpa token, user yang sama di HP lain atau setelah instal ulang tercatat sebagai pengunjung baru.

> **Penting: Perlakukan token seperti password**
>
> Siapa pun yang memegang token bisa membaca dan mengirim pesan di percakapan user tersebut. Simpan hanya di server Anda, berikan hanya ke user yang login sebagai pemiliknya, dan jangan pernah menulisnya ke log.

## Kirim gambar dan PDF

User bisa mengirim JPG, PNG, WEBP, GIF, dan PDF hingga 5 MB. WebView butuh `WebChromeClient` yang membuka pemilih file:

```kotlin
class ChatChromeClient(private val activity: ComponentActivity) : WebChromeClient() {

    private var callback: ValueCallback<Array<Uri>>? = null

    private val picker = activity.registerForActivityResult(
        ActivityResultContracts.StartActivityForResult()
    ) { result ->
        callback?.onReceiveValue(FileChooserParams.parseResult(result.resultCode, result.data))
        callback = null
    }

    override fun onShowFileChooser(
        view: WebView, filePathCallback: ValueCallback<Array<Uri>>, params: FileChooserParams
    ): Boolean {
        callback?.onReceiveValue(null)
        callback = filePathCallback
        picker.launch(params.createIntent())
        return true
    }
}
```

Buat `ChatChromeClient` di `onCreate`, sebelum Activity `STARTED`, karena memakai `registerForActivityResult`.

## Logout dan ganti akun

Sesi chat disimpan di penyimpanan WebView dan berlaku untuk seluruh aplikasi. Jika user A logout lalu user B login di HP yang sama tanpa membersihkan penyimpanan, B melihat percakapan A. Saat logout, panggil:

```kotlin
WebStorage.getInstance().deleteAllData()
CookieManager.getInstance().removeAllCookies(null)
```

Jika WebView juga dipakai untuk halaman lain yang datanya tidak boleh ikut terhapus, jalankan chat di proses terpisah dengan `WebView.setDataDirectorySuffix("csku-chat")` (Android 9+), lalu hapus direktori data itu saat logout.

## Layar penuh (edge-to-edge)

Halaman chat otomatis memberi jarak untuk status bar, navigation bar, dan notch. Beberapa versi WebView lama tidak meneruskan jarak ini. Jika header tertutup status bar atau kotak ketik tertutup navigation bar (Android 15 / targetSdk 35 memaksa edge-to-edge), beri padding di native:

```kotlin
ViewCompat.setOnApplyWindowInsetsListener(webView) { v, insets ->
    val bars = insets.getInsets(WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.ime())
    v.setPadding(bars.left, bars.top, bars.right, bars.bottom)
    WindowInsetsCompat.CONSUMED
}
```

Padding ini tidak membuat jarak dobel. Pakai `android:windowSoftInputMode="adjustResize"` pada Activity supaya kotak ketik tetap terlihat saat keyboard muncul.

## Keamanan dan batasan

> **Peringatan: Identitas tidak diverifikasi**
>
> Nama dan nomor dari aplikasi tidak diverifikasi oleh CSKU. Siapa pun yang membuka URL chat bisa mengirim nomor lain. Gunakan sebagai info bantu untuk tim CS, bukan bukti identitas. Jangan membuka data sensitif (saldo, pesanan, data akun) hanya berdasarkan nomor yang tampil di chat.

- Pengunjung baru melewati pemeriksaan anti-spam otomatis saat memulai chat. WebView harus bisa memuat `challenges.cloudflare.com`.
- Satu pesan maksimal 2000 karakter.
- Tampilan chat berbahasa Indonesia dan bertema terang.

## Checklist uji

1. Login, buka chat: form pra-chat tidak muncul. Kirim pesan, cek nama dan nomor di menu **Chat** dashboard.
2. Nomor salah format (misalnya `12345`): form pra-chat muncul.
3. Tutup chat lalu buka lagi: riwayat pesan masih ada.
4. Kirim `close`, lalu balas dari dashboard: event `unread` masuk dengan `count` bertambah.
5. Tombol tutup di header menutup Activity, atau `header=0` dan toolbar aplikasi tampil.
6. Kirim gambar dan PDF.
7. Ketuk link di pesan: terbuka di browser.
8. Logout lalu login akun lain: chat mulai kosong.
9. Event `session` masuk dan token tersimpan di server. Login akun yang sama di HP lain: riwayat chat muncul.
10. HP dengan gesture navigation dan notch: header dan kotak ketik tidak tertutup.

## Troubleshooting

| Gejala | Solusi |
|---|---|
| Form pra-chat tetap muncul | Pastikan URL memakai `?embed=app`. Cek nama minimal 2 karakter dan nomor 8–15 digit. Kirim `identify` di `onPageFinished`. |
| Nama lama tampil setelah ganti akun | Hapus penyimpanan WebView saat logout. |
| Tombol tutup tidak berfungsi | Daftarkan `CskuWebchatBridge` atau pakai `header=0`. |
| Tombol lampiran tidak membuka galeri | Implementasikan `onShowFileChooser`. |
| Muncul "Verifikasi keamanan gagal" | Izinkan `challenges.cloudflare.com` di jaringan atau network security config. |
| Halaman kosong | Aktifkan JavaScript dan DOM storage. Cek ID channel di dashboard. |

---

Sumber: https://docs.csku.ai/waba/proxy

# Proxy WhatsApp API (WABA)

> Kirim pesan teks, template, dan media lewat WhatsApp Cloud API Meta memakai kredensial CSKU, dengan pesan terkirim tercatat di inbox.


Proxy WABA meneruskan request Anda ke WhatsApp Cloud API Meta memakai nomor WhatsApp API yang sudah terhubung di CSKU. Anda tidak perlu menyimpan access token Meta di sistem Anda. Body request memakai format Meta apa adanya, dan pesan yang berhasil terkirim ikut tercatat di menu **Chat**.

## Kapan dipakai

| Kebutuhan | Pakai |
|---|---|
| Membalas percakapan yang sudah ada di CSKU, di channel apa pun | [Kirim pesan](https://docs.csku.ai/api/kirim-pesan) (`POST /v1/message`) |
| Mengirim pesan template WhatsApp (notifikasi, OTP, pengingat) ke nomor mana pun | Proxy WABA |
| Memakai fitur Cloud API Meta secara langsung, dengan format body Meta | Proxy WABA |

Proxy hanya berlaku untuk channel **WhatsApp API (Token manual)** dan **WhatsApp API (Login Meta)**.

## Base URL

```bash
https://api.csku.ai/v1/waba/{channel_merchant_id}
```

`{channel_merchant_id}` adalah ID channel WhatsApp API Anda, tampil di daftar channel pada **Integrasi** → **WhatsApp API**. Channel harus milik bisnis yang sama dengan kredensial dan berstatus aktif.

## Autentikasi

Pakai **Business ID** (**Pengaturan** → **Informasi Bisnis**) dan **Secret Key** (**Pengaturan** → **Secret Key**). Pilih salah satu cara.

**Header terpisah:**

```http
Business: <BUSINESS_ID>
Secret: <SECRET_KEY>
```

**Bearer token**, berisi base64 dari `BUSINESS_ID|SECRET_KEY`:

```bash
TOKEN=$(printf '%s|%s' "$BUSINESS_ID" "$SECRET_KEY" | base64 | tr -d '\n')
```

```http
Authorization: Bearer <TOKEN>
```

> **Peringatan: Pemisahnya pipa, bukan titik dua**
>
> Proxy WABA memakai `|` di antara Business ID dan Secret Key. Ini berbeda dari Public API utama yang memakai `:`. Lihat [Autentikasi](https://docs.csku.ai/api/autentikasi).

Jika header `Secret` diisi, header `Authorization` diabaikan. **WABA API Key** dari dashboard (berawalan `csku_waba_`) tidak berlaku untuk endpoint ini. Jangan bagikan Secret Key dan jangan menaruhnya di kode aplikasi mobile atau browser.

## Kirim pesan teks

`POST /messages/text`

Body diteruskan tanpa diubah ke `https://graph.facebook.com/v20.0/{phone_number_id}/messages`, jadi formatnya mengikuti [dokumentasi Cloud API Meta](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages).

```bash
curl -X POST "https://api.csku.ai/v1/waba/$CHANNEL_ID/messages/text" \
  -H "Business: $BUSINESS_ID" \
  -H "Secret: $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "6281234567890",
    "type": "text",
    "text": { "body": "Halo, pesanan Anda sudah dikirim." }
  }'
```

Respons sukses adalah respons Meta apa adanya:

```json
{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "6281234567890", "wa_id": "6281234567890" }],
  "messages": [{ "id": "wamid.HBgM..." }]
}
```

> **Catatan: Aturan 24 jam**
>
> Pesan bebas (teks, gambar, dokumen) hanya bisa dikirim dalam 24 jam sejak pesan terakhir pelanggan. Di luar jendela itu, Meta menolak pesan dan Anda harus memakai template yang sudah disetujui.

## Kirim pesan template

`POST /messages/template`

Template harus sudah disetujui Meta. Isi `components` sesuai variabel di template Anda.

```bash
curl -X POST "https://api.csku.ai/v1/waba/$CHANNEL_ID/messages/template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "6281234567890",
    "type": "template",
    "template": {
      "name": "order_shipped",
      "language": { "code": "id" },
      "components": [
        {
          "type": "header",
          "parameters": [
            { "type": "image", "image": { "link": "https://example.com/paket.jpg" } }
          ]
        },
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Budi" },
            { "type": "text", "text": "INV-1024" }
          ]
        }
      ]
    }
  }'
```

Daftar template lewat `GET /templates` belum stabil. Lihat nama dan isi template di dashboard atau di Meta Business Manager.

## Upload media

`POST /media`

Unggah file lewat multipart dengan field `file`. CSKU meneruskannya ke Meta dan mengembalikan ID media.

```bash
curl -X POST "https://api.csku.ai/v1/waba/$CHANNEL_ID/media" \
  -H "Business: $BUSINESS_ID" \
  -H "Secret: $SECRET_KEY" \
  -F "file=@invoice.pdf;type=application/pdf"
```

```json
{ "id": "1234567890123456" }
```

Sertakan tipe file (`type=...`) agar Meta mengenali formatnya. Pakai ID ini di body pesan, misalnya di `/messages/text`:

```json
{
  "messaging_product": "whatsapp",
  "to": "6281234567890",
  "type": "document",
  "document": { "id": "1234567890123456", "filename": "invoice.pdf", "caption": "Invoice Anda" }
}
```

## Pesan di inbox

Setiap pesan yang diterima Meta (status di bawah 400) dicatat sebagai pesan agen di percakapan nomor tujuan di menu **Chat**. Jika belum ada percakapan, CSKU membuat percakapan baru. Isi yang tercatat:

- Teks: isi `text.body`.
- Template: isi body template dengan variabel terisi, atau nama template jika isinya tidak bisa diambil.
- Gambar, video, dokumen: `link` dan `caption`. Media yang dikirim dengan `id` tercatat tanpa link.

Pencatatan berjalan setelah respons dikirim, jadi pesan bisa muncul di inbox beberapa detik kemudian.

## Error

Ada dua sumber error, dibedakan oleh `error.source`.

**Error dari CSKU**, dengan HTTP status sesuai kode:

```json
{
  "error": {
    "source": "csku",
    "code": "unauthorized",
    "message": "unauthorized"
  }
}
```

| `code` | HTTP | Penyebab |
|---|---|---|
| `unauthorized` | 401 | Business ID atau Secret Key kosong atau salah. |
| `permission_denied` | 403 | Channel bukan milik bisnis ini. |
| `channel_disabled` | 403 | Channel tidak aktif. |
| `channel_not_found` | 404 | `channel_merchant_id` tidak ditemukan. |
| `invalid_request` | 400 | Body kosong, atau field `file` tidak ada di upload media. |
| `internal_error` | 500 | Konfigurasi channel tidak lengkap atau Meta tidak bisa dihubungi. |

**Error dari Meta**, dengan HTTP status dari Meta. `meta_error` berisi respons error Meta apa adanya:

```json
{
  "error": {
    "source": "meta",
    "meta_error": {
      "error": {
        "message": "(#131047) Re-engagement message",
        "type": "OAuthException",
        "code": 131047,
        "fbtrace_id": "A1b2C3..."
      }
    }
  }
}
```

Arti kode error Meta ada di [dokumentasi error Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes). Kode `131047` berarti jendela 24 jam sudah lewat; kirim template.

## Batasan

- Body tidak divalidasi oleh CSKU. Format salah dikembalikan sebagai error Meta.
- Request ke Meta dibatasi 30 detik. Jika lewat, Anda menerima `internal_error`.
- Batas ukuran media, rate limit, dan aturan template mengikuti ketentuan Meta untuk nomor Anda.
- Proxy hanya untuk mengirim pesan dan upload media. Balasan pelanggan masuk ke menu **Chat** seperti channel lainnya.

---

Sumber: https://docs.csku.ai/llms

# Docs untuk AI (llms.txt)

> Berikan dokumentasi CSKU ke ChatGPT, Claude, Cursor, atau asisten AI lain dalam format yang mudah dibaca mesin.


Seluruh dokumentasi ini juga tersedia sebagai markdown biasa. Pakai saat meminta asisten AI membantu menulis integrasi CSKU, supaya jawabannya mengikuti perilaku API yang sebenarnya.

## File yang tersedia

| URL | Isi |
|---|---|
| [`/llms.txt`](https://docs.csku.ai/llms.txt) | Daftar semua halaman dengan ringkasan satu kalimat, plus fakta penting integrasi. Format [llmstxt.org](https://llmstxt.org) |
| [`/llms-full.txt`](https://docs.csku.ai/llms-full.txt) | Seluruh dokumentasi dalam satu file markdown |
| `/<halaman>.md` | Markdown satu halaman, misalnya [`/api/kirim-pesan.md`](https://docs.csku.ai/api/kirim-pesan.md) |

Semua file dibuat otomatis dari konten yang sama dengan situs ini, jadi selalu sinkron.

## Cara pakai

### ChatGPT, Claude, Gemini

Tempel link ini di awal percakapan:

```text
Baca dokumentasi https://docs.csku.ai/llms-full.txt lalu bantu saya membuat penerima webhook CSKU di Node.js.
```

Jika asisten tidak bisa membuka link, buka file-nya, salin semua isinya, lalu tempel ke chat.

### Satu halaman saja

Di setiap halaman docs ada tombol **Salin** di kanan atas untuk menyalin markdown halaman itu, dan tombol **Markdown** untuk membukanya. Cocok jika Anda hanya butuh satu topik, misalnya [Event & payload](https://docs.csku.ai/webhook/event).

### Cursor dan editor AI lain

Tambahkan `https://docs.csku.ai/llms-full.txt` sebagai sumber dokumentasi (fitur **Docs** di Cursor), atau tempel isi file-nya ke file aturan proyek Anda.

> **Peringatan: Jangan tempel Secret Key ke AI**
>
> Berikan dokumentasi, bukan kredensial. Ganti nilai `Secret` dan Business ID dengan placeholder saat meminta bantuan menulis kode.

---

Sumber: https://docs.csku.ai/changelog

# Changelog

> Perubahan penting di CSKU yang berpengaruh ke integrasi dan pemakaian.


## Oktober 2026

- **Dokumentasi baru.** Docs disusun ulang mengikuti tampilan dashboard dan dicek langsung dengan kode backend.
- **Aplikasi mobile CSKU** untuk agent: balas chat, catatan internal, template WhatsApp, performa, dan notifikasi pesan masuk. Lihat [Aplikasi mobile](https://docs.csku.ai/panduan/aplikasi-mobile).
- **Webchat di aplikasi Android** lewat mode `embed=app`: data user dari aplikasi, header bisa disembunyikan, dan sesi chat bisa dipulihkan. Lihat [Integrasi Android](https://docs.csku.ai/webchat/android).
- **Performa Saya** di dashboard untuk anggota tim. Anggota tanpa akses menu Analitik hanya melihat data miliknya.
- **Notifikasi pesan masuk** di browser, bisa dinyalakan atau dimatikan di Pengaturan → Notifikasi.