> For the complete documentation index, see [llms.txt](https://docs.suvvy.ai/ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.suvvy.ai/ru/osnovnye-nastroiki/prompts/prompts-1.md).

# Переменные

В данном разделе вы найдете информацию по переменным.

**Переменные** — это подстановки, которые Савви заполняет автоматически в момент ответа. Вы пишете в инструкции `{current_datetime}`, а модель получает уже готовое «Saturday, January 02, 2025 at 16:03+03:00».

Все переменные записываются в фигурных скобках и делятся на три группы:

| Группа               | Что внутри                                                                                | Кто заполняет |
| -------------------- | ----------------------------------------------------------------------------------------- | ------------- |
| **Системные**        | Дата, время, часовой пояс, канал, ссылка на диалог, параметры агента                      | Платформа     |
| **Канальные**        | Данные о собеседнике и о сделке / заявке / товаре, которые пришли из подключённого канала | Канал         |
| **Пользовательские** | То, что агент запомнил в ходе диалога сам                                                 | Агент         |

### Как вставить переменную

Не обязательно помнить названия наизусть — в [командной панели](https://docs.suvvy.ai/ru/osnovnye-nastroiki/prompts) над полем инструкции есть выбор переменных из готового списка. Список зависит от агента: в него попадают системные переменные, переменные подключённых каналов и созданные вами пользовательские переменные.

Переменные работают не только в системной инструкции. Их же можно подставлять:

* в [аргументы действий и веб-хуков](https://docs.suvvy.ai/ru/deistviya/veb-khuki) — в том числе прямо в URL запроса;
* в текст [фоллоу-апов](https://docs.suvvy.ai/ru/osnovnye-nastroiki/dopolnitelnye-nastroiki/follou-apy);
* в условия отбора диалогов при [рассылках](https://docs.suvvy.ai/ru/mailing/rassylki);
* в [шаблоны уведомлений в Telegram](https://docs.suvvy.ai/ru/osnovnye-nastroiki/opovesheniya-ot-savvi/nastraivaemye-uvedomleniya-v-tg) — но там свой отдельный набор плейсхолдеров, он не совпадает с описанным ниже.

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

Доступны в любом агенте, независимо от того, какие каналы подключены.

| Переменная                     | Тип         | Что подставляет                                                                                                             |
| ------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| `{current_datetime}`           | Строка      | Текущие дата и время в формате `Saturday, January 02, 2025 at 16:03+03:00`                                                  |
| `{current_datetime_iso}`       | Строка      | Те же дата и время в формате ISO                                                                                            |
| `{current_date}`               | Строка      | Только текущая дата                                                                                                         |
| `{current_time}`               | Строка      | Только текущее время                                                                                                        |
| `{current_year}`               | Целое число | Текущий год                                                                                                                 |
| `{current_timezone}`           | Строка      | Часовой пояс, в котором работает агент                                                                                      |
| `{now_datetime}`               | Дата-время  | Текущие дата и время в «нативном» формате — не строкой, а объектом даты                                                     |
| `{channel_name}`               | Строка      | Кодовое название канала, из которого пришло обращение — см. [таблицу ниже](#kodovye-nazvaniya-kanalov)                      |
| `{chat_link}`                  | Строка      | Ссылка на этот диалог в кабинете Савви. Удобно передавать в уведомление менеджеру, чтобы он открыл переписку одним нажатием |
| `{instance_name}`              | Строка      | Название агента                                                                                                             |
| `{instance_max_answer_tokens}` | Целое число | Максимальное количество токенов, доступных агенту на один ответ                                                             |

{% hint style="info" %}
Дата и время подставляются в том часовом поясе, который выбран в **Доп. настройки → Рабочее время**. Если агент отвечает клиентам из другого региона — проверьте эту настройку прежде, чем разбираться, почему он ошибается со сроками.
{% endhint %}

{% hint style="warning" %}
Текущие дата и время уже вшиты в служебную инструкцию каждого агента — отдельно добавлять их в инструкцию не нужно. Переменные даты и времени пригодятся, когда вам важен конкретный формат или нужно построить на них условие.
{% endhint %}

#### Пример: срок доставки от текущей даты

{% tabs %}
{% tab title="Пример использования в инструкции" %}
{% code overflow="wrap" %}

```
# ТЕКУЩИЕ ДАТА И ВРЕМЯ
{current_datetime}

# СРОКИ ДОСТАВКИ
Доставка занимает 3 рабочих дня. Считай срок от текущей даты и называй клиенту конкретное число, а не «через три дня».
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Канальные переменные

Когда обращение приходит из подключённого канала, вместе с сообщением в Савви попадают данные о собеседнике и о том объекте, в котором идёт переписка: сделке в CRM, заявке в хелпдеске, карточке товара на маркетплейсе. Эти данные и становятся канальными переменными.

Набор переменных **зависит от канала**. У Telegram есть имя и username, у amoCRM — идентификаторы сделки и контакта, у Wildberries — артикул товара, у голосового канала — номер телефона и причина завершения звонка.

#### Базовый набор

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

| Переменная            | Что подставляет                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `{name}`              | Имя собеседника, как его передал канал                                                                               |
| `{username}`          | Логин собеседника в канале, например ник в Telegram                                                                  |
| `{link}`              | Ссылка на переписку на стороне канала — на сделку в CRM или чат в мессенджере                                        |
| `{source_chat_id}`    | Идентификатор чата на стороне канала                                                                                 |
| `{source_channel_id}` | Идентификатор самого канала                                                                                          |
| `{channel_name}`      | Кодовое название канала                                                                                              |
| `{custom_fields}`     | Дополнительные поля конкретного канала. В CRM сюда попадают собственные поля сделки — см. [ниже](#svoi-polya-sdelki) |

#### Кодовые названия каналов

Значение `{channel_name}` — это техническое имя канала, а не то, как он подписан в интерфейсе. Именно его нужно указывать в условиях, если агент работает сразу в нескольких каналах и должен отвечать по-разному.

Обратите внимание: у маркетплейсов на каждый тип обращения своё имя — отзыв, вопрос под товаром и чат с покупателем это разные каналы.<br>

| Канал                                     | Значение `channel_name`                      |
| ----------------------------------------- | -------------------------------------------- |
| amoCRM / Kommo                            | `amocrm`, `kommo`                            |
| Битрикс24                                 | `bitrix`                                     |
| RetailCRM                                 | `retailcrm`                                  |
| GetCourse                                 | `getcourse`                                  |
| Telegram                                  | `telegram_bot`                               |
| WhatsApp                                  | `whatsapp`                                   |
| MAX                                       | `max`, `max_bot`                             |
| VK                                        | `vk`                                         |
| Instagram                                 | `instagram`, `instagram_comments`            |
| Facebook                                  | `facebook`                                   |
| Савви Виджет                              | `widget`                                     |
| Jivo                                      | `jivo`                                       |
| Электронная почта                         | `email`, `umnico_email`                      |
| UseDesk                                   | `usedesk`                                    |
| HelpDeskEddy                              | `helpdeskeddy`                               |
| PlanFix                                   | `planfix`                                    |
| Omnidesk                                  | `omnidesk`                                   |
| Zoho                                      | `zoho_salesiq`, `zoho_teaminbox`             |
| Umnico                                    | `umnico`                                     |
| Wazzup                                    | `wazzup`                                     |
| Wildberries                               | `wildberries_review`, `wildberries_question` |
| OZON                                      | `ozon_review`, `ozon_question`, `ozon_chat`  |
| Яндекс.Маркет                             | `yandexmarket_review`, `yandexmarket_chat`   |
| Авито                                     | `avito`                                      |
| ЦИАН                                      | `cian`                                       |
| Персональный канал (API)                  | `custom`                                     |
| Голосовой агент                           | `inbound_voice_call`, `outbound_voice_call`  |
| Тестовый чат и тестовый звонок в кабинете | `test_chat`, `test_voice_call`               |

#### Как узнать переменные своего канала

Самый надёжный способ — посмотреть **экспорт диалога**. В шапке экспорта перечислены все параметры, которые канал передал агенту по этому диалогу, вместе с их значениями.\
Порядок такой:

{% stepper %}
{% step %}

#### Найдите живой диалог из нужного канала

Раздел **История**, фильтр по каналу. Нужен диалог, в котором уже есть сообщения от клиента.
{% endstep %}

{% step %}

#### Выгрузите экспорт диалога

Подробнее про экспорт — в статье [Работа с чатами](https://docs.suvvy.ai/ru/osnovnye-nastroiki/prompts/prompts/rabota-s-chatami).
{% endstep %}

{% step %}

#### Посмотрите параметры в самом верху

Названия параметров из шапки — это и есть имена переменных. Их можно подставлять в инструкцию и передавать в аргументы функций.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Переменная, которой в канале нет, подставится пустой. Например, `{email}` заполнится при обращении из UseDesk, но останется пустым при обращении из Telegram.

Если агент работает в нескольких каналах, учитывайте это в инструкции: не строите на такой переменной обязательный шаг и прописывайте, что делать, когда значения нет. Например: «Если почта клиента не известна — запроси её».
{% endhint %}

#### Переменные amoCRM и Kommo

Из сделки, кроме базового набора, приходят идентификаторы, этап воронки и источник переписки:

| Переменная        | Пример значения    | Что подставляет                                                            |
| ----------------- | ------------------ | -------------------------------------------------------------------------- |
| `{lead_id}`       | `41230987`         | Идентификатор сделки                                                       |
| `{contact_id}`    | `70112233`         | Идентификатор контакта                                                     |
| `{manager_id}`    | `10554477`         | Идентификатор ответственного менеджера                                     |
| `{pipeline_id}`   | `10233445`         | Идентификатор воронки                                                      |
| `{status_id}`     | `80112233`         | Идентификатор этапа сделки                                                 |
| `{price}`         | `15000`            | Бюджет сделки                                                              |
| `{source}`        | `Сделка #41230987` | Название источника, как он подписан в amoCRM                               |
| `{source_id}`     | `21100500`         | Идентификатор источника                                                    |
| `{origin}`        | `help.message`     | Откуда пришло обращение — идентификатор интеграции мессенджера или сервиса |
| `{chat_id}`       | `a1b2c3d4-5e6f-…`  | Идентификатор чата, UUID                                                   |
| `{customer_id}`   | `9f8e7d6c-5b4a-…`  | Идентификатор покупателя, UUID                                             |
| `{talk_id}`       | `17420`            | Идентификатор беседы                                                       |
| `{talk_category}` | —                  | Категория беседы, если задана                                              |

Идентификаторы удобно передавать в веб-хуки и в [уведомления менеджеру](https://docs.suvvy.ai/ru/osnovnye-nastroiki/opovesheniya-ot-savvi/nastraivaemye-uvedomleniya-v-tg): по ним принимающая сторона поймёт, о какой именно сделке речь.

**Пример: разная ссылка на регистрацию в зависимости от источника**

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

{% tabs %}
{% tab title="Использование {origin}" %}
{% code overflow="wrap" %}

```
# ССЫЛКА НА РЕГИСТРАЦИЮ
Источник этого диалога: {origin}

Если клиент хочет зарегистрироваться, отправь ссылку, соответствующую источнику:

- instagram_business — https://example.com/reg/inst
- com.wazzup24-1 — https://example.com/reg/wz
- com.wazzup.whatsapp — https://example.com/reg/wa

Если источник не совпал ни с одним из перечисленных, отправь https://example.com/reg.
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="success" %}
Значения `{origin}` заранее не угадать — они приходят в том виде, в котором их отдаёт интеграция мессенджера, и различаются от CRM к CRM: в amoCRM это, например, `instagram_business`, `com.wazzup.whatsapp` или `help.message`, в Битрикс24 — `telegrambot`. Возьмите значения из экспорта диалога по каждому источнику, прежде чем прописывать условия.
{% endhint %}

#### Переменные Битрикс24

Набор похож на amoCRM по смыслу, но отличается и названиями, и форматом значений:

| Переменная      | Пример значения | Что подставляет                                        |
| --------------- | --------------- | ------------------------------------------------------ |
| `{entity_type}` | `deal`          | Тип объекта, в котором идёт переписка — сделка или лид |
| `{entity_id}`   | `4207`          | Идентификатор этого объекта                            |
| `{contact_id}`  | `3115`          | Идентификатор контакта                                 |
| `{manager_id}`  | `1042`          | Идентификатор ответственного менеджера                 |
| `{pipeline_id}` | `7`             | Идентификатор направления                              |
| `{status_id}`   | `C7:NEW`        | Стадия сделки — вместе с номером направления           |
| `{origin}`      | `telegrambot`   | Канал, из которого пришло обращение в открытую линию   |
| `{openline_id}` | `12`            | Идентификатор открытой линии                           |
| `{chat_id}`     | `2318`          | Идентификатор чата                                     |
| `{bot_id}`      | `987`           | Идентификатор бота Савви в Битриксе                    |
| `{client_id}`   | `a7c31f…`       | Идентификатор приложения Савви                         |

{% hint style="warning" %}
Одинаково названные переменные в разных CRM выглядят по-разному. `{status_id}` в Битрикс24 — это строка вида `C7:NEW`, а в amoCRM — число. `{chat_id}` в Битрикс24 число, в amoCRM — UUID. Сама сделка в amoCRM это `{lead_id}`, а в Битрикс24 — пара `{entity_type}` и `{entity_id}`.

Поэтому инструкцию, написанную под одну CRM, нельзя переносить в агента на другой CRM без правки: возьмите значения из экспорта диалога того канала, с которым работаете.
{% endhint %}

#### Свои поля сделки

Кроме стандартных переменных агент видит и ваши собственные поля сделки — те, что вы выбрали при настройке канала. Они приезжают внутри `{custom_fields}`.

Имя переменной складывается из префикса `entity_` и того псевдонима, который вы задали полю в настройках канала. Задали полю `UF_CRM_1758727500777` псевдоним «Промокод» — агент увидит его как `entity_Промокод`.

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

#### Переменные голосового канала

У [голосового агента](https://docs.suvvy.ai/ru/types-of-agents/golosovoi-agent) свой набор:

| Переменная            | Что подставляет                               |
| --------------------- | --------------------------------------------- |
| `{customer_phone}`    | Номер телефона собеседника                    |
| `{channel_phone}`     | Номер, с которого работает агент              |
| `{call_close_reason}` | Причина завершения звонка — см. значения ниже |
| `{room_name}`         | Идентификатор комнаты звонка                  |

Возможные значения `{call_close_reason}`:

| Значение                   | Что произошло                        |
| -------------------------- | ------------------------------------ |
| `agent_finished`           | Агент завершил разговор сам          |
| `participant_disconnected` | Собеседник положил трубку            |
| `participant_inactive`     | Собеседник молчал дольше допустимого |
| `participant_busy`         | Занято                               |
| `participant_no_answer`    | Не взяли трубку                      |
| `voicemail`                | Ответил автоответчик                 |
| `max_duration`             | Достигнут лимит длительности звонка  |
| `transferred`              | Звонок переведён на менеджера        |
| `internal_error`           | Внутренняя ошибка                    |

{% hint style="info" %}
`{call_close_reason}` заполняется после завершения звонка, поэтому применять его стоит не в самом разговоре, а в том, что происходит после: в веб-хуке, уведомлении менеджеру или условии [исходящего обзвона](https://docs.suvvy.ai/ru/types-of-agents/golosovoi-agent/iskhodyashie-zvonki) — например, перезвонить только тем, кто не взял трубку.
{% endhint %}

### Переменные в интеграциях

Переменные нужны не только для того, чтобы агент что-то знал, — их можно передавать в аргументы функций. Тогда агенту не нужно спрашивать у клиента то, что уже приехало из канала.

Типичный пример — записи в [системах бронирования](https://docs.suvvy.ai/ru/integracii/sistemy-bronirovaniya). У функции поиска записей клиента аргументом идёт телефон, и его можно взять из переменной канала, а не выпрашивать в диалоге:

{% code overflow="wrap" %}

```
# ПРОВЕРКА ЗАПИСЕЙ
Телефон клиента: {customer_phone}

Если клиент спрашивает про свою запись — вызови функцию `yc_get_client_seances_by_phone`, передав туда телефон клиента. Повторно телефон не спрашивай, если он уже известен.
```

{% endcode %}

{% hint style="info" %}
Телефон приходит далеко не из каждого канала: в голосовом он есть всегда, в мессенджерах — нет. Пропишите в инструкции запасной вариант: «Если телефон не известен — попроси клиента его назвать».
{% endhint %}

Так же переменные передаются в [веб-хуки](https://docs.suvvy.ai/ru/deistviya/veb-khuki) — в том числе прямо в строку URL. Например, идентификатор сделки из CRM можно подставить в адрес запроса, чтобы внешний сервис сразу понял, о какой сделке речь.

{% hint style="success" %}
У некоторых интеграций есть своё поле инструкции — отдельное от системной инструкции агента. Переменные работают и там.

Например, в настройках [Google-календаря](https://docs.suvvy.ai/ru/integracii/kalendari/google-kalendar) можно задать правило записи от текущего момента:

`Записывать не раньше, чем через 12 часов от {current_datetime}`

Так агент не предложит клиенту слот на «через полчаса».
{% endhint %}

### Пользовательские переменные

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

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

[Пользовательские переменные](https://docs.suvvy.ai/ru/osnovnye-nastroiki/dopolnitelnye-nastroiki/less-than-greater-than-polzovatelskie-peremennye)

### Частые ошибки

| Симптом                                    | Причина                                                                                                                                                                                                                                                     |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Переменная подставляется пустой            | Канал не передаёт эти данные. Проверьте по экспорту диалога, что параметр вообще приходит                                                                                                                                                                   |
| Условие по `{channel_name}` не срабатывает | Указано название из интерфейса, а не кодовое. Сверьтесь с [таблицей кодовых названий](#kodovye-nazvaniya-kanalov) — например, у OZON три разных значения                                                                                                    |
| Агент ошибается в датах и сроках           | <p>Проверьте часовой пояс в <strong>Доп. настройки → Рабочее время</strong>. <br>Иногда причина в <a href="https://docs.suvvy.ai/ru/osnovnye-nastroiki/dopolnitelnye-nastroiki/maskirovanie-personalnykh-dannykh">маскировании персональных данных</a>.</p> |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.suvvy.ai/ru/osnovnye-nastroiki/prompts/prompts-1.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.