Metadata Percakapan

Metadata Percakapan memungkinkan Anda melampirkan data kunci-nilai kustom ke percakapan, menghubungkan sistem Anda dengan Agen AI. Metadata mengalir melalui seluruh alur kerja Quickchat:

• Masukkan melalui API: gunakan endpoint ini untuk melampirkan metadata ke percakapan secara terprogram (misalnya dari CRM, helpdesk, atau backend)
• Masukkan melalui widget/sematan: kirim metadata sebagai parameter inisialisasi saat memuat widget, atau masukkan secara dinamis selama percakapan aktif menggunakan SDK JavaScript
• Terlihat di Dasbor: metadata kustom muncul dalam detail percakapan Kotak Masuk. Kunci internal difilter, sedangkan detail kontak yang dikumpulkan dan memori Tindakan memiliki tampilan tersendiri
• Disertakan dalam ekspor: metadata disertakan saat Anda mengekspor percakapan dari Dasbor, sehingga tersedia untuk analisis offline
• Digunakan dalam Tindakan AI: nilai metadata dapat langsung dimasukkan sebagai placeholder {{metadata_<key>}} dalam Tindakan AI. Lihat Variabel Tindakan AI untuk referensi lengkap placeholder yang tersedia
• Tersedia bagi Agen AI jika diizinkan: konteks model menggunakan sebagian metadata yang telah difilter. Menyimpan kunci tidak menjamin model akan menerima atau menyebutkannya

Gunakan metadata untuk referensi pelanggan, konteks akun, analitik, dan input Tindakan. Penyimpanan, tampilan Kotak Masuk, substitusi Tindakan, dan konteks model merupakan penggunaan terpisah atas data yang sama.

Metadata divalidasi terhadap skema JSON jika skema dikonfigurasi di Dasbor.

Pemeriksaan contoh opsional

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

• Periksa kondisi pelaksanaan Tindakan. Evaluasi kondisi terhadap contoh metadata yang diberikan tanpa menjalankan Tindakan.

Pada browser yang kompatibel, pemeriksaan ini juga tersedia sebagai alat situs. Tautan membuka formulir standar.

Konteks model dan otorisasi

Pada kanal yang dikendalikan pengunjung, seperti Widget situs web dan Sematan, konteks model menerima kunci kontak pengunjung (visitor_name, visitor_email, visitor_phone_number) serta kunci yang memenuhi syarat dan dirujuk atau dikumpulkan Tindakan aktif. Nilai internal dan yang dicadangkan difilter; batas konfigurasi dan ukuran juga berlaku. Integrasi lain memiliki aturan konteks khusus kanal. Kunci kustom customer_tier atau customer_id tidak otomatis terlihat oleh model hanya karena Anda mengirimkannya.

Tindakan dapat mengganti {{metadata_<key>}} saat menyusun permintaan tanpa meminta AI menghasilkan nilai tersebut. Hal ini tidak membuat metadata biasa menjadi rahasia: nilai yang memenuhi syarat dapat masuk ke konteks model secara terpisah atau muncul dalam respons Tindakan. Jangan simpan kunci API atau kata sandi dalam metadata kustom.

Metadata dari browser bukan bukti identitas atau izin. Layanan penerima harus mengautentikasi dan mengotorisasi akses ke data pribadi; ID pelanggan atau tingkat paket yang dikirim browser tidak cukup. Uji permintaan Tindakan yang dihasilkan serta jawaban Agen untuk konfigurasi Anda.

Mengambil Metadata

Cakupan: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Respons 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

Menetapkan Metadata

Buat atau perbarui metadata percakapan.

Cakupan: write_all

POST https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Isi Permintaan

Parameter	Deskripsi
metadata object, wajib	Metadata kunci-nilai yang akan disimpan

Shell

curl -X POST https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "metadata": {"ticket_id": "T-1234", "priority": "high"}
    },
)
data = response.json()

Respons 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

---