Переменные 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 страницы, домен верхнего уровня хоста URL, затем резервное определение страны по языку.

Метаданные разговора

Префикс metadata_ обязателен. Quickchat ищет <key> в метаданных разговора и подставляет его значение в запрос.

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

Ключи метаданных посетителя

Эти четыре ключа описывают сеанс посетителя и помещаются в отдельный раздел Посетитель в меню. Они могут заполняться каналом, интеграцией, виджетом или встроенным чатом, API, Умным сбором данных или настроенными сопоставлениями входных данных действия.

Переменная	Источник автоматического заполнения
{{metadata_fullPathURL}}	Виджет или встроенный чат сайта либо интеграции каналов чата со своим виджетом (HubSpot, Intercom и т. д.).
{{metadata_visitor_name}}	Профиль в канале чата (Telegram, Slack и т. д.), интеграции каналов, Умный сбор данных, настроенные сопоставления входных данных действия, виджет или встроенный чат либо API Quickchat.
{{metadata_visitor_email}}	Профиль в канале чата, интеграции каналов, Умный сбор данных, настроенные сопоставления входных данных действия, виджет или встроенный чат либо API Quickchat.
{{metadata_visitor_phone_number}}	WhatsApp и другие каналы с доступом к номеру телефона, интеграции каналов, Умный сбор данных, настроенные сопоставления входных данных действия, виджет или встроенный чат либо API Quickchat.

Пользовательские ключи метаданных

К разговору можно прикреплять произвольные пары «ключ-значение» и обращаться к ним через {{metadata_<key>}}.

Из виджета или встроенного чата сайта

Передайте 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 для вызова Telegram Bot API.

Вызов Telegram Bot API

Telegram Bot API принимает токен бота в пути URL, поэтому укажите его непосредственно в URL конечной точки:

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

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

Ключ метаданных	Значение
{{metadata_telegram_chat_id}}	Чат, из которого пришло сообщение.
{{metadata_telegram_chat_type}}	private, group, supergroup или channel.
{{metadata_telegram_user_id}}	ID пользователя Telegram, отправившего сообщение.
{{metadata_telegram_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.

Подстановка и контекст модели являются разными процессами. Допустимые метаданные и встроенный контекст также могут быть доступны AI, а ответ действия может содержать те же значения. Другие метаданные исключаются из промпта. Не считайте обычные метаданные всегда видимыми или всегда скрытыми от модели. См. «Контекст модели и авторизация».

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

Учитывается ли регистр в именах ключей метаданных? Да. {{metadata_orderId}} и {{metadata_orderid}} являются разными ключами. Используйте тот же регистр, который задали в виджете, интеграции или API.

Учитывает ли панель «Проверка ответа» эти переменные? Да. Панель «Проверка ответа» предварительно заполняет все семь встроенных переменных, в том числе {{language}} значением en, {{country}} значением US и {{current_timestamp}} текущим временем UTC. Параметры AI и переменные метаданных изначально пусты. Введите любое значение, чтобы смоделировать реальный вызов.

Связанные материалы

• Пользовательские действия: создание и настройка действия API.
• Канал сайта: пользовательские параметры: передача метаданных с вашего сайта.
• API: метаданные разговора: программная передача метаданных.