Zmienne AI Actions

Wszędzie tam, gdzie w API Action możesz wpisać wartość (URL, nagłówki, body lub query parameters), możesz wstawiać dynamiczne wartości przy użyciu składni {{...}}. Quickchat zamienia te placeholdery w momencie żądania, tuż przed wywołaniem Twojego endpointu.

Kliknij przycisk + Add AI Data obok dowolnego pola wartości, aby przejrzeć wszystkie zmienne dostępne w bieżącym scenariuszu.

Przycisk + Add AI Data jest dostępny obok każdego pola wartości: URL endpointu, wartości każdego nagłówka, pól body i query parameters.

Trzy kategorie zmiennych

Kategoria	Składnia	Kiedy się wypełnia
Parametry AI. Wartości, które Twój Agent AI wyciąga z rozmowy. Definiujesz je w sekcji Parameters każdej Akcji.	{{order_number}}, {{customer_email}}	Agent AI wypełnia je w momencie wywołania, na podstawie reguł, które zapiszesz w opisie każdego parametru.
Zmienne wbudowane. Kontekst konwersacji, który Quickchat wstawia automatycznie.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Zawsze dostępne. Quickchat zamienia je przy każdym żądaniu.
Metadane konwersacji. Własne pary klucz-wartość przypisane do konwersacji.	{{metadata_<key>}}	Gdy odpowiedni klucz istnieje na konwersacji (ustawiony przez widget, integrację kanału, Smart Data Gathering lub API).

Wskazówka

Każda zmienna jest renderowana w edytorze jako kolorowy pill. Niebieski oznacza parametr AI lub zmienną wbudowaną. Pomarańczowy oznacza zmienną metadanych lub system token. Czerwony oznacza, że nazwa nie pasuje do niczego, co Quickchat zna (zwykle literówka).

Dropdown ”+ Add AI Data”

Dropdown wyświetla wszystkie zmienne dostępne dla bieżącego scenariusza, pogrupowane w pięć sekcji:

1. Parameters: parametry AI zdefiniowane w tej Akcji.
2. Visitor: cztery klucze metadanych zbierane automatycznie dla każdego użytkownika, gdy jego kanał je dostarcza.
3. Metadata (used in recent conversations): niestandardowe klucze metadanych zauważone w ostatnich 20 konwersacjach tego scenariusza, każdy z przykładową wartością.
4. Built-in: sześć zmiennych konwersacji zawsze dostępnych, z bieżącą wartością lub przykładem inline.
5. System Tokens: dane uwierzytelniające dostarczane przez podłączoną integrację (np. HubSpot). Pojawia się tylko wtedy, gdy integracja jest podłączona.

Dropdown grupuje zmienne w sekcje. Wiersze Built-in pokazują wartość na żywo, jeśli jest już znana (scenario_id), oraz przykłady e.g. … dla pozostałych. Grupa Metadata (used in recent conversations) jest odbudowywana dla każdego scenariusza na podstawie rzeczywistych ostatnich konwersacji. Sekcja System Tokens (tu niewidoczna) pojawia się tylko wtedy, gdy integracja jest podłączona.

Notatka

Lista Metadata (used in recent conversations) jest odbudowywana z 20 najnowszych konwersacji Twojego scenariusza i cache’owana przez 5 minut dla każdego Agenta AI. Klucz metadanych ustawiony na świeżo utworzonej konwersacji może pojawić się w tej sekcji nawet po 5 minutach. Zawsze możesz wpisać {{metadata_<your_key>}} bezpośrednio: Quickchat nie wymaga, aby klucz pojawił się w dropdownie, aby zamiana zadziałała.

Zmienne wbudowane

Te sześć zmiennych jest zawsze dostępne. Dropdown + Add AI Data pokazuje obok każdego wiersza wartość na żywo (jeśli jest już znana) lub wartość przykładową.

Zmienna	Przykład	Czym jest
{{scenario_id}}	abc123xyz	ID Agenta AI, do którego należy konwersacja.
{{conversation_id}}	conv-d8a8…	Unikalny identyfikator konwersacji.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Bezpośredni link do tej konwersacji w Inboxie.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Kanał, na którym odbywa się konwersacja.
{{language}}	en, nl, de, fr, …	Kod ISO 639-1 (małe litery) języka konwersacji.
{{country}}	US, GB, NL, DE, …	Kod kraju ISO 3166-1 alpha-2 (wielkie litery).

Kilka rzeczy, które warto wiedzieć:

• {{scenario_id}} jest również widoczne w adresie URL przeglądarki podczas edycji Akcji. Dropdown + Add AI Data pokazuje żywy ID edytowanego scenariusza, nie przykład.
• {{conversation_url}} przydaje się do publikowania klikalnych linków w Slacku, Jirze lub każdym innym narzędziu, w którym wygodny jest bezpośredni skok do Inboxa.
• {{language}} jest wyprowadzane w następującej kolejności: z prefiksu URL strony (dla Shopify Markets), z metadanych konwersacji, a następnie ze skonfigurowanego języka Twojego Agenta AI.
• {{country}} jest wyprowadzane w następującej kolejności: z prefiksu URL strony, z TLD hosta URL, a następnie z fallbacku język-do-kraju.

Metadane konwersacji

Prefiks metadata_ jest wymagany. Quickchat szuka <key> w metadanych konwersacji i podstawia jego wartość do żądania.

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

Klucze metadanych użytkownika

Te cztery klucze opisują sesję użytkownika i mają w dropdownie własną sekcję Visitor. Są zbierane automatycznie przez kanał, integrację, widget/embed lub API. Nie musisz ich sam wysyłać.

Zmienna	Zbierane automatycznie przez
{{metadata_fullPathURL}}	Widget na stronie, embed strony lub integracje kanałów chatu, które mają własny widget (HubSpot, Intercom itp.).
{{metadata_visitor_name}}	Profil kanału chatu (Telegram, Slack itp.), integracje kanałów, Smart Data Gathering, Twój widget/embed lub Quickchat API.
{{metadata_visitor_email}}	Profil kanału chatu, integracje kanałów, Smart Data Gathering, Twój widget/embed lub Quickchat API.
{{metadata_visitor_phone_number}}	WhatsApp i inne kanały rozpoznające numery telefonów, integracje kanałów, Smart Data Gathering, Twój widget/embed lub Quickchat API.

Niestandardowe klucze metadanych

Możesz dołączyć dowolne pary klucz-wartość do konwersacji i odwoływać się do nich jako {{metadata_<key>}}.

Z widgetu lub embedu strony

Przekaż custom_params podczas inicjalizacji widgetu. Pełny snippet znajdziesz w sekcji Kanał Website: Advanced Features: Custom Parameters.

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

Odwołuj się do nich w dowolnej Akcji jako {{metadata_order_id}} i {{metadata_customer_tier}}.

Uwaga

Klucze metadanych muszą pasować do ^[a-zA-Z0-9_]+$ (litery, cyfry, podkreślniki). Klucze ze spacjami lub innymi znakami nie mogą być referencjonowane jako {{metadata_<key>}}. Nadal pojawią się w widoku metadanych konwersacji w Inboxie, ale podstawienie w Akcji je pominie. Trzymaj się nazw snake_case, jeśli planujesz używać ich w Akcjach.

Ze Smart Data Gathering

Każda nazwa pola, którą skonfigurujesz w kampanii Smart Data Gathering, staje się kluczem metadanych o tej samej nazwie. Jeśli Twoja kampania zbiera delivery_address, możesz od razu używać {{metadata_delivery_address}} w dowolnej kolejnej API Action.

Z integracji kanałowych

HubSpot, Intercom, Telegram, Slack, WhatsApp i podobne integracje dopisują do konwersacji własne metadane (nazwa użytkownika, email, URL strony, właściwości konta itp.). Wszystko, co jest widoczne w widoku metadanych konwersacji w Inboxie, można referencjonować przez {{metadata_<key>}}.

Z Quickchat API

Użyj POST /v1/api_core/conversations/{conv_id}/metadata, aby dołączyć metadane programowo. Zobacz Conversation Metadata w referencji API.

Kolory pillów w edytorze

Każde odwołanie {{...}} jest renderowane jako kolorowy pill, abyś od razu widział, czy Quickchat rozpoznaje zmienną.

Pille działają w każdym polu wartości. Powyżej: pomarańczowy pill {{metadata_user_type}} w URL endpointu i niebieski pill {{language}} w wartości nagłówka.

Te same reguły kolorów obowiązują wewnątrz body JSON żądania. Zmienne wbudowane jak {{country}} renderują się na niebiesko, zmienne metadanych jak {{metadata_fullPathURL}} na pomarańczowo.

• 🔵 Niebieski: zmienna wbudowana lub parametr AI, który zdefiniowałeś.
• 🟠 Pomarańczowy: zmienna metadanych ({{metadata_*}}) lub System Token z podłączonej integracji.
• 🔴 Czerwony: Quickchat nie rozpoznaje tej nazwy. Niemal zawsze literówka. Popraw pisownię, zdefiniuj zmienną jako parametr AI lub (jeśli to naprawdę klucz metadanych) upewnij się, że zaczyna się od metadata_.

Wskazówka

Wpisanie {{metadata_anything}} bezpośrednio jest zawsze poprawne, nawet jeśli klucz nigdy wcześniej nie pojawił się w konwersacji. Pill będzie pomarańczowy, nie czerwony. To właściwy sposób na podłączenie kluczy, które sam ustawiasz ze skryptu widgetu lub Smart Data Gathering, zanim odbędzie się pierwsza konwersacja.

Testowanie Akcji

Panel Test Response (obok Done w edytorze Akcji) pozwala wysłać prawdziwe żądanie HTTP bez konieczności prowadzenia rozmowy. Dla każdej zmiennej referencjonowanej w Akcji zobaczysz wiersz do wpisania wartości, którą Quickchat podstawi.

Dwa wygodne wartości domyślne:

• {{language}} ma domyślnie en
• {{country}} ma domyślnie US

Nadpisz dowolne z tych pól, aby przetestować inną locale. Wszystkie pozostałe zmienne (Twoje parametry AI, klucze {{metadata_*}} i pozostałe wbudowane) startują puste. Wpisz dowolną wartość, aby zasymulować, co stałoby się w żywej konwersacji.

FAQ

Dlaczego moja zmienna jest czerwona? Edytor nie rozpoznaje nazwy. Albo to literówka, albo nazwa nie pasuje do żadnego zdefiniowanego parametru AI, albo nie jest to zmienna wbudowana, albo to klucz metadanych bez prefiksu metadata_.

Czy mogę wstawić {{language}} lub {{country}}, nawet jeśli nigdy ich nie ustawiam? Tak. Quickchat zawsze wyprowadza oba z kontekstu konwersacji (URL strony, locale przeglądarki lub skonfigurowany język Twojego Agenta AI). Zawsze otrzymasz wartość, nawet jeśli sprowadzi się do en / US.

Jaka jest różnica między {{language}} a {{metadata_locale}}?

• {{language}} to zmienna wbudowana. Zawsze dostępna, zawsze w formacie en / nl / de … Używaj jej w 99% przypadków.
• {{metadata_locale}} istnieje tylko wtedy, gdy integracja kanału lub Twój widget jawnie ustawił klucz locale w metadanych konwersacji, często w formacie xx_YY (np. en_GB). Sięgaj po nią tylko wtedy, gdy potrzebujesz dokładnego ciągu locale.

Czy istnieje limit liczby parametrów AI na Akcję? Tak, 30 na Akcję. Jeśli naprawdę potrzebujesz więcej, skontaktuj się z supportem.

Czy wartości wbudowane i metadanych są wysyłane do AI? Nie. Są wstrzykiwane do żądania HTTP po tym, jak AI zdecyduje o wywołaniu Akcji. AI ich nie widzi i nie jest proszone o ich wypełnienie. Dlatego nie muszą być definiowane jako parametry AI.

Jak często odświeżana jest lista „Metadata (used in recent conversations)”? Jest cache’owana przez 5 minut na Agenta AI. Klucz metadanych ustawiony na świeżo utworzonej konwersacji może pojawić się w dropdownie nawet po 5 minutach, ale {{metadata_<your_key>}} możesz zawsze wpisać bezpośrednio bez czekania.

Czy nazwy kluczy metadanych rozróżniają wielkość liter? Tak. {{metadata_orderId}} i {{metadata_orderid}} to różne klucze. Używaj dokładnie tej samej wielkości liter, jakiej użyłeś po stronie widgetu, integracji lub API.

Czy panel Test Response zna te zmienne? Tak. Gdy Twoja Akcja referencjonuje {{language}} lub {{country}}, panel Test Response wypełnia je odpowiednio en i US. Wszystkie pozostałe zmienne startują puste. Wpisz dowolną wartość, aby zasymulować żywe wywołanie.

Powiązane

• Custom Actions: jak utworzyć i skonfigurować API Action.
• Kanał Website: Custom Parameters: jak wysyłać metadane ze swojej strony.
• API: Conversation Metadata: jak wysyłać metadane programowo.