Змінні дій AI

У будь-якому полі значення дії API (URL, заголовки, тіло чи параметри запиту) можна підставити динамічні значення через синтаксис {{...}}. Quickchat замінює ці змінні безпосередньо перед викликом вашого ендпоїнта.

Натисніть + Додати дані AI біля поля значення, щоб переглянути всі змінні поточного сценарію.

Кнопка + Додати дані AI доступна біля кожного поля значення: URL ендпоїнта, заголовків, полів тіла й параметрів запиту.

Додаткові інструменти налаштування

• Попередній перегляд запиту дії API. Побудуйте запит із наданого шаблону й синтетичних тестових значень без надсилання. Не додавайте заголовки з обліковими даними.

• Попередній перегляд ключів метаданих. Перевірте, як надані назви полів перетворюються на ключі змінних, зокрема дублікати назв і помилки зарезервованих ключів. Значення та дозволи конкретного облікового запису не перевіряються.

Три категорії змінних

Категорія	Синтаксис	Коли заповнюється
Параметри AI. Значення, які AI-агент витягує з розмови. Ви задаєте їх у розділі Параметри кожної дії.	{{order_number}}, {{customer_email}}	AI-агент заповнює їх під час виклику за правилами в описі кожного параметра.
Вбудовані змінні. Контекст розмови, який Quickchat підставляє автоматично.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Завжди доступні. Quickchat підставляє їх у кожен запит.
Метадані розмови. Власні пари ключ-значення, прикріплені до розмови.	{{metadata_<key>}}	Коли відповідний ключ є в розмові (заданий віджетом, інтеграцією каналу, Розумним збиранням даних або API).

Порада

Кожна змінна показується в редакторі кольоровою міткою. Синя означає параметр AI або вбудовану змінну. Помаранчева означає метадані чи системний токен. Червона означає невідому Quickchat назву, зазвичай через помилку написання.

Список «+ Додати дані AI»

Список містить усі змінні поточного сценарію, згруповані в п’ять розділів:

1. Параметри: параметри AI, визначені в цій дії.
2. Відвідувач: чотири ключі метаданих, що автоматично збираються для відвідувача, якщо канал їх надає.
3. Метадані (з нещодавніх розмов): власні ключі з останніх 20 розмов сценарію з прикладом кожного значення.
4. Вбудоване: сім завжди доступних змінних розмови з поточним значенням або прикладом у рядку.
5. Системні токени: облікові дані підключеної інтеграції, наприклад HubSpot чи Telegram. Розділ з’являється лише за наявності підключення. Див. Системні токени нижче.

Список групує змінні за розділами. Вбудоване показує поточне значення, якщо воно вже відоме (scenario_id), і приклади e.g. … для решти. Метадані (з нещодавніх розмов) формуються для кожного сценарію з реальних розмов. Системні токени (тут не показано) з’являються лише за підключеної інтеграції.

Заувага

Список Метадані (з нещодавніх розмов) формується з останніх 20 розмов сценарію й кешується на 5 хвилин для кожного AI-агента. Новий ключ може з’явитися в ньому із затримкою до 5 хвилин. Ви завжди можете ввести {{metadata_<your_key>}} безпосередньо: для підстановки Quickchat не вимагає наявності ключа в списку.

Вбудовані змінні

Ці сім змінних доступні завжди. Список + Додати дані AI показує поточне значення, якщо воно вже відоме, або приклад біля кожного рядка.

Змінна	Приклад	Значення
{{scenario_id}}	abc123xyz	ID AI-агента, якому належить розмова.
{{conversation_id}}	conv-d8a8…	Унікальний ідентифікатор розмови.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Пряме посилання на цю розмову у Вхідних.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Канал, у якому відбувається розмова.
{{current_timestamp}}	2026-09-02T12:00:00+00:00	Поточні дата й час UTC у форматі ISO 8601.
{{language}}	en, nl, de, fr, …	Код мови розмови ISO 639-1 малими літерами.
{{country}}	US, GB, NL, DE, …	Код країни ISO 3166-1 alpha-2 великими літерами.

Корисні примітки:

• {{scenario_id}} також видно в URL браузера під час редагування дії. Список + Додати дані AI показує справжній ID поточного сценарію, а не приклад.
• {{conversation_url}} зручний для публікації посилань у Slack, Jira чи інших інструментах, звідки потрібен швидкий перехід до Вхідних.
• {{language}} визначається в такому порядку: префікс URL сторінки (для Shopify Markets), метадані розмови, налаштована мова AI-агента.
• {{country}} визначається в такому порядку: префікс URL сторінки, домен верхнього рівня хоста, резервне зіставлення мови з країною.

Метадані розмови

Префікс metadata_ обов’язковий. Quickchat шукає <key> у метаданих розмови й підставляє його значення в запит.

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

Ключі метаданих відвідувача

Ці чотири ключі описують сеанс відвідувача й мають окремий розділ Відвідувач у списку. Їх можуть збирати канал, інтеграція, віджет/Embed, API, Розумне збирання даних або налаштовані зіставлення вхідних даних дії.

Змінна	Джерело автоматичного збору
{{metadata_fullPathURL}}	Віджет сайту, Embed або інтеграції чат-каналів із власним віджетом (HubSpot, Intercom тощо).
{{metadata_visitor_name}}	Профіль чат-каналу (Telegram, Slack тощо), інтеграції, Розумне збирання даних, зіставлення вхідних даних дії, ваш віджет/Embed або API Quickchat.
{{metadata_visitor_email}}	Профіль чат-каналу, інтеграції, Розумне збирання даних, зіставлення вхідних даних дії, ваш віджет/Embed або API Quickchat.
{{metadata_visitor_phone_number}}	WhatsApp та інші канали з телефонними номерами, інтеграції, Розумне збирання даних, зіставлення вхідних даних дії, ваш віджет/Embed або API Quickchat.

Власні ключі метаданих

До розмови можна додати довільні пари ключ-значення й посилатися на них як {{metadata_<key>}}.

Із віджета сайту або Embed

Передайте custom_params під час ініціалізації віджета. Повний приклад наведено в Ваш сайт: розширені можливості: власні параметри.

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

Посилайтеся на них у будь-якій дії як {{metadata_order_id}} і {{metadata_customer_tier}}.

Обережно

Ключі метаданих мають відповідати ^[a-zA-Z0-9_]+$ (літери, цифри, підкреслення). На ключі з пробілами чи іншою пунктуацією не можна посилатися як {{metadata_<key>}}. Вони залишаться видимими в метаданих розмови у Вхідних, але підстановка дії їх пропустить. Для ключів, які використовуватимете в діях, дотримуйтеся snake_case.

Із Розумного збирання даних

Кожен увімкнений елемент у Розумному збиранні даних стає ключем метаданих із назвою в нижньому регістрі snake_case: пробіли перетворюються на підкреслення, діакритика відкидається, інша пунктуація видаляється.

Елемент даних	Змінна
Budget	{{metadata_budget}}
Company size	{{metadata_company_size}}
Número de pedido	{{metadata_numero_de_pedido}}

Контактні дані є винятком. Елемент із назвою Email, Name чи Phone number (або близьким англійським варіантом, як-от Email address, Full name чи Mobile) заповнює {{metadata_visitor_email}}, {{metadata_visitor_name}} або {{metadata_visitor_phone_number}}. Розпізнаються лише англійські назви: Correo electrónico стає окремим ключем correo_electronico. Коли AI-агент збирає контактні дані, яких у розмові ще не було, він також задає lead_captured значення true.

• Порожнє до отримання даних. Ключ додається з порожнім значенням під час першої відповіді AI з увімкненим збиранням даних і заповнюється після відповіді відвідувача. Подальше виправлення оновлює значення; повторно порожнім воно не стає.
• Використовуйте is true, щоб дочекатися значення. У Запускати коли умова budget is true проходить після отримання значення, а budget exists відразу після запуску збирання даних. Відповіді no, false або 0 вважаються хибними.
• Ваші власні значення мають перевагу. Якщо ключ уже містить значення із сайту, API чи іншої дії, Розумне збирання даних не змінює його. Оновлення також припиняється, щойно ключ змінить інше джерело.
• Деякі назви зарезервовані, наприклад language, locale і lead_captured. Елемент із такою назвою не стає змінною; за потреби перейменуйте його.
• Перейменування елемента перейменовує змінну. Оновіть дії, які її використовують: дія не може виконуватися, коли в розмові немає потрібної змінної.

Коли ключ з’являється в розмові, він також потрапляє до списку + Додати дані AI.

Перевірте умови запуску дії на тестових метаданих, щоб побачити, які проходять. Перевірка оцінює надані значення без виконання дії.

Із вхідних даних або відповіді дії

Дія API може зберегти оголошений вхідний параметр або значення відповіді API в ключ метаданих для повторного використання наступною дією. У Зберегти в пам’ять виберіть Вхідні дані дії або Відповідь API як Джерело. У Значення для збереження виберіть параметр дії зі списку для вхідних даних або введіть JSONPath для відповіді, а потім задайте Ключ пам’яті. Посилайтеся на значення як {{metadata_<memory key>}}.

Зіставлення вхідних даних із visitor_name, visitor_phone_number і visitor_email також заповнюють порожні контактні поля Вхідних. Наявні значення й поля, явно очищені оператором, зберігаються. Вхідні дані записуються до HTTP-запиту після проходження перевірок дії, тому коректні контакти залишаються доступними навіть за помилки API. Приклади й повний посібник наведено в Зберегти в пам’ять.

Із інтеграцій каналів

HubSpot, Intercom, Telegram, Slack, WhatsApp та подібні інтеграції додають власні метадані до розмови (ім’я, email, URL сторінки, властивості облікового запису тощо). На все, що видно в метаданих розмови у Вхідних, можна посилатися через {{metadata_<key>}}.

Із API Quickchat

Використовуйте POST /v1/api_core/conversations/{conv_id}/metadata, щоб додавати метадані програмно. Див. Метадані розмови у довіднику API.

Системні токени

Деякі інтеграції надають системний токен, облікові дані, які Quickchat підставляє в запит на сервері під час виклику дії. Системний токен не додається до контексту AI чи метаданих розмови й приховується в журналі запиту, трасуванні та журналі викликів Вхідних. Звичайні метадані не мають таких гарантій секретності. Токен з’являється в розділі Системні токени списку + Додати дані AI лише після підключення відповідної інтеграції й показується помаранчевою міткою.

Системний токен	Коли доступний	Що підставляє
{{hubspot_access_token}}	HubSpot підключено	Чинний токен доступу OAuth HubSpot, який оновлюється автоматично.
{{telegram_bot_token}}	У сценарію є активність Telegram	Токен підключеного бота для виклику Telegram Bot API.

Виклик Telegram Bot API

Telegram Bot API приймає токен бота в шляху URL, тому посилайтеся на нього безпосередньо в URL ендпоїнта:

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

Quickchat підставляє токен під час виклику й приховує його всюди, де показується запит, щоб секрет не розкривався. Для спрямування виклику Bot API на поточний чат, повідомлення чи відправника поєднуйте його з ключами метаданих, які Quickchat задає для кожного вхідного повідомлення Telegram:

Ключ метаданих	Значення
{{metadata_telegram_chat_id}}	Чат, із якого надійшло повідомлення.
{{metadata_telegram_chat_type}}	private, group, supergroup або channel.
{{metadata_telegram_user_id}}	ID відправника в Telegram.
{{metadata_telegram_username}}	@username відправника, якщо є.
{{metadata_telegram_message_id}}	ID вхідного повідомлення.
{{metadata_telegram_sender_is_admin}}	true, якщо відправник є адміністратором чату. Обчислюється на сервері, тому значення неможливо підробити з чату. Використовуйте його в умові запуску, щоб обмежити дії модерації адміністраторами.
{{metadata_telegram_reply_to_message_id}}, {{metadata_telegram_reply_to_user_id}}, {{metadata_telegram_reply_to_text}}	Задаються, коли вхідне повідомлення є відповіддю, щоб AI міг діяти щодо вихідного повідомлення, наприклад модерувати його автора.

Кольори міток у редакторі

Кожне посилання {{...}} показується кольоровою міткою, щоб відразу було видно, чи Quickchat розпізнає змінну.

Мітки працюють у всіх полях значень. Вище показано помаранчеву {{metadata_user_type}} в URL ендпоїнта й синю {{language}} у значенні заголовка.

Ті самі кольори використовуються в тілі JSON-запиту. Вбудовані змінні, як-от {{country}}, сині, а змінні метаданих, як-от {{metadata_fullPathURL}}, помаранчеві.

• 🔵 Синій: вбудована змінна або визначений вами параметр AI.
• 🟠 Помаранчевий: змінна метаданих ({{metadata_*}}) або системний токен підключеної інтеграції.
• 🔴 Червоний: Quickchat не розпізнає назву, майже завжди через помилку написання. Виправте її, визначте як параметр AI або, якщо це ключ метаданих, перевірте префікс metadata_.

Порада

Безпосереднє введення {{metadata_anything}} завжди коректне, навіть якщо ключ ще не з’являвся в розмовах. Мітка буде помаранчевою, а не червоною. Так слід налаштовувати ключі зі скрипту віджета чи Розумного збирання даних ще до першої розмови.

Тестування дії

Панель Перевірка відповіді (біля Готово в редакторі дії) дає змогу надіслати справжній HTTP-запит без чату. Для кожної змінної дії показано рядок, у який потрібно ввести значення для підстановки Quickchat.

Панель попередньо заповнює всі вбудовані змінні поточним контекстом або типовим тестовим значенням. Типові значення мови й часу:

• {{language}} типово має значення en
• {{country}} типово має значення US
• {{current_timestamp}} типово містить поточний час UTC

Змініть будь-яке поле, щоб перевірити інше значення. Параметри AI й ключі {{metadata_*}} спочатку порожні. Введіть довільні значення, щоб змоделювати справжню розмову.

Часті запитання

Чому змінна червона? Редактор не розпізнає назву. Це може бути помилка написання, відсутність відповідного параметра AI, невідома вбудована змінна або ключ метаданих без префікса metadata_.

Чи можна підставляти {{language}} або {{country}}, якщо я їх не задавав? Так. Quickchat завжди визначає їх із контексту розмови: URL сторінки, локалі браузера або налаштованої мови AI-агента. Значення буде завжди, навіть якщо резервне en / US.

Чим відрізняються {{language}} і {{metadata_locale}}?

• {{language}} є вбудованою змінною. Завжди доступна у форматі en / nl / de тощо. Використовуйте її в 99% випадків.
• {{metadata_locale}} існує лише якщо інтеграція каналу або віджет явно задали ключ locale у метаданих, часто у форматі xx_YY (наприклад, en_GB). Використовуйте її лише коли потрібен точний рядок локалі без змін.

Чи обмежена кількість параметрів AI у дії? Так, 30 на дію. Якщо потрібно більше, зверніться до підтримки.

Чи передаються вбудовані значення й метадані до AI? Quickchat підставляє їх під час формування HTTP-запиту; AI не потрібно генерувати їх або визначати як параметри AI. Для режиму AI вирішує підстановка відбувається після вибору дії моделлю. Автоматичні дії не просять AI зробити вибір.

Підстановка й контекст моделі є окремими механізмами. Дозволені метадані й вбудований контекст також можуть бути доступні AI, а відповідь дії може містити ті самі значення. Інші метадані відфільтровуються з промпту. Не вважайте звичайні метадані завжди видимими або завжди прихованими від моделі. Див. Контекст моделі й авторизація.

Як часто оновлюється список «Метадані (з нещодавніх розмов)»? Він кешується на 5 хвилин для кожного AI-агента. Ключ із нової розмови може з’явитися в списку протягом 5 хвилин, але ви завжди можете ввести {{metadata_<your_key>}} безпосередньо без очікування.

Чи чутливі назви ключів метаданих до регістру? Так. {{metadata_orderId}} і {{metadata_orderid}} є різними ключами. Використовуйте той самий регістр, який задали у віджеті, інтеграції чи API.

Чи знає панель перевірки відповіді про ці змінні? Так. Панель попередньо заповнює всі сім вбудованих змінних, зокрема {{language}} значенням en, {{country}} значенням US, а {{current_timestamp}} поточним часом UTC. Параметри AI й змінні метаданих спочатку порожні. Введіть значення, щоб змоделювати справжній виклик.

Пов’язані теми

• Власні дії: створення й налаштування дії API.
• Ваш сайт: власні параметри: передавання метаданих із сайту.
• API: Метадані розмови: програмне передавання метаданих.