AI Eylemi Değişkenleri

Bir API Eyleminde değer yazabildiğiniz her yerde (URL, başlıklar, gövde veya sorgu parametreleri) {{...}} sözdizimiyle dinamik değerler ekleyebilirsiniz. Quickchat bu yer tutucuları istek sırasında, uç noktanızı çağırmadan hemen önce değiştirir.

Geçerli senaryoda kullanılabilen tüm değişkenleri görmek için herhangi bir değer alanının yanındaki + AI verisi ekle düğmesine tıklayın.

+ AI verisi ekle düğmesi her değer alanının yanında bulunur: uç nokta URL’si, her başlık değeri, gövde alanları ve sorgu parametreleri.

İsteğe bağlı kurulum araçları

• API Eylemi isteğini önizleyin. Sağlanan istek şablonunu, isteği göndermeden sentetik örnek değerlerle oluşturun. Kimlik bilgisi başlıklarını eklemeyin.

• Meta veri anahtarlarını önizleyin. Yinelenen adlar ve ayrılmış anahtar hataları dahil, sağlanan alan adlarının değişken anahtarlarına nasıl dönüştüğünü kontrol edin. Bu işlem değerleri veya hesaba özel izinleri incelemez.

Üç değişken kategorisi

Kategori	Sözdizimi	Ne zaman doldurulur
AI parametreleri. AI Temsilcinizin konuşmadan çıkardığı değerler. Bunları her Eylemin Parametreler bölümünde tanımlarsınız.	{{order_number}}, {{customer_email}}	AI Temsilcisi bunları çağrı sırasında, her parametrenin açıklamasına yazdığınız kurallara göre doldurur.
Yerleşik değişkenler. Quickchat’in otomatik olarak eklediği konuşma bağlamı.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Her zaman kullanılabilir. Quickchat her istekte bunların değerlerini yerine koyar.
Konuşma meta verileri. Konuşmaya eklenen özel anahtar-değer çiftleri.	{{metadata_<key>}}	İlgili anahtar konuşmada bulunduğunda (widget, kanal entegrasyonu, Akıllı Veri Toplama veya API tarafından ayarlanmışsa).

İpucu

Düzenleyicide her değişken renkli bir etiket olarak gösterilir. Mavi, AI parametresi veya yerleşik değişken olduğunu belirtir. Turuncu, meta veri değişkeni veya sistem belirteci olduğunu belirtir. Kırmızı, adın Quickchat’in bildiği hiçbir öğeyle eşleşmediğini gösterir (genellikle yazım hatasıdır).

+ AI verisi ekle açılır menüsü

Açılır menü, geçerli senaryoda kullanılabilen tüm değişkenleri beş bölümde listeler:

1. Parametreler: bu Eylemde tanımladığınız AI parametreleri.
2. Ziyaretçi: kanal sağlıyorsa her ziyaretçi için otomatik alınan dört meta veri anahtarı.
3. Meta veriler (son konuşmalarda kullanılan): bu senaryonun son 20 konuşmasında görülen özel meta veri anahtarları ve her biri için örnek değer.
4. Yerleşik: her zaman kullanılabilen yedi konuşma değişkeni; geçerli değerleri veya örnekleri aynı satırda gösterilir.
5. Sistem belirteçleri: bağlı entegrasyonun (ör. HubSpot, Telegram) sağladığı kimlik bilgileri. Yalnızca entegrasyon bağlıysa görünür. Aşağıdaki Sistem belirteçleri bölümüne bakın.

Açılır menü değişkenleri bölümlere ayırır. Yerleşik satırları, biliniyorsa canlı değeri (scenario_id), diğerleri için e.g. … örneklerini gösterir. Meta veriler (son konuşmalarda kullanılan) grubu, her senaryo için gerçek son konuşmalardan yeniden oluşturulur. Sistem belirteçleri bölümü (burada gösterilmiyor), yalnızca bir entegrasyon bağlı olduğunda görünür.

Not

Meta veriler (son konuşmalarda kullanılan) listesi, senaryonuzun en son 20 konuşmasından yeniden oluşturulur ve AI Temsilcisi başına 5 dakika önbelleğe alınır. Yepyeni bir konuşmada ayarlanan meta veri anahtarının bu bölümde görünmesi 5 dakikayı bulabilir. Her zaman doğrudan {{metadata_<your_key>}} yazabilirsiniz: Quickchat, yerine koyma işlemi için anahtarın açılır menüde görünmesini gerektirmez.

Yerleşik değişkenler

Bu yedi değişken her zaman kullanılabilir. + AI verisi ekle açılır menüsü, her satırın yanında canlı değeri (biliniyorsa) veya örnek bir değer gösterir.

Değişken	Örnek	Açıklama
{{scenario_id}}	abc123xyz	Konuşmanın ait olduğu AI Temsilcisinin kimliği.
{{conversation_id}}	conv-d8a8…	Konuşmanın benzersiz kimliği.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Bu konuşmaya doğrudan Gelen Kutusu bağlantısı.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Konuşmanın gerçekleştiği kanal.
{{current_timestamp}}	2026-09-02T12:00:00+00:00	ISO 8601 biçiminde geçerli UTC tarihi ve saati.
{{language}}	en, nl, de, fr, …	Konuşma dilinin küçük harfli ISO 639-1 kodu.
{{country}}	US, GB, NL, DE, …	Büyük harfli ISO 3166-1 alpha-2 ülke kodu.

Bilinmesi yararlı birkaç nokta:

• {{scenario_id}}, Eylemi düzenlerken tarayıcınızın URL’sinde de görünür. + AI verisi ekle açılır menüsü, düzenlediğiniz senaryonun örnek değil canlı kimliğini gösterir.
• {{conversation_url}}, Slack, Jira veya Gelen Kutusu’na doğrudan dönmenin yararlı olduğu diğer araçlara tıklanabilir bağlantılar göndermek için kullanışlıdır.
• {{language}} şu sırayla belirlenir: sayfa URL’si öneki (Shopify Markets için), konuşma meta verileri, ardından AI Temsilcinizin yapılandırılmış dili.
• {{country}} şu sırayla belirlenir: sayfa URL’si öneki, URL ana bilgisayarının üst düzey alan adı, ardından dilden ülkeye yedek eşleme.

Konuşma meta verileri

metadata_ öneki zorunludur. Quickchat, konuşmanın meta verilerinde <key> anahtarını arar ve değerini isteğe yerleştirir.

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

Ziyaretçi meta veri anahtarları

Bu dört anahtar ziyaretçinin oturumunu tanımlar ve açılır menüde ayrı Ziyaretçi bölümünde yer alır. Kanal, entegrasyon, widget/gömülü sohbet, API, Akıllı Veri Toplama veya yapılandırılmış Eylem girdi eşlemeleri tarafından alınabilirler.

Değişken	Otomatik olarak alan kaynak
{{metadata_fullPathURL}}	Web sitesi widget’ı, web sitesine gömülü sohbet veya kendi widget’ını içeren sohbet kanalı entegrasyonları (HubSpot, Intercom vb.).
{{metadata_visitor_name}}	Sohbet kanalı profili (Telegram, Slack vb.), kanal entegrasyonları, Akıllı Veri Toplama, yapılandırılmış Eylem girdi eşlemeleri, widget/gömülü sohbetiniz veya Quickchat API.
{{metadata_visitor_email}}	Sohbet kanalı profili, kanal entegrasyonları, Akıllı Veri Toplama, yapılandırılmış Eylem girdi eşlemeleri, widget/gömülü sohbetiniz veya Quickchat API.
{{metadata_visitor_phone_number}}	WhatsApp ve telefon bilgisi sağlayan diğer kanallar, kanal entegrasyonları, Akıllı Veri Toplama, yapılandırılmış Eylem girdi eşlemeleri, widget/gömülü sohbetiniz veya Quickchat API.

Özel meta veri anahtarları

Bir konuşmaya istediğiniz anahtar-değer çiftlerini ekleyebilir ve bunlara {{metadata_<key>}} ile başvurabilirsiniz.

Web sitesi widget’ından veya gömülü sohbetten

Widget’ı başlatırken custom_params iletin. Tam kod parçası için Web sitesi kanalı: Gelişmiş Özellikler: Özel Parametreler bölümüne bakın.

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

Bunlara herhangi bir Eylemde {{metadata_order_id}} ve {{metadata_customer_tier}} olarak başvurun.

Dikkat

Meta veri anahtarları ^[a-zA-Z0-9_]+$ biçimine (harf, rakam, alt çizgi) uymalıdır. Boşluk veya başka noktalama işareti içeren anahtarlara {{metadata_<key>}} ile başvurulamaz. Gelen Kutusu’ndaki konuşma meta veri görünümünde yine görünürler, ancak Eylemdeki yerine koyma işlemi bunları atlar. Eylemlerde kullanacağınız adlar için snake_case biçimini tercih edin.

Akıllı Veri Toplama’dan

Akıllı Veri Toplama içindeki her etkin veri noktası, adının küçük harfli snake_case biçiminden oluşan bir meta veri anahtarına dönüşür: boşluklar alt çizgi olur, aksanlar kaldırılır ve diğer noktalama işaretleri silinir.

Veri noktası	Değişken
Budget	{{metadata_budget}}
Company size	{{metadata_company_size}}
Número de pedido	{{metadata_numero_de_pedido}}

İletişim bilgileri istisnadır. Email, Name veya Phone number adlı bir veri noktası (ya da Email address, Full name veya Mobile gibi yakın İngilizce karşılıkları), bunun yerine {{metadata_visitor_email}}, {{metadata_visitor_name}} veya {{metadata_visitor_phone_number}} alanını doldurur. Yalnızca İngilizce adlar tanınır: Correo electrónico adlı veri noktası kendine ait correo_electronico anahtarına dönüşür. AI Temsilcisi konuşmada henüz bulunmayan bir iletişim bilgisini aldığında lead_captured değerini de true yapar.

• Alınana kadar boştur. AI Temsilcisi Akıllı Veri Toplama açıkken ilk yanıtını verdiğinde anahtar boş değerle eklenir, ziyaretçi bilgiyi verdiğinde doldurulur. Sonraki bir düzeltme değeri günceller; tekrar boşaltılmaz.
• Değeri beklemek için is true kullanın. Şu durumda çalıştır bölümünde budget is true, değer alındığında geçer; budget exists ise Akıllı Veri Toplama çalışır çalışmaz geçer. no, false veya 0 gibi yanıtlar yanlış sayılır.
• Kendi değerleriniz önceliklidir. Anahtarda web siteniz, API veya başka bir Eylem tarafından ayarlanmış değer varsa Akıllı Veri Toplama onu değiştirmez. Başka bir şey anahtarı değiştirdiğinde de güncellemeyi bırakır.
• Bazı adlar ayrılmıştır; örneğin language, locale ve lead_captured. Bu adlardan birini taşıyan veri noktası değişkene dönüşmez; değişken gerekiyorsa yeniden adlandırın.
• Veri noktasını yeniden adlandırmak değişkenini de yeniden adlandırır. Onu kullanan Eylemleri güncelleyin: ihtiyaç duyduğu değişken konuşmada yoksa Eylem çalışamaz.

Anahtar bir konuşmada bulunduktan sonra + AI verisi ekle açılır menüsünde de görünür.

Hangi koşulların geçtiğini görmek için örnek meta verilerle Eylem çalışma koşullarını kontrol edin. Kontrol, Eylem çalıştırmadan sağlanan değerleri değerlendirir.

Eylemin girdilerinden veya yanıtından

Bir API Eylemi, sonraki bir Eylemin kullanabilmesi için tanımlı bir girdiyi veya API yanıt değerini meta veri anahtarına kaydedebilir. Belleğe kaydet bölümünde Kaynak olarak Eylem girdisi veya API yanıtı seçin. Kaydedilecek değer altında girdiler için açılır menüden bir Eylem parametresi seçin, yanıtlar için JSONPath ifadesi girin; ardından Bellek anahtarı seçin. Değere {{metadata_<memory key>}} olarak başvurun.

visitor_name, visitor_phone_number ve visitor_email girdi eşlemeleri, Gelen Kutusu’ndaki ayarlanmamış iletişim alanlarını da doldurur. Mevcut değerler ve operatörün açıkça temizlediği alanlar korunur. Eylem kontrolleri geçtikten sonra girdiler HTTP isteğinden önce kaydedilir; böylece API başarısız olsa bile geçerli iletişim bilgileri kullanılabilir kalır. Örnekler ve tam anlatım için Belleğe kaydet bölümüne bakın.

Kanal entegrasyonlarından

HubSpot, Intercom, Telegram, Slack, WhatsApp ve benzeri entegrasyonlar konuşmaya kendi meta verilerini (ziyaretçi adı, e-posta, sayfa URL’si, hesap özellikleri vb.) ekler. Gelen Kutusu’ndaki konuşma meta veri görünümünde bulunan her şeye {{metadata_<key>}} ile başvurulabilir.

Quickchat API’den

Programatik olarak meta veri eklemek için POST /v1/api_core/conversations/{conv_id}/metadata kullanın. API başvurusundaki Konuşma Meta Verileri bölümüne bakın.

Sistem belirteçleri

Bazı bağlı entegrasyonlar bir sistem belirteci sunar: Quickchat’in Eylem çalışırken sunucu tarafında, çağrı anında isteğe eklediği kimlik bilgisi. Sistem belirteci AI bağlamına veya konuşma meta verilerine eklenmez; istek günlüğünde, iz kaydında ve Gelen Kutusu çağrı günlüğünde gizlenir. Normal meta veriler aynı gizlilik güvencelerine sahip değildir. Belirteç, yalnızca ilgili entegrasyon bağlıysa + AI verisi ekle menüsünün Sistem belirteçleri bölümünde görünür ve turuncu etiket olarak gösterilir.

Sistem belirteci	Kullanılabildiği durum	Eklediği değer
{{hubspot_access_token}}	HubSpot bağlı olduğunda	Otomatik yenilenen, geçerli HubSpot OAuth erişim belirteci.
{{telegram_bot_token}}	Senaryoda Telegram etkinliği olduğunda	Telegram Bot API çağrıları için bağlı Telegram botunuzun belirteci.

Telegram Bot API’sini çağırma

Telegram Bot API, bot belirtecini URL yolunda alır; bu nedenle doğrudan uç nokta URL’sinde başvurursunuz:

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

Quickchat belirteci çağrı anında çözümler ve isteğin gösterildiği her yerde gizler; böylece gizli bilgi açığa çıkmaz. Bot API çağrısını geçerli sohbete, mesaja veya gönderene yönlendirmek için Quickchat’in her gelen mesajda ayarladığı Telegram meta veri anahtarlarıyla birlikte kullanın:

Meta veri anahtarı	Değer
{{metadata_telegram_chat_id}}	Mesajın geldiği sohbet.
{{metadata_telegram_chat_type}}	private, group, supergroup veya channel.
{{metadata_telegram_user_id}}	Gönderenin Telegram kullanıcı kimliği.
{{metadata_telegram_username}}	Varsa gönderenin @kullanıcıadı.
{{metadata_telegram_message_id}}	Gelen mesajın kimliği.
{{metadata_telegram_sender_is_admin}}	Gönderen sohbet yöneticisiyse true. Sunucu tarafında hesaplanır, bu nedenle sohbetten taklit edilemez. Moderasyon eylemlerini yöneticilerle sınırlamak için çalışma koşulunda kullanın.
{{metadata_telegram_reply_to_message_id}}, {{metadata_telegram_reply_to_user_id}}, {{metadata_telegram_reply_to_text}}	Gelen mesaj bir yanıtsa ayarlanır; böylece AI yanıtlanan mesaj üzerinde işlem yapabilir (örneğin yazarına moderasyon uygulayabilir).

Düzenleyicideki etiket renkleri

Her {{...}} başvurusu, Quickchat’in değişkeni tanıyıp tanımadığını bir bakışta anlayabilmeniz için renkli etiket olarak gösterilir.

Etiketler her değer alanında çalışır. Yukarıda: uç nokta URL’sinde turuncu {{metadata_user_type}} etiketi ve bir başlık değerinde mavi {{language}} etiketi.

Aynı renk kuralları JSON istek gövdesinde de geçerlidir. {{country}} gibi yerleşik değişkenler mavi, {{metadata_fullPathURL}} gibi meta veri değişkenleri turuncu gösterilir.

• 🔵 Mavi: yerleşik değişken veya tanımladığınız AI parametresi.
• 🟠 Turuncu: meta veri değişkeni ({{metadata_*}}) veya bağlı entegrasyondan Sistem Belirteci.
• 🔴 Kırmızı: Quickchat bu adı tanımıyor. Neredeyse her zaman yazım hatasıdır. Yazımı düzeltin, AI parametresi olarak tanımlayın veya (gerçekten meta veri anahtarıysa) metadata_ ile başladığından emin olun.

İpucu

Anahtar henüz hiçbir konuşmada görünmemiş olsa bile doğrudan {{metadata_anything}} yazmak her zaman geçerlidir. Etiket kırmızı değil turuncu olur. İlk konuşma gerçekleşmeden önce widget betiği veya Akıllı Veri Toplama ile ayarladığınız anahtarları bağlamanın doğru yolu budur.

Eyleminizi test etme

Yanıtı test et paneli (Eylem düzenleyicisinde Bitti yanında), sohbetten geçmeden gerçek HTTP isteği göndermenizi sağlar. Eylemde başvurulan her değişken için Quickchat’in yerine koyacağı değeri doldurabileceğiniz bir girdi satırı görürsünüz.

Panel, her yerleşik değişkeni canlı bağlam veya temsili test değeriyle önceden doldurur. Dil, ülke ve zaman varsayılanları şunlardır:

• {{language}} varsayılanı en
• {{country}} varsayılanı US
• {{current_timestamp}} varsayılanı geçerli UTC zamanı

Farklı bir değeri test etmek için istediğiniz alanı değiştirin. AI parametreleriniz ve {{metadata_*}} anahtarları boş başlar. Canlı konuşmada ne olacağını simüle etmek için herhangi bir değer yazın.

Sık sorulan sorular

Değişkenim neden kırmızı görünüyor? Düzenleyici adı tanımıyor. Yazım hatası olabilir, tanımladığınız AI parametrelerinden biriyle eşleşmiyor olabilir, yerleşik değişken olmayabilir veya metadata_ öneki eksik bir meta veri anahtarı olabilir.

Hiç ayarlamamış olsam bile {{language}} veya {{country}} ekleyebilir miyim? Evet. Quickchat her ikisini de her zaman konuşma bağlamından (sayfa URL’si, tarayıcı yerel ayarı veya AI Temsilcinizin yapılandırılmış dili) türetir. Yedek olarak en / US kullanılsa bile her zaman bir değer alırsınız.

{{language}} ile {{metadata_locale}} arasındaki fark nedir?

• {{language}} yerleşik değişkendir. Her zaman kullanılabilir, her zaman en / nl / de … biçimindedir. Durumların %99’unda bunu kullanın.
• {{metadata_locale}}, yalnızca kanal entegrasyonu veya widget’ınız konuşma meta verilerinde açıkça locale anahtarı ayarladıysa bulunur; genellikle xx_YY biçimindedir (ör. en_GB). Bunu yalnızca tam yerel ayar dizesine aynen ihtiyacınız olduğunda kullanın.

Eylem başına AI parametresi sayısında sınır var mı? Evet, Eylem başına 30. Daha fazlasına ihtiyacınız varsa destekle iletişime geçin.

Yerleşik değerler ve meta veri değerleri AI’a gönderilir mi? Quickchat bu değerleri HTTP isteğini oluştururken yerine koyar; AI’ın bunları üretmesine veya AI parametresi olarak tanımlamasına gerek yoktur. AI karar verir Eyleminde yerine koyma, AI Eylemi seçtikten sonra gerçekleşir. Otomatik Eylemler AI’dan seçim yapmasını istemez.

Yerine koyma ve model bağlamı ayrıdır. Uygun meta veriler ve yerleşik bağlam AI için de kullanılabilir olabilir; Eylem yanıtı da aynı değerleri içerebilir. Diğer meta veriler istemden filtrelenir. Normal meta verilerin modele her zaman görünür veya her zaman gizli olduğunu varsaymayın. Model bağlamı ve yetkilendirme bölümüne bakın.

Meta veriler (son konuşmalarda kullanılan) listesi ne sıklıkta yenilenir? AI Temsilcisi başına 5 dakika önbelleğe alınır. Yepyeni bir konuşmada ayarlanan meta veri anahtarının açılır menüde görünmesi 5 dakikayı bulabilir; ancak beklemeden her zaman doğrudan {{metadata_<your_key>}} yazabilirsiniz.

Meta veri anahtar adları büyük/küçük harfe duyarlı mı? Evet. {{metadata_orderId}} ve {{metadata_orderid}} farklı anahtarlardır. Widget, entegrasyon veya API tarafında ayarladığınız harf biçimini aynen kullanın.

Yanıtı test et paneli bu değişkenleri tanır mı? Evet. Yanıtı test et paneli yedi yerleşik değişkenin tamamını önceden doldurur: {{language}} için en, {{country}} için US ve {{current_timestamp}} için geçerli UTC zamanı dahil. AI parametreleri ve meta veri değişkenleri boş başlar. Canlı çağrıyı simüle etmek için herhangi bir değer yazın.

İlgili sayfalar

• Özel Eylemler: API Eylemi oluşturma ve yapılandırma.
• Web sitesi kanalı: Özel Parametreler: web sitenizden meta veri gönderme.
• API: Konuşma Meta Verileri: programatik olarak meta veri gönderme.