Ringkasan

Quickchat AI menyediakan REST API untuk mengakses konfigurasi Agen AI, Basis Pengetahuan, Percakapan, Tindakan AI, dan lainnya secara terprogram.

Pemeriksaan contoh opsional

• Bandingkan metode penerapan. Periksa kanal, akses situs web, dan fitur yang Anda nyatakan terhadap pilihan penyiapan Quickchat AI. Alat ini tidak memeriksa situs web atau akun Anda.

• Periksa contoh koneksi MCP. Inisialisasi dan tampilkan alat hanya pada endpoint dokumentasi Cloudflare atau Microsoft Learn. Tidak ada proses masuk atau pelaksanaan alat.

Autentikasi

Seluruh endpoint API menggunakan autentikasi token Bearer. Sertakan token API dalam header Authorization pada setiap permintaan:

Authorization: Bearer <API_TOKEN>

Token dibuat di Dasbor Quickchat dalam Aplikasi Eksternal > API. Setiap token adalah JWT yang berisi scenario_id, sehingga tidak diperlukan header pengenal tambahan.

• Masa berlaku token: 52 minggu sejak dibuat
• Token dapat dicabut kapan saja melalui Dasbor
• Setiap token berlaku untuk satu Agen AI (skenario)
• Pembuatan token memerlukan paket Business atau lebih tinggi; pada paket lebih rendah, pilihan ini dinonaktifkan dan endpoint mengembalikan 402 Payment Required

Catatan

Endpoint Chat waktu nyata (POST https://app.quickchat.ai/chat) menerima token Bearer yang sama dengan API lainnya, tetapi berada di luar jalur dasar /v1/api/ dan memerlukan scenario_id dalam isi permintaan. Lihat halaman Chat untuk referensi lengkap.

Cakupan Token

Token API dibuat dengan salah satu dari dua cakupan:

Cakupan	Tingkat Akses	Deskripsi
read_all	Hanya baca	Dapat membaca semua sumber daya, tetapi tidak dapat membuat, memperbarui, atau menghapus
write_all	Baca dan Tulis	Akses penuh ke seluruh endpoint, termasuk operasi penulisan

• Cakupan token ditetapkan saat dibuat di Dasbor dalam Aplikasi Eksternal > API
• Cakupan write_all otomatis mencakup seluruh izin read_all
• Menggunakan token read_all pada endpoint penulisan mengembalikan 403 dengan "Insufficient token scope. Required: write_all"

Tips

Gunakan token read_all untuk pemantauan, analitik, dan integrasi hanya baca. Gunakan token write_all hanya jika integrasi perlu membuat atau mengubah sumber daya.

Persyaratan cakupan menurut kelompok endpoint:

Kelompok Endpoint	Operasi Baca	Operasi Tulis
Pengaturan Chatbot	read_all	write_all
Pengaturan Basis Pengetahuan	read_all	write_all
Artikel	read_all	write_all
URL Bahasa Artikel	read_all	write_all
Tag	read_all	Tidak ada
Unggah File	Tidak ada	write_all
Impor Konten Eksternal	Tidak ada	write_all
Basis Pengetahuan Intercom	read_all	write_all
Konfigurasi Widget	read_all	write_all
Percakapan	read_all	Tidak ada
Metadata Percakapan	read_all	write_all
Konfigurasi Pengalihan	read_all	write_all
Penilaian Percakapan	read_all	write_all
Tindakan AI	read_all	write_all

URL Dasar

Kelompok Endpoint	URL Dasar
Basis Pengetahuan, Tindakan AI, Unggah File, Impor, Pengaturan Chatbot, Widget, Pengalihan, Penilaian Percakapan	https://app.quickchat.ai/v1/api/
Percakapan	https://app.quickchat.ai/v1/api_core/
Chat Waktu Nyata	https://app.quickchat.ai/chat

Batas Permintaan

Batas permintaan diterapkan per token dan per endpoint.

Tingkat	Batas	Berlaku Untuk
READ	120 permintaan/menit	GET dan operasi daftar
WRITE	60 permintaan/menit	POST, PATCH, PUT, DELETE
HEAVY	20 permintaan/menit	Unggah file, impor, pengambilan konten web

Saat batas permintaan terlampaui, API mengembalikan HTTP 429 Too Many Requests.

Webhook

Quickchat AI tidak mengirim webhook keluar. Tidak tersedia cara berlangganan peristiwa agar kami melakukan POST ke endpoint Anda saat pesan masuk, percakapan dialihkan, atau percakapan ditutup.

Alternatif yang tersedia memiliki tujuan berbeda:

• Tindakan AI memanggil API Anda selama percakapan. Tindakan API menyediakan mode AI yang memutuskan, Sebelum balasan pertama, dan Saat metadata cocok. Mode otomatis mencoba panggilan sekali per percakapan sesuai kondisi yang didokumentasikan, bukan berlangganan setiap pesan atau pengalihan. Gunakan untuk tugas seperti mencatat prospek atau memberi tahu sistem Anda ketika data yang diperlukan tersedia.
• Google Sheets menambahkan baris ketika Tindakannya berjalan. Fitur ini tidak otomatis mencatat setiap pesan atau pengalihan.
• Polling API Percakapan mengambil percakapan tersimpan beserta peristiwanya, termasuk pesan dan penanda pengalihan yang tercatat. Ikuti paginasi dan batas permintaan READ di atas. Polling menimbulkan jeda; membandingkan status percakapan antar-polling dapat melewatkan perubahan di antaranya. Jangan menganggapnya sebagai riwayat lengkap setiap perubahan pengalihan atau penugasan.

Akses API memerlukan paket Business; lihat Paket dan batas.

Paginasi

Endpoint daftar mendukung paginasi melalui parameter kueri:

Parameter	Deskripsi
limit integer	Jumlah item per halaman
offset integer	Jumlah item yang dilewati

Respons dengan paginasi mengikuti struktur ini:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Penanganan Kesalahan

Seluruh kesalahan dikembalikan sebagai JSON dalam format berikut:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Status	Kode	Deskripsi
400	BAD_REQUEST	Input tidak valid atau kolom wajib tidak ada
401	PERMISSION_DENIED	Token tidak valid, kedaluwarsa, atau dicabut
402	PAYMENT_REQUIRED	Memerlukan langganan aktif
403	PERMISSION_DENIED	Token tidak memiliki cakupan yang diperlukan untuk operasi ini
404	NOT_FOUND	Sumber daya tidak ditemukan
409	CONFLICT	Operasi bertentangan (misalnya perubahan bersamaan)
422	VALIDATION_ERROR	Isi permintaan gagal divalidasi terhadap skema
429	TOO_MANY_REQUESTS	Batas permintaan terlampaui
500	UNKNOWN	Kesalahan server internal
503	SERVICE_UNAVAILABLE	Layanan sementara tidak tersedia

---