# Шаблоны в инструкциях

{% hint style="warning" %}
Данный функционал находится на стадии бета-тестирования. Обо всех найденных ошибках сообщайте в поддержку.
{% endhint %}

Шаблоны нужны, чтобы одна инструкция могла автоматически подстраиваться под разные сценарии поведения. Вместо того чтобы делать отдельный промпт для каждого канала, каждого сценария и каждого типа клиента, можно собрать одну универсальную инструкцию и добавить в неё правила: что подставить, что показать, а что скрыть. Это особенно полезно, потому что стоимость использования ИИ-агента зависит в том числе от объёма инструкции.

Шаблоны позволяют сделать инструкцию бота «умнее»: она может автоматически меняться в зависимости от того, например, с какого канала написал пользователь, как его зовут, какой сейчас день недели и т.д.

Например, один и тот же бот может показывать разные артикулы товаров для Ozon и Wildberries — и для этого не нужно создавать отдельного бота для каждого канала.

{% hint style="info" %}
Проще всего объяснить шаблоны так: это способ заранее написать “умный конструктор” инструкции. Когда приходит сообщение, система собирает из этого конструктора уже готовый текст — только с нужными кусками. В Python Liquid2 для этого используются два типа синтаксиса: {{ ... }} для вывода значения и {% ... %} для логики, например условий, выбора, комментариев и присваивания переменных.
{% endhint %}

## Системные переменные

Кроме данных из диалога (имя пользователя, его email и т.д.), в шаблонах можно использовать встроенные переменные — данные, которые система подставляет автоматически.

<table><thead><tr><th width="264.01171875">Переменная</th><th width="147.3671875">Тип</th><th width="359.62109375">Описание</th></tr></thead><tbody><tr><td><code>instance_max_answer_tokens</code></td><td>Целое число</td><td>Максимальное количество токенов, доступных боту для ответа</td></tr><tr><td><code>current_datetime_iso</code></td><td>Строка</td><td>Текущие дата и время в формате ISO</td></tr><tr><td><code>current_datetime</code></td><td>Строка</td><td>Текущие дата и время в формате "Saturday, January 02, 2025 at 16:03+03:00"</td></tr><tr><td><code>now_datetime</code></td><td>Дата-время</td><td>Текущие дата и время в нативном формате. Подробнее в пункте про фильтры</td></tr><tr><td><code>current_year</code></td><td>Целое число</td><td>Текущий год</td></tr><tr><td><code>chat_link</code></td><td>Строка</td><td>Ссылка на этот диалог в ЛК Савви</td></tr><tr><td><code>channel_name</code></td><td>Строка</td><td>Кодовое название канала. Посмотреть можно в шапке экспорта диалога в параметре <code>channel_name</code></td></tr></tbody></table>

## Теги

Теги — это специальные конструкции внутри инструкции, которые управляют тем, что именно увидит бот. С их помощью можно вставлять данные из диалога, добавлять условия, комментарии и многое другое.

Полный список доступных тегов (на английском языке) можно посмотреть [здесь](https://jg-rp.github.io/python-liquid2/tag_reference).

### Вставка переменных

{% hint style="warning" %}
Если вы уже используете переменные в обычной инструкции (без шаблона), обратите внимание: в шаблонах они пишутся немного иначе — в двойных фигурных скобках: `{{ имя_переменной }}`.
{% endhint %}

В инструкцию можно подставлять любые данные из диалога — например, имя пользователя или текущее время.

Список доступных для использования в диалоге параметров можно найти в шапке экспорта диалога — в поле `channel_variables`.

<div align="left"><figure><img src="/files/WBWVanYod84qeeWoci1T" alt=""><figcaption></figcaption></figure></div>

Также доступны системные переменные.

<div align="left"><figure><img src="/files/0uHSjjoyBXSxr7P74vp3" alt=""><figcaption></figcaption></figure></div>

Пример инструкции для работы с переменными:

```liquid
Ты - сотрудник компании "Мои колёса".

Имя твоего собеседника - {{ name }}
Текущие дата и время - {{ current_datetime }}
```

Когда бот получит эту инструкцию, переменные автоматически заменятся на реальные данные:

```
Ты - сотрудник компании "Мои колёса".

Имя твоего собеседника - Ангелина Викторовна
Текущие дата и время - Saturday, January 02, 2025 at 16:03+03:00
```

### Комментарии

{% hint style="danger" %}
Если вы используете комментарии в обычной инструкции или файлах базы знаний, обратите внимание: в шаблонах они оформляются иначе.
{% endhint %}

Комментарии — это заметки для вас, которые бот никогда не увидит. Они полностью удаляются из инструкции перед отправкой боту и удобны для пояснений при настройке.

```liquid
Ты - сотрудник компании "Мои колёса".

{# Это однострочный комментарий #}

{#
    Это
    Многострочный
    Комментарий
#}

Ты можешь ...
```

Если нужно временно «выключить» какой-то блок инструкции (например, пока он не нужен), можно обернуть его в комментарий, начало комментария **{#**, конец комментария **#}** вот так:

```liquid
{# уберем это пока, пока что не нужно

{% if channel_name == "ozon" %}
Ты отвечаешь на отзыв Озон
{% endif %}

#}
```

### Условия

Условия позволяют показывать боту разный текст в зависимости от ситуации. Например, можно указать разные артикулы товаров для разных площадок:

```liquid
Ты - сотрудник компании "Мои колёса".

{# Артикулы ниже зависят от канала #}

Если клиент спрашивает про артикулы колёс, отправь ему эти:
{% if channel_name == "ozon" %}
OZ123, OZ456, OZ789
{% elsif channel_name == "wildberries" %}
WB124954309, WB30924, WB12093
{% else %}
YM123, YM123123
{% endif %}
```

В итоге бот получит инструкцию, уже адаптированную под нужный канал:

{% tabs %}
{% tab title="Ozon" %}

```
Ты - сотрудник компании "Мои колёса".

Если клиент спрашивает про артикулы колёс, отправь ему эти:
OZ123, OZ456, OZ789
```

{% endtab %}

{% tab title="Wildberries" %}

```
Ты - сотрудник компании "Мои колёса".

Если клиент спрашивает про артикулы колёс, отправь ему эти:
WB124954309, WB30924, WB12093
```

{% endtab %}

{% tab title="Яндекс Маркет (и любой другой канал)" %}

```
Ты - сотрудник компании "Мои колёса".

Если клиент спрашивает про артикулы колёс, отправь ему эти:
YM123, YM123123
```

{% endtab %}
{% endtabs %}

Как это работает:

* `if` — основное условие. Проверяется первым.
* `elsif` — дополнительное условие. Проверяется, если предыдущее не сработало. Допустимо любое количество дополнительных условий.
* `else` — запасной вариант. Подставляется, если ни одно из условий не выполнилось. Если `else` не указан и ни одно условие не сработало — в инструкцию ничего не добавится.

`else` и `elsif` добавлять не обязательно.

### Выбор

Если вариантов много и условия становятся громоздкими, удобнее использовать блок выбора — он специально создан для ситуаций, когда нужно выбрать один из множества вариантов в зависимости от значения одной переменной. Например, для разных каналов продаж:

```liquid
Ты - сотрудник компании "Мои колёса".

{# Артикулы ниже зависят от канала #}

Если клиент спрашивает про артикулы колёс, отправь ему эти:
{% case channel_type %}
    {% when 'ozon' %}
        OZ123, OZ456, OZ789
    {% when 'wildberries' %}
        WB124954309, WB30924, WB12093
    {% when 'yandex_market' %}
        YM123, YM123123
{% endcase %}
```

Можно добавить запасной вариант через `else` — он сработает, если канал не совпал ни с одним из перечисленных:

```liquid
Ты - сотрудник компании "Мои колёса".

{# Приветствие зависит от дня недели #}

{#
    Про assign, plus и date будет ниже.
    Присваиваем переменной weekday значение текущего дня недели с помощью assign и фильтра date
#}



Поприветствуй пользователя этой фразой:




```

Бот получит приветствие, которое автоматически подбирается под день недели:

{% tabs %}
{% tab title="Понедельник" %}

```
Ты - сотрудник компании "Мои колёса".

Поприветствуй пользователя этой фразой:
Здравствуйте, хорошего вам начала недели!
```

{% endtab %}

{% tab title="Пятница" %}

```
Ты - сотрудник компании "Мои колёса".

Поприветствуй пользователя этой фразой:
Здравствуйте, уже пятница, скоро выходные, мы на выходных не работаем.
```

{% endtab %}

{% tab title="Суббота / Воскресенье" %}

```
Ты - сотрудник компании "Мои колёса".

Поприветствуй пользователя этой фразой:
Здравствуйте, хороших выходных! Операторы в это время не работают
```

{% endtab %}

{% tab title="Другой день недели" %}

```
Ты - сотрудник компании "Мои колёса".

Поприветствуй пользователя этой фразой:
Здравствуйте!
```

{% endtab %}
{% endtabs %}

То, как это будет выглядеть в инструкции:

<figure><img src="/files/kmx3JUdXxTRpe422VJUG" alt=""><figcaption></figcaption></figure>

То, что увидит бот(сегодня был вторник)

<figure><img src="/files/zA2ojPv2UFIDkwW2QTde" alt=""><figcaption></figcaption></figure>

:

### Собственные переменные

Иногда одни и те же данные нужны в разных местах инструкции. Чтобы не повторять длинные условия несколько раз, можно сохранить нужное значение в переменную с помощью тега `assign` и затем использовать её где угодно:

```
{% assign article = 'OZ123' %}

{{ article }}
```

Особенно удобно сочетать `assign` с блоком выбора. Например, можно в начале инструкции один раз определить все данные для каждого канала, а дальше просто использовать готовые переменные:

```liquid
{% assign platform = '' %}

{% assign wheels_articles = '' %}

{% assign steering_articles = '' %}

{% case channel_type %}

  {% when 'wildberries' %}

    {% assign platform = 'Wildberries' %}

    {% assign wheels_articles = 'WB123, WB456, WB789' %}

    {% assign steering_articles = 'WB987, WB765' %}

  {% when 'ozon' %}

    {% assign platform = 'Ozon' %}

    {% assign wheels_articles = 'OZ1212313, OZ452346, OZ7894534' %}

    {% assign steering_articles = 'OZ345987, OZ764355' %}

  {% when 'yandex_market' %}

    {% assign platform = 'Яндекс.Маркете' %}

    {% assign wheels_articles = 'ЯМ1212313, ЯМ452346, ЯМ7894534' %}

    {% assign steering_articles = 'ЯМ345987, ЯМ764355' %}

{% endcase %}

Ты — сотрудник компании "Мои колёса". Твоя задача — отвечать на вопросы под товарами на {{ platform }}.

Если клиент спрашивает про новые колёса, отправь артикулы: {{ wheels_articles }}

Если клиент спрашивает про новый руль, отправь артикулы: {{ steering_articles }}
```

Итоговая инструкция для каждого канала будет выглядеть так:

{% tabs %}
{% tab title="Ozon" %}

```
Ты — сотрудник компании "Мои колёса". Твоя задача — отвечать на вопросы под товарами на Ozon.

Если клиент спрашивает про новые колёса, отправь артикулы: OZ1212313, OZ452346, OZ7894534

Если клиент спрашивает про новый руль, отправь артикулы: OZ345987, OZ764355
```

{% endtab %}

{% tab title="Wildberries" %}

```
Ты — сотрудник компании "Мои колёса". Твоя задача — отвечать на вопросы под товарами на Wildberries.

Если клиент спрашивает про новые колёса, отправь артикулы: WB123, WB456, WB789

Если клиент спрашивает про новый руль, отправь артикулы: WB987, WB765
```

{% endtab %}

{% tab title="Яндекс Маркет" %}

```
Ты — сотрудник компании "Мои колёса". Твоя задача — отвечать на вопросы под товарами на Яндекс.Маркете.

Если клиент спрашивает про новые колёса, отправь артикулы: ЯМ1212313, ЯМ452346, ЯМ7894534

Если клиент спрашивает про новый руль, отправь артикулы: ЯМ345987, ЯМ764355
```

{% endtab %}

{% tab title="Другой канал" %}

```
Ты — сотрудник компании "Мои колёса". Твоя задача — отвечать на вопросы под товарами .

Если клиент спрашивает про новые колёса, отправь артикулы:

Если клиент спрашивает про новый руль, отправь артикулы:
```

Не пугайтесь такому тексту. Так получилось из-за того, что мы не указали `else` в блоке выбора
{% endtab %}
{% endtabs %}

## Фильтры

Фильтры позволяют изменить значение переменной перед тем, как оно попадёт в инструкцию. Например, привести имя к нужному виду, обрезать длинный текст или отформатировать дату.

Фильтр указывается после переменной через символ `|`:

```liquid
{{ name | capitalize }}
```

Некоторые фильтры принимают дополнительный параметр:

```liquid
{{ email | default: "No email" }}
```

Самые полезные фильтры для работы с инструкцией:

<table><thead><tr><th width="262" align="center">Фильтр</th><th width="160">Описание</th><th width="327">Пример</th></tr></thead><tbody><tr><td align="center"><code>capitalize</code></td><td>Делает первую букву текста заглавной, а остальные — строчными</td><td><code>name</code> равен "иВАн"<br>После применения фильтра подставится "Иван"</td></tr><tr><td align="center"><code>default: &#x3C;значение></code></td><td>Подставляет заданное значение, если переменная не определена (например отсутствует в канале)</td><td><p>Переменная <code>email</code> есть в канале Usedesk, но её нет в Telegram.<br><br>Если написать:<br><code>{{ email | default: "No email" }}</code><br><br>То при обращении из Usedesk подставится почта пользователя, а из Telegram — строка</p><p>"No email"</p></td></tr><tr><td align="center"><code>downcase</code></td><td>Переводит все буквы в нижний регистр</td><td>"Иван" → "иван"</td></tr><tr><td align="center"><code>upcase</code></td><td>Переводит все буквы в верхний регистр</td><td>"Иван" → "ИВАН"</td></tr><tr><td align="center"><code>truncate: &#x3C;кол-во символов></code></td><td>Обрезает текст до указанного числа символов и добавляет "..." в конце</td><td>"Привет, меня зовут Иван" → "Привет, меня зо..."</td></tr><tr><td align="center"><code>truncatewords: &#x3C;кол-во слов></code></td><td>Обрезает текст до указанного числа слов и добавляет "..." в конце</td><td>"Привет, меня зовут Иван" → "Привет, меня..."</td></tr><tr><td align="center"><code>strip</code></td><td>Убирает лишние пробелы в начале и конце строки</td><td>" Иван " → "Иван"</td></tr><tr><td align="center"><code>date: &#x3C;формат></code></td><td>Форматирует дату так, как вам нужно</td><td><code>{{ now_datetime | date: "%A" }}</code> → "Monday"<br><br>Полный список вариантов форматирования — <a href="https://docs.python.org/3.6/library/datetime.html#strftime-and-strptime-behavior">здесь</a></td></tr><tr><td align="center"><p><code>plus: &#x3C;число></code></p><p><code>minus: &#x3C;число></code></p><p><code>divided_by: &#x3C;число></code></p></td><td>Прибавить / вычесть / разделить на указанное число</td><td><code>{{ 5 | plus: 1 }}</code> → 6<br><code>{{ "5" | plus: 0 }}</code> → 5<br><code>{{ "5" | plus: 1 }}</code> → 6</td></tr></tbody></table>

Все доступные фильтры можно посмотреть [здесь](https://jg-rp.github.io/python-liquid2/filter_reference).

## FAQ новичка

### Я вообще не понимаю разницу между `{{ ... }}` и `{% ... %}`

Очень просто:

`{{ ... }}` — когда нужно вывести значение.\
`{% ... %}` — когда нужно выполнить логику: условие, выбор, комментарий, присваивание переменной.

***

### Когда использовать `if`, а когда `case`?

Используйте `if`, когда условий немного или когда вы проверяете разные логические выражения. Используйте `case`, когда у вас много вариантов, но сравнивается одна и та же переменная — например канал, тип клиента или статус. `if` поддерживает `elsif` и `else`, а `case` — несколько `when` и `else`.

***

### Что делать, если переменная может быть пустой?

Обычно — использовать `default`.

```
{{ email | default: "не указан" }}
```

Это самый безопасный вариант для новичка, потому что вам не нужно писать отдельный блок с проверками на пустое значение.

***

### Что делать, если имя пользователя пришло в странном виде?

Можно сразу нормализовать его в одной строке:

```
{{ name | strip | capitalize | default: "клиент" }}
```

`strip` уберёт пробелы по краям, `capitalize` поправит регистр, а `default` подставит запасное слово, если имени нет.

***

### Что делать, если вариантов очень много?

Если у вас много каналов, категорий товаров или сценариев, лучше сначала через `case` присвоить значения переменным, а ниже использовать уже короткий финальный текст. Так шаблон становится намного понятнее и проще для поддержки.

***

### Можно ли оставлять заметки внутри инструкции?

Да. Для этого используйте комментарии:

```
{% comment %}
Это служебная заметка
{% endcomment %}
```

или

```
{% # Это короткий комментарий %}
```

Комментарии удобны для настройки и не попадают в итоговый текст.

***

### С чего начать, если я никогда не работал с шаблонами?

Лучший путь — идти по шагам.

Сначала научиться подставлять значения:

```
{{ name }}
{{ email }}
```

Потом — добавить один фильтр:

```
{{ name | capitalize }}
{{ email | default: "не указан" }}
```

Потом — одно простое условие:

```
{% if channel_name == "ozon" %}
Отправь артикулы Ozon.
{% endif %}
```

И только после этого переходить к `case` и `assign`. Так проще не запутаться и быстрее понять логику шаблонов.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.suvvy.ai/ru/osnovnye-nastroiki/prompts/shablony-v-instrukciyakh-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.