Chat

Pemeriksaan contoh opsional

• Pratinjau permintaan Tindakan API. Render templat permintaan yang diberikan dengan nilai contoh sintetis tanpa mengirimkannya. Jangan sertakan header kredensial.

• Pratinjau kunci metadata. Periksa bagaimana nama bidang yang diberikan menjadi kunci variabel, termasuk nama duplikat dan kesalahan kunci yang dicadangkan. Pemeriksaan ini tidak meninjau nilai atau izin khusus akun.

Chat

Endpoint Chat realtime mengirim pesan pengunjung ke Agen AI Anda dan mengembalikan balasan AI dalam satu siklus permintaan dan respons. Gunakan endpoint ini saat membuat antarmuka chat khusus di atas Quickchat AI.

Ada dua perbedaan dengan endpoint lainnya: endpoint ini berada di app.quickchat.ai/chat, di luar jalur dasar /v1/api/ dan /v1/api_core/, serta membaca scenario_id dari isi permintaan, bukan dari token. Autentikasinya menggunakan token Bearer yang sama dengan endpoint API lainnya.

Catatan

Kirim setiap permintaan ke https://app.quickchat.ai/chat. Nilai scenario_id dalam isi permintaan harus cocok dengan Agen AI yang terikat pada token Bearer Anda.

Kirim Pesan

POST https://app.quickchat.ai/chat

Isi Permintaan

Parameter	Deskripsi
scenario_id string, wajib	ID Agen AI Anda. Harus cocok dengan scenario_id yang terikat pada token Bearer
text string, wajib	Pesan masukan pengguna
conv_id string	ID percakapan. Jangan sertakan pada permintaan pertama untuk memulai percakapan baru, lalu kirim kembali conv_id yang diterima pada permintaan berikutnya untuk melanjutkannya
client_metadata object	Pasangan kunci-nilai khusus (kami menyarankan maksimal 5 kunci) yang dilampirkan pada setiap pesan. Ditampilkan sebagai kolom data dalam ekspor percakapan di Kotak Masuk

Permintaan tanpa conv_id memulai percakapan baru, dan conv_id yang dibuat dikembalikan dalam respons. Simpan conv_id tersebut dan kirim kembali pada permintaan berikutnya untuk mempertahankan konteks percakapan selama beberapa interaksi pengguna.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

Respons 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

Bidang	Deskripsi
conv_id string	Pengenal percakapan. Selalu dikembalikan. Kirim kembali dalam bidang conv_id di isi permintaan untuk melanjutkan percakapan
reply string	Respons Agen AI. Dapat berisi HTML seperti pemisah baris <br>
ord_number integer	Nomor urut pesan dalam percakapan
src integer	Penanda sumber internal. Klien API dapat mengabaikan bidang ini

Untuk melanjutkan percakapan yang ada, kirim kembali conv_id yang Anda terima:

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

Metadata Klien

Endpoint Chat menerima parameter opsional client_metadata: atribut khusus yang ditetapkan pada setiap pesan baru dan ditampilkan sebagai kolom data dalam ekspor percakapan di Kotak Masuk. Anda juga dapat melampirkan atribut yang sama melalui widget. Kami menyarankan pengiriman maksimal 5 kunci sekaligus, misalnya {"userId": 12, "website": "mywebsite.com"}. Ini adalah panduan, bukan batas yang diterapkan API.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

Pemfilteran Tag Basis Pengetahuan

Anda dapat menambahkan tag ke artikel Basis Pengetahuan dan menggunakannya untuk membatasi artikel yang dipakai AI, sehingga jawaban hanya didasarkan pada sebagian Basis Pengetahuan. Pemfilteran ini saat ini hanya didukung melalui API.

Untuk memfilter berdasarkan tag, tambahkan kunci kb_topic ke client_metadata. Kunci kb_topic harus ada dalam setiap permintaan dalam percakapan, termasuk permintaan yang memulainya. Nilainya dapat berubah antarpermintaan, tetapi kuncinya harus selalu ada agar filter diterapkan.

Dalam contoh di bawah, setiap artikel dengan tag your-topic, atau tanpa tag sama sekali, disertakan dalam kumpulan pengetahuan yang dapat digunakan untuk respons.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

Kesalahan

Endpoint Chat mengembalikan pesan kesalahan teks biasa dengan kode status HTTP yang sesuai.

Status	Deskripsi	Tindakan
400	scenario_id tidak ada atau kredensial tidak diberikan	Sertakan scenario_id dalam isi permintaan dan header Authorization: Bearer <API_TOKEN> yang valid
400	conv_id tidak valid (Conversation conv_id <id> is not valid.)	Jangan sertakan conv_id untuk memulai percakapan baru, atau berikan conv_id dari respons sebelumnya
401	Kredensial tidak valid (Unauthorized.)	Pastikan token Bearer atau kunci API Anda valid untuk scenario_id ini
404	scenario_id tidak dikenal (No implementation found for scenario_id <id>)	Periksa scenario_id dan pastikan token Bearer Anda terikat padanya
500	Kesalahan server internal	Ada masalah di pihak kami. Silakan hubungi dukungan
503	Layanan tidak tersedia	Server sedang kelebihan beban sementara atau dalam pemeliharaan. Jika masalah berlanjut, silakan hubungi dukungan