> For the complete documentation index, see [llms.txt](https://doc.nextbot.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.nextbot.ru/functional/python-script/shablony-python-script.md).

# Шаблоны Python Script

Как выбрать, применить и адаптировать готовый шаблон Python Script под бизнес-задачу.

В Nextbot есть готовые шаблоны Python Script для распространённых задач: расчётов, работы с API, обработки данных и управления диалогом.

Каждый шаблон — стартовый код для вашего скрипта. Не нужно писать всё с нуля: выберите подходящий вариант и доработайте его сами или с помощью ИИ.

## Как использовать шаблон

1. Откройте функцию, сценарий или форму персональных данных, нажмите **«Добавить действие»** и выберите **Python Script**. В сценарии действие называется **«Python скрипт»**.
2. Когда вы откроете добавленное действие, появится окно **«Выберите шаблон Python Script»**. Нажмите на подходящий шаблон (1).
3. Нажмите **«Использовать шаблон»** (2). Код появится в редакторе.
4. Измените код под свою задачу: вручную или с помощью кнопки **«Сгенерировать с ИИ»**.
5. Сохраните код и проверьте его тестом — см. [«Настройка и тестирование скрипта»](https://doc.nextbot.ru/functional/python-script/nastroika-i-testirovanie-skripta.md).

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-cd841817fb3f9562ef8d5dc7b7e498b6dff8d264%2Fpython-script-vybor-shablona.webp?alt=media" alt="Окно «Выберите шаблон Python Script»: список шаблонов, выбран «Базовый скрипт», внизу кнопка «Использовать шаблон»"><figcaption><p>Окно выбора шаблона. Цифры 1–2 соответствуют шагам 2 и 3</p></figcaption></figure>

## Доступные шаблоны

| Шаблон                             | Что делает                                                                                                                                                                                                                                                               | Пример бизнес-задачи                                                                                                                                         |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Базовый скрипт**                 | Содержит базовую структуру кода с входными аргументами `args`, логированием и переменной `result`.                                                                                                                                                                       | Магазину нужен нестандартный расчёт скидки по собственным правилам. Базовый скрипт — отправная точка для него.                                               |
| **Вернуть результат в AI**         | Передаёт данные ИИ-модели через `tool_result`. Ответ клиенту формулирует модель.                                                                                                                                                                                         | Агент проверяет статус заказа во внешней системе и на основе полученных данных самостоятельно формулирует ответ клиенту.                                     |
| **Отправить сообщение напрямую**   | Отправляет клиенту готовый текст через `send_message`, без ИИ-модели.                                                                                                                                                                                                    | После оформления заявки клиент автоматически получает сообщение с номером заказа и условиями доставки.                                                       |
| **Промолчать**                     | Выполняет действия, например ставит теги и обновляет переменные, но ничего не отвечает клиенту (`silent`).                                                                                                                                                               | После получения контактов агент незаметно для клиента присваивает диалогу тег «Новый лид» и обновляет переменные.                                            |
| **Действия с диалогом**            | Набор примеров: пауза и снятие с паузы, блокировка, очистка диалога, переключение на другого агента, передача оператору, отложенные сообщения, теги, уведомление администратора. Чтобы оставить только нужный пример, попросите об этом ИИ.                              | Клиент просит связаться с ним завтра. Скрипт планирует сообщение на следующий день и добавляет тег «Повторное обращение».                                    |
| **Чтение и запись переменных**     | Получает значения пользовательских переменных и сохраняет изменения.                                                                                                                                                                                                     | Агент запоминает выбранную клиентом категорию товаров и бюджет, чтобы использовать их в дальнейшей консультации.                                             |
| **Интеграция с внешним API**       | Отправляет во внешнюю систему POST-запрос с данными и авторизацией.                                                                                                                                                                                                      | После сбора контактных данных агент автоматически создаёт заявку в CRM компании.                                                                             |
| **Квалификация лида**              | Начисляет баллы за телефон, бюджет и слово «купить», записывает оценку и статус клиента в переменные и ставит тег. Бюджет и текст со словом «купить» берёт из параметров функции. Если набралось 70 баллов и больше, ставит диалог на паузу и уведомляет администратора. | Агент оценивает клиента по бюджету и наличию телефона. Если баллов достаточно, менеджер получает уведомление.                                                |
| **Проверка рабочего времени**      | В нерабочее время отвечает автосообщением и планирует напоминание на начало рабочего дня. В рабочее время ответ формулирует ИИ-модель.                                                                                                                                   | Клиент пишет в салон ночью. Агент сообщает, что менеджер ответит утром, и планирует напоминание на начало рабочего дня.                                      |
| **Валидация контактных данных**    | Проверяет и приводит к единому формату телефон и e-mail, записывает их в поля формы (`form_data`).                                                                                                                                                                       | Перед созданием заявки агент проверяет телефон и e-mail клиента и приводит их к единому формату для передачи в CRM.                                          |
| **Извлечение данных из сообщения** | Находит в тексте телефон, e-mail или номер заказа с помощью регулярных выражений и сохраняет значения в переменные.                                                                                                                                                      | Клиент пишет: «Проверьте заказ №45821, моя почта — <example@mail.ru>». Скрипт извлекает номер заказа и e-mail для дальнейшей обработки.                      |
| **Отправить галерею файлов**       | Отправляет несколько изображений и документ одним сообщением через `send_message`.                                                                                                                                                                                       | Агент магазина мебели отправляет клиенту фотографии доступных моделей диванов и PDF-каталог с характеристиками.                                              |
| **База знаний (FAQ)**              | Ищет ответ по ключевым словам и отправляет его напрямую либо передаёт вопрос языковой модели.                                                                                                                                                                            | Клиент спрашивает об условиях возврата товара. Если в шаблоне найден подходящий ответ, агент отправляет его без дополнительного обращения к языковой модели. |
| **Расчёт стоимости заказа**        | Рассчитывает сумму заказа, скидку и доставку, возвращает клиенту разбивку стоимости.                                                                                                                                                                                     | Клиент заказывает пять товаров. Скрипт рассчитывает общую стоимость с учётом скидки за объём и стоимости доставки.                                           |

{% hint style="warning" %}
**У части шаблонов есть условия работы:**

* **«Валидация контактных данных»** — только в форме персональных данных: в функции и сценарии полей формы нет.
* **«Действия с диалогом»** — передача оператору работает только с Битрикс24. Если он не подключён, действие пропускается.
* **«Действия с диалогом»** и **«Квалификация лида»** уведомляют администратора, только если настроен канал в разделе [«Админу в мессенджер»](https://doc.nextbot.ru/functional/functions/sending-result/adminu-v-messendzher.md). Иначе уведомление пропускается.
* **«Чтение и запись переменных»**, **«Квалификация лида»**, **«Извлечение данных из сообщения»** — переменные, в которые пишет скрипт, нужно заранее создать в агенте с теми же именами, что в коде шаблона. Как это сделать — в статье [«Создание и редактирование переменных»](https://doc.nextbot.ru/functional/setting-up-agent/polzovatelskie-peremennye/sozdanie-i-redaktirovanie-peremennykh.md).
* **«Квалификация лида»** — ещё нужны параметры функции `budget` и `message_text`: из них шаблон берёт бюджет и текст, в котором ищет слово «купить». Как создать параметры — в статье [«Параметры функций»](https://doc.nextbot.ru/functional/functions/function-parameters.md).
  {% endhint %}

## Как адаптировать шаблон под свою задачу

Шаблоны показывают общую логику работы Python Script. Меняйте условия, добавляйте действия, подставляйте свои параметры.

Чаще всего в шаблоне меняют:

* тексты сообщений клиенту и администратору;
* названия параметров, переменных и тегов — на те, что есть в вашем агенте;
* числа и условия: баллы, рабочие часы и часовой пояс, размер скидки;
* адрес внешнего API и ключ к нему. Где хранить ключ — в статье [«Создание Python-скриптов с помощью ИИ»](https://doc.nextbot.ru/functional/python-script/sozdanie-python-skriptov-s-pomoshchyu-ii.md#gde-khranit-klyuchi-i-tokeny), раздел «Где хранить ключи и токены».

Например, шаблон **«Квалификация лида»** начисляет баллы за телефон, бюджет и слово «купить». Для вашего бизнеса важно ещё, сколько филиалов у клиента.

Чтобы изменить логику, нажмите **«Сгенерировать с ИИ»** и отправьте запрос:

> Доработай текущий скрипт квалификации лида. Добавь оценку количества филиалов клиента: 1 филиал — 0 баллов, от 2 до 5 — 10 баллов, больше 5 — 20 баллов. Если итоговая оценка 70 баллов или больше, присвой диалогу тег «Приоритетный клиент». Сохрани остальные условия существующего скрипта.

ИИ предложит изменения, которые можно проверить и применить в редакторе. Пока вы не нажали **«Сохранить»**, изменения не влияют на работу агента.

Подробнее о работе с ИИ — в статье [«Создание Python-скриптов с помощью ИИ»](https://doc.nextbot.ru/functional/python-script/sozdanie-python-skriptov-s-pomoshchyu-ii.md).

{% hint style="info" %}
Если ни один шаблон не подходит, выберите **«Базовый скрипт»** и опишите свою задачу ИИ-помощнику. Он напишет код под вашу задачу.
{% endhint %}

## Проверка перед запуском

Готовый шаблон не гарантирует, что скрипт будет правильно работать в вашем проекте. Перед запуском проверьте:

* **Входные данные.** Все необходимые параметры и переменные доступны скрипту.
* **Условия выполнения.** Логика соответствует вашему бизнес-процессу.
* **Результат.** Скрипт возвращает нужные данные или выполняет необходимые действия.
* **Обработка ошибок.** Если данные отсутствуют или внешний сервис недоступен, скрипт возвращает понятный `result`.

Как запустить тест и что проверить кроме удачного случая — в статье [«Настройка и тестирование скрипта»](https://doc.nextbot.ru/functional/python-script/nastroika-i-testirovanie-skripta.md). Если тест завершился ошибкой, попросите ИИ исправить код — см. [«Создание Python-скриптов с помощью ИИ»](https://doc.nextbot.ru/functional/python-script/sozdanie-python-skriptov-s-pomoshchyu-ii.md).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.nextbot.ru/functional/python-script/shablony-python-script.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
