Variabel Tindakan AI

Di mana pun Anda dapat mengetik nilai dalam Tindakan API (URL, header, isi, atau parameter kueri), Anda dapat memasukkan nilai dinamis menggunakan sintaks {{...}}. Quickchat mengganti placeholder ini saat permintaan dibuat, tepat sebelum memanggil endpoint Anda.

Klik tombol + Tambah Data AI di sebelah bidang nilai untuk menelusuri semua variabel yang tersedia dalam skenario saat ini.

Tombol + Tambah Data AI tersedia di sebelah setiap bidang nilai: URL endpoint, setiap nilai header, bidang isi, dan parameter kueri.

Tool penyiapan 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.

Tiga kategori variabel

Kategori	Sintaks	Kapan diisi
Parameter AI. Nilai yang diekstrak Agen AI dari percakapan. Anda menentukannya di bagian Parameter setiap Tindakan.	{{order_number}}, {{customer_email}}	Agen AI mengisinya saat pemanggilan, berdasarkan aturan dalam deskripsi setiap parameter.
Variabel bawaan. Konteks percakapan yang dimasukkan Quickchat secara otomatis.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Selalu tersedia. Quickchat menggantinya pada setiap permintaan.
Metadata percakapan. Pasangan kunci-nilai khusus yang dilampirkan pada percakapan.	{{metadata_<key>}}	Ketika kunci terkait ada dalam percakapan (ditetapkan oleh widget, integrasi saluran, Pengumpulan Data Cerdas, atau API).

Tips

Setiap variabel dirender sebagai label berbentuk pil berwarna dalam editor. Biru berarti parameter AI atau variabel bawaan. Oranye berarti variabel metadata atau token sistem. Merah berarti namanya tidak cocok dengan apa pun yang dikenali Quickchat (biasanya salah ketik).

Dropdown ”+ Tambah Data AI”

Dropdown mencantumkan setiap variabel yang tersedia untuk skenario saat ini, dikelompokkan menjadi lima bagian:

1. Parameter: parameter AI yang Anda tentukan pada Tindakan ini.
2. Pengunjung: empat kunci metadata yang dicatat otomatis untuk setiap pengunjung ketika salurannya menyediakannya.
3. Metadata (digunakan dalam percakapan terbaru): kunci metadata khusus yang ditemukan dalam 20 percakapan terakhir skenario ini, dengan contoh nilai untuk masing-masing.
4. Bawaan: tujuh variabel percakapan yang selalu tersedia, dengan nilai saat ini atau contoh yang ditampilkan langsung.
5. Token Sistem: kredensial yang disediakan integrasi terhubung (misalnya HubSpot, Telegram). Hanya muncul jika integrasi terhubung. Lihat Token Sistem di bawah.

Dropdown mengelompokkan variabel ke dalam beberapa bagian. Baris Bawaan menunjukkan nilai saat ini ketika sudah diketahui (scenario_id) dan contoh e.g. … untuk sisanya. Kelompok Metadata (digunakan dalam percakapan terbaru) dibuat ulang per skenario dari percakapan nyata terbaru. Bagian Token Sistem (tidak ditampilkan di sini) hanya muncul ketika suatu integrasi terhubung.

Catatan

Daftar Metadata (digunakan dalam percakapan terbaru) dibuat ulang dari 20 percakapan terbaru skenario dan disimpan dalam cache selama 5 menit per Agen AI. Kunci metadata yang ditetapkan pada percakapan baru dapat memerlukan hingga 5 menit untuk muncul di bagian ini. Anda selalu dapat mengetik {{metadata_<your_key>}} secara langsung: Quickchat tidak mensyaratkan kunci muncul di dropdown agar penggantian berfungsi.

Variabel bawaan

Ketujuh variabel ini selalu tersedia. Dropdown + Tambah Data AI menampilkan nilai saat ini (jika sudah diketahui) atau contoh nilai di sebelah setiap baris.

Variabel	Contoh	Artinya
{{scenario_id}}	abc123xyz	ID Agen AI yang memiliki percakapan.
{{conversation_id}}	conv-d8a8…	Pengenal unik percakapan.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Tautan Kotak Masuk langsung ke percakapan ini.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Saluran tempat percakapan berlangsung.
{{current_timestamp}}	2026-09-02T12:00:00+00:00	Tanggal dan waktu UTC saat ini dalam format ISO 8601.
{{language}}	en, nl, de, fr, …	Kode ISO 639-1 huruf kecil untuk bahasa percakapan.
{{country}}	US, GB, NL, DE, …	Kode negara ISO 3166-1 alpha-2 huruf besar.

Beberapa catatan yang perlu diketahui:

• {{scenario_id}} juga terlihat pada URL browser saat mengedit Tindakan. Dropdown + Tambah Data AI menunjukkan ID sebenarnya untuk skenario yang sedang diedit, bukan contoh.
• {{conversation_url}} berguna untuk memposting tautan yang dapat diklik ke Slack, Jira, atau tool lain yang memerlukan akses langsung kembali ke Kotak Masuk.
• {{language}} ditentukan dari (secara berurutan): prefiks URL halaman (untuk Shopify Markets), metadata percakapan, lalu bahasa yang dikonfigurasi untuk Agen AI.
• {{country}} ditentukan dari (secara berurutan): prefiks URL halaman, TLD host URL, lalu fallback bahasa ke negara.

Metadata percakapan

Prefiks metadata_ wajib digunakan. Quickchat mencari <key> dalam metadata percakapan dan memasukkan nilainya ke permintaan.

{{metadata_order_id}}      →   ord_8a4f3…
{{metadata_customer_tier}} →   gold

Kunci metadata pengunjung

Keempat kunci ini menjelaskan sesi pengunjung dan memiliki bagian Pengunjung sendiri dalam dropdown. Nilainya dapat dicatat oleh saluran, integrasi, widget/embed, API, Pengumpulan Data Cerdas, atau pemetaan masukan Tindakan yang dikonfigurasi.

Variabel	Dicatat otomatis oleh
{{metadata_fullPathURL}}	Widget situs web, embed situs web, atau integrasi saluran chat yang menyertakan widget sendiri (HubSpot, Intercom, dan lainnya).
{{metadata_visitor_name}}	Profil saluran chat (Telegram, Slack, dan lainnya), integrasi saluran, Pengumpulan Data Cerdas, pemetaan masukan Tindakan yang dikonfigurasi, widget/embed Anda, atau API Quickchat.
{{metadata_visitor_email}}	Profil saluran chat, integrasi saluran, Pengumpulan Data Cerdas, pemetaan masukan Tindakan yang dikonfigurasi, widget/embed Anda, atau API Quickchat.
{{metadata_visitor_phone_number}}	WhatsApp dan saluran lain yang mengenali nomor telepon, integrasi saluran, Pengumpulan Data Cerdas, pemetaan masukan Tindakan yang dikonfigurasi, widget/embed Anda, atau API Quickchat.

Kunci metadata khusus

Anda dapat melampirkan pasangan kunci-nilai apa pun ke percakapan dan merujuknya sebagai {{metadata_<key>}}.

Dari widget situs web atau embed

Berikan custom_params saat menginisialisasi widget. Lihat bagian Saluran Situs Web: Fitur Lanjutan: Parameter Khusus untuk cuplikan lengkap.

<script>
  _quickchat("custom_params", {
    "order_id": "ord_8a4f3",
    "customer_tier": "gold"
  });
</script>

Rujuk nilainya dalam Tindakan apa pun sebagai {{metadata_order_id}} dan {{metadata_customer_tier}}.

Perhatian

Kunci metadata harus sesuai dengan ^[a-zA-Z0-9_]+$ (huruf, angka, garis bawah). Kunci dengan spasi atau tanda baca lain tidak dapat dirujuk sebagai {{metadata_<key>}}. Kunci tetap muncul dalam tampilan metadata percakapan di Kotak Masuk, tetapi penggantian Tindakan melewatinya. Gunakan nama snake_case jika ingin memakainya dalam Tindakan.

Dari Pengumpulan Data Cerdas

Setiap poin data aktif dalam Pengumpulan Data Cerdas menjadi kunci metadata berdasarkan namanya dalam snake_case huruf kecil: spasi menjadi garis bawah, aksen dihapus, dan tanda baca lain dibuang.

Poin data	Variabel
Budget	{{metadata_budget}}
Company size	{{metadata_company_size}}
Número de pedido	{{metadata_numero_de_pedido}}

Detail kontak merupakan pengecualian. Poin data bernama Email, Name, atau Phone number (atau varian bahasa Inggris yang serupa seperti Email address, Full name, atau Mobile) mengisi {{metadata_visitor_email}}, {{metadata_visitor_name}}, atau {{metadata_visitor_phone_number}}. Hanya nama bahasa Inggris yang dikenali: poin data bernama Correo electrónico menjadi kuncinya sendiri, correo_electronico. Ketika Agen AI memperoleh detail kontak yang belum dimiliki percakapan, agen juga menetapkan lead_captured ke true.

• Kosong sampai diperoleh. Kunci ditambahkan dengan nilai kosong saat pertama kali Agen AI membalas dengan Pengumpulan Data Cerdas aktif, lalu diisi setelah pengunjung memberikan detail. Koreksi berikutnya memperbarui nilai; nilai tidak pernah dikosongkan lagi.
• Gunakan is true untuk menunggu nilai. Dalam Jalankan saat, budget is true terpenuhi setelah nilai diperoleh, sedangkan budget exists terpenuhi begitu Pengumpulan Data Cerdas dijalankan. Jawaban seperti no, false, atau 0 dianggap salah.
• Nilai Anda sendiri diutamakan. Jika kunci sudah berisi nilai yang ditetapkan situs web, API, atau Tindakan lain, Pengumpulan Data Cerdas membiarkannya. Fitur ini juga berhenti memperbarui kunci setelah sesuatu yang lain mengubahnya.
• Beberapa nama dicadangkan, seperti language, locale, dan lead_captured. Poin data dengan nama tersebut tidak menjadi variabel; ganti namanya jika memerlukan variabel.
• Mengganti nama poin data mengganti nama variabelnya. Perbarui Tindakan yang menggunakannya: Tindakan tidak dapat berjalan ketika variabel yang dibutuhkan tidak ada dalam percakapan.

Setelah percakapan memiliki kunci, kunci tersebut juga muncul dalam dropdown + Tambah Data AI.

Periksa kondisi pelaksanaan Tindakan terhadap contoh metadata untuk melihat kondisi yang terpenuhi. Pemeriksaan mengevaluasi nilai yang diberikan tanpa menjalankan Tindakan.

Dari masukan atau respons Tindakan

Tindakan API dapat menyimpan masukan yang dideklarasikan atau nilai respons API ke kunci metadata agar Tindakan berikutnya dapat menggunakannya kembali. Dalam Simpan ke memori, pilih Input Tindakan atau Respons API sebagai Sumber. Di Nilai yang akan disimpan, pilih parameter Tindakan dari dropdown untuk masukan atau masukkan ekspresi JSONPath untuk respons, lalu pilih Kunci memori. Rujuk nilai sebagai {{metadata_<memory key>}}.

Pemetaan masukan ke visitor_name, visitor_phone_number, dan visitor_email juga mengisi bidang kontak Kotak Masuk yang belum ditetapkan. Nilai yang ada dan bidang yang secara jelas dikosongkan operator dipertahankan. Masukan disimpan sebelum permintaan HTTP setelah Tindakan lolos pemeriksaan, sehingga detail kontak valid tetap tersedia jika API gagal. Lihat Simpan ke memori untuk contoh dan panduan lengkap.

Dari integrasi saluran

HubSpot, Intercom, Telegram, Slack, WhatsApp, dan integrasi serupa mengirim metadata sendiri ke percakapan (nama pengunjung, email, URL halaman, properti akun, dan lainnya). Apa pun yang terlihat dalam tampilan metadata percakapan di Kotak Masuk dapat dirujuk melalui {{metadata_<key>}}.

Dari API Quickchat

Gunakan POST /v1/api_core/conversations/{conv_id}/metadata untuk melampirkan metadata secara terprogram. Lihat Metadata Percakapan dalam referensi API.

Token Sistem

Beberapa integrasi terhubung menyediakan token sistem: kredensial yang dimasukkan Quickchat ke permintaan di sisi server, saat pemanggilan, ketika Tindakan berjalan. Token sistem tidak ditambahkan ke konteks AI atau metadata percakapan, dan disamarkan dari log permintaan, trace, serta log panggilan Kotak Masuk. Metadata biasa tidak memiliki jaminan kerahasiaan yang sama. Token muncul pada bagian Token Sistem dalam dropdown + Tambah Data AI hanya ketika integrasi terkait terhubung, dan dirender sebagai pil oranye.

Token sistem	Tersedia ketika	Nilai yang dimasukkan
{{hubspot_access_token}}	HubSpot terhubung	Token akses OAuth HubSpot yang valid, diperbarui otomatis.
{{telegram_bot_token}}	Skenario memiliki aktivitas Telegram	Token bot Telegram yang terhubung, untuk memanggil Telegram Bot API.

Memanggil Telegram Bot API

Telegram Bot API menerima token bot dalam jalur URL, sehingga Anda merujuknya langsung dalam URL endpoint:

https://api.telegram.org/bot{{telegram_bot_token}}/sendMessage

Quickchat menentukan token saat pemanggilan dan menyamarkannya di setiap tempat permintaan ditampilkan, sehingga rahasia tidak bocor. Untuk mengarahkan panggilan Bot API ke chat, pesan, atau pengirim saat ini, pasangkan dengan kunci metadata Telegram yang ditetapkan Quickchat pada setiap pesan masuk:

Kunci metadata	Nilai
{{metadata_telegram_chat_id}}	Chat tempat pesan berasal.
{{metadata_telegram_chat_type}}	private, group, supergroup, atau channel.
{{metadata_telegram_user_id}}	ID pengguna Telegram pengirim.
{{metadata_telegram_username}}	@username pengirim, jika ada.
{{metadata_telegram_message_id}}	ID pesan masuk.
{{metadata_telegram_sender_is_admin}}	true ketika pengirim merupakan admin chat. Dihitung di sisi server, sehingga tidak dapat dipalsukan dari chat. Gunakan dalam kondisi pelaksanaan untuk membatasi tindakan moderasi kepada admin.
{{metadata_telegram_reply_to_message_id}}, {{metadata_telegram_reply_to_user_id}}, {{metadata_telegram_reply_to_text}}	Ditetapkan ketika pesan masuk merupakan balasan, sehingga AI dapat bertindak pada pesan yang dibalas (misalnya, memoderasi penulisnya).

Warna pil dalam editor

Setiap referensi {{...}} dirender sebagai pil berwarna agar Anda dapat melihat sekilas apakah Quickchat mengenali variabelnya.

Pil berfungsi pada setiap bidang nilai. Di atas: pil oranye {{metadata_user_type}} pada URL endpoint, dan pil biru {{language}} pada nilai header.

Aturan warna yang sama berlaku dalam isi permintaan JSON. Variabel bawaan seperti {{country}} dirender biru, variabel metadata seperti {{metadata_fullPathURL}} dirender oranye.

• 🔵 Biru: variabel bawaan atau parameter AI yang Anda tentukan.
• 🟠 Oranye: variabel metadata ({{metadata_*}}) atau Token Sistem dari integrasi terhubung.
• 🔴 Merah: Quickchat tidak mengenali nama ini. Hampir selalu karena salah ketik. Perbaiki ejaan, tentukan sebagai parameter AI, atau (jika memang kunci metadata) pastikan diawali metadata_.

Tips

Mengetik {{metadata_anything}} secara langsung selalu valid, meskipun kunci belum pernah muncul dalam percakapan. Pil akan berwarna oranye, bukan merah. Inilah cara yang tepat untuk menyiapkan kunci yang Anda tetapkan sendiri dari skrip widget atau Pengumpulan Data Cerdas sebelum percakapan pertama terjadi.

Menguji Tindakan Anda

Panel Uji Respons (di sebelah Selesai dalam editor Tindakan) memungkinkan Anda mengirim permintaan HTTP nyata tanpa melalui chat. Untuk setiap variabel yang dirujuk Tindakan, Anda akan melihat baris masukan untuk mengisi nilai yang akan dimasukkan Quickchat.

Panel mengisi setiap variabel bawaan dengan konteks saat ini atau nilai uji yang mewakili. Default lokal dan waktunya mencakup:

• {{language}} memiliki default en
• {{country}} memiliki default US
• {{current_timestamp}} memiliki default waktu UTC saat ini

Ubah bidang mana pun untuk menguji nilai berbeda. Parameter AI dan kunci {{metadata_*}} awalnya kosong. Ketik nilai apa pun untuk menyimulasikan yang terjadi dalam percakapan nyata.

FAQ

Mengapa variabel saya berwarna merah? Editor tidak mengenali nama tersebut. Bisa jadi salah ketik, tidak cocok dengan parameter AI yang ditentukan, bukan variabel bawaan, atau merupakan kunci metadata tanpa prefiks metadata_.

Bisakah saya memasukkan {{language}} atau {{country}} meskipun tidak pernah menetapkannya? Ya. Quickchat selalu menentukan keduanya dari konteks percakapan (URL halaman, lokal browser, atau bahasa Agen AI yang dikonfigurasi). Anda selalu mendapatkan nilai, meskipun menggunakan fallback en / US.

Apa perbedaan {{language}} dan {{metadata_locale}}?

• {{language}} adalah variabel bawaan. Selalu tersedia, selalu dalam format en / nl / de … Gunakan ini dalam 99% kasus.
• {{metadata_locale}} hanya ada jika integrasi saluran atau widget secara jelas menetapkan kunci locale dalam metadata percakapan, sering kali dalam format xx_YY (misalnya en_GB). Gunakan hanya ketika memerlukan string lokal persis apa adanya.

Apakah ada batas jumlah parameter AI per Tindakan? Ya, 30 per Tindakan. Jika benar-benar membutuhkan lebih banyak, hubungi dukungan.

Apakah nilai bawaan dan metadata dikirim ke AI? Quickchat mengganti nilai ini saat menyusun permintaan HTTP; AI tidak perlu membuat atau mendefinisikannya sebagai parameter AI. Untuk Tindakan AI yang memutuskan, penggantian terjadi setelah AI memilih Tindakan. Tindakan otomatis tidak meminta AI memilihnya.

Penggantian dan konteks model adalah hal terpisah. Metadata yang memenuhi syarat dan konteks bawaan juga dapat tersedia bagi AI, dan respons Tindakan dapat berisi nilai yang sama. Metadata lain disaring dari prompt. Jangan menganggap metadata biasa selalu terlihat atau selalu tersembunyi dari model. Lihat Konteks model dan otorisasi.

Seberapa sering daftar “Metadata (digunakan dalam percakapan terbaru)” diperbarui? Daftar disimpan dalam cache selama 5 menit per Agen AI. Kunci metadata pada percakapan baru dapat memerlukan hingga 5 menit untuk muncul dalam dropdown, tetapi Anda selalu dapat mengetik {{metadata_<your_key>}} langsung tanpa menunggu.

Apakah nama kunci metadata peka huruf besar-kecil? Ya. {{metadata_orderId}} dan {{metadata_orderid}} adalah kunci berbeda. Gunakan kapitalisasi yang persis sama dengan yang ditetapkan pada widget, integrasi, atau API.

Apakah panel Uji Respons mengenali variabel ini? Ya. Panel Uji Respons mengisi ketujuh variabel bawaan, termasuk {{language}} dengan en, {{country}} dengan US, dan {{current_timestamp}} dengan waktu UTC saat ini. Parameter AI dan variabel metadata awalnya kosong. Ketik nilai apa pun untuk menyimulasikan panggilan nyata.

Terkait

• Tindakan Khusus: cara membuat dan mengonfigurasi Tindakan API.
• Saluran Situs Web: Parameter Khusus: cara mengirim metadata dari situs web.
• API: Metadata Percakapan: cara mengirim metadata secara terprogram.