> 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/spravochnik-python-script-v2.md).

# Как устроен Python-скрипт

Справка по Python-скрипту в Nextbot: что приходит в args, что можно вернуть в result, как Nextbot это обработает, библиотеки и ограничения.

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

Если вы только начинаете, сначала прочитайте [«Настройка и тестирование скрипта»](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).

## Как скрипт получает данные и отдаёт результат

Перед запуском Nextbot кладёт все входные данные в словарь `args`: параметры функции, данные диалога, переменные, данные формы. Ваш код читает из `args` нужные поля и делает свою работу. Итог он записывает в переменную `result`: её Nextbot забирает после выполнения и решает, что делать дальше.

Минимальный рабочий скрипт:

```python
order_id = args.get("order_id")
result = f"Заказ {order_id} принят"
```

## Входные данные: args

Читайте любое поле через `args.get("ключ")`. Если поля нет, вы получите `None`, а не ошибку, и сможете подставить значение по умолчанию:

```python
city = args.get("city") or "Москва"
```

{% hint style="warning" %}
Не обращайтесь к полям через `args["ключ"]`. Если такого ключа нет, скрипт завершится с ошибкой `KeyError`.
{% endhint %}

### Параметры функции

Если скрипт запускается из функции, параметры, которые вы задали в её настройках, приходят под своими именами. Например, для параметров `name` и `city`:

```python
name = args.get("name") or ""
city = args.get("city") or "Москва"
```

В сценарии и в форме персональных данных параметров функции нет: там доступны только системные поля и переменные.

### Системные поля

Nextbot добавляет в `args` данные о диалоге, клиенте и подключённых сервисах. Набор зависит от канала связи и подключённых CRM: если поле для диалога недоступно, его просто нет в `args`. Поэтому и здесь используйте `args.get(...)` и проверяйте значение на `None`.

<details>

<summary>Дата и время</summary>

| Поле                      | Что содержит                                                         |
| ------------------------- | -------------------------------------------------------------------- |
| `dateStringCreatedDialog` | Дата и время создания диалога, текстом в формате `ДД.ММ.ГГГГ, ЧЧ:ММ` |
| `dateUonCreatedDialog`    | Дата и время создания диалога в формате `ГГГГ-ММ-ДД ЧЧ:ММ:СС`        |
| `dateStringUseFunction`   | Дата и время запуска скрипта, текстом                                |
| `dateUonUseFunction`      | Дата и время запуска скрипта в формате `ГГГГ-ММ-ДД ЧЧ:ММ:СС`         |

</details>

<details>

<summary>Диалог и пользователь</summary>

| Поле                  | Что содержит                                                                                                                                                                                                     |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messenger`           | Канал, из которого пришло обращение                                                                                                                                                                              |
| `dialogId`            | ID диалога                                                                                                                                                                                                       |
| `chatId`              | ID чата                                                                                                                                                                                                          |
| `userId`              | ID пользователя                                                                                                                                                                                                  |
| `nameUser`            | Имя пользователя в мессенджере                                                                                                                                                                                   |
| `phoneNumber`         | Номер телефона                                                                                                                                                                                                   |
| `phoneNumberWhatsapp` | Номер телефона из WhatsApp                                                                                                                                                                                       |
| `link`                | Ссылка на диалог в Nextbot                                                                                                                                                                                       |
| `linkInUserMessenger` | Ссылка на пользователя в мессенджере                                                                                                                                                                             |
| `agentHash`           | ID агента                                                                                                                                                                                                        |
| `messageId`           | Числовой ID последнего сообщения клиента; между диалогами не повторяется                                                                                                                                         |
| `triggerMessage`      | Текст сообщения, которое запустило скрипт. В функции — текущее сообщение клиента. В сценарии — сообщение клиента, менеджера, ответ агента или уведомление, в зависимости от триггера. Если текста нет — `"none"` |
| `fullDialog`          | Полный текст диалога                                                                                                                                                                                             |
| `assistantMessage`    | Последний ответ агента                                                                                                                                                                                           |
| `errorMessage`        | Последняя ошибка отправки сообщения                                                                                                                                                                              |

</details>

<details>

<summary>UTM-метки и виджет на сайте</summary>

| Поле          | Что содержит                                                              |
| ------------- | ------------------------------------------------------------------------- |
| `linkWidget`  | Адрес страницы сайта, на которой открыт виджет                            |
| `start`       | Параметр `start` из адреса страницы с виджетом или с iframe «Чат на сайт» |
| `utmSource`   | `utm_source` из адреса страницы с виджетом                                |
| `utmMedium`   | `utm_medium` из адреса страницы с виджетом                                |
| `utmCampaign` | `utm_campaign` из адреса страницы с виджетом                              |
| `utmContent`  | `utm_content` из адреса страницы с виджетом                               |
| `utmTerm`     | `utm_term` из адреса страницы с виджетом                                  |

</details>

<details>

<summary>Файлы от клиента</summary>

| Поле                   | Что содержит                            |
| ---------------------- | --------------------------------------- |
| `userImageLinks`       | Ссылки на все изображения клиента       |
| `lastUserImageLink`    | Ссылка на последнее изображение клиента |
| `userVideoLinks`       | Ссылки на все видео клиента             |
| `lastUserVideoLink`    | Ссылка на последнее видео клиента       |
| `lastUserDocumentLink` | Ссылка на последний документ клиента    |

</details>

<details>

<summary>Telegram и MAX</summary>

| Поле                  | Что содержит                             |
| --------------------- | ---------------------------------------- |
| `telegramStartParams` | Параметры из команды `/start` в Telegram |
| `telegramUserName`    | Имя пользователя в Telegram              |
| `maxStartParams`      | Параметры из команды `/start` в MAX Bot  |

</details>

<details>

<summary>Битрикс24</summary>

| Поле                     | Что содержит                                  |
| ------------------------ | --------------------------------------------- |
| `bitrixToken`            | Токен штатного подключения к Битрикс24        |
| `bitrixDomain`           | Адрес портала, например `company.bitrix24.ru` |
| `bitrixEntityId`         | ID сделки или лида                            |
| `bitrixEntityLink`       | Ссылка на сделку или лид                      |
| `bitrixContactFirstName` | Имя контакта                                  |
| `bitrixContactLastName`  | Фамилия контакта                              |
| `bitrixPhoneNumber`      | Телефон контакта                              |
| `bitrixContactEmail`     | E-mail контакта                               |

</details>

<details>

<summary>amoCRM</summary>

| Поле                  | Что содержит                                 |
| --------------------- | -------------------------------------------- |
| `amoToken`            | Токен штатного подключения к amoCRM          |
| `amoDomain`           | Адрес аккаунта, например `company.amocrm.ru` |
| `amoDealId`           | ID сделки                                    |
| `amoDealLink`         | Ссылка на сделку                             |
| `amoSourceName`       | Источник сделки                              |
| `amoContactFirstName` | Имя контакта                                 |
| `amoContactLastName`  | Фамилия контакта                             |
| `amoContactPhone`     | Телефон контакта                             |
| `amoContactEmail`     | E-mail контакта                              |

</details>

<details>

<summary>Kommo</summary>

| Поле                    | Что содержит                                 |
| ----------------------- | -------------------------------------------- |
| `kommoToken`            | Токен штатного подключения к Kommo           |
| `kommoDomain`           | Адрес аккаунта, например `company.kommo.com` |
| `kommoDealId`           | ID сделки                                    |
| `kommoDealLink`         | Ссылка на сделку                             |
| `kommoSourceName`       | Источник сделки                              |
| `kommoContactFirstName` | Имя контакта                                 |
| `kommoContactLastName`  | Фамилия контакта                             |
| `kommoPhoneNumber`      | Телефон контакта                             |
| `kommoContactEmail`     | E-mail контакта                              |

</details>

<details>

<summary>Авито и Avito Pro</summary>

| Поле                     | Что содержит                                                                                                                        |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `avitoAdId`              | ID объявления                                                                                                                       |
| `linkAdAvito`            | Ссылка на объявление                                                                                                                |
| `nameAdAvito`            | Название объявления в Avito Pro                                                                                                     |
| `avitoAdRegion`          | Регион объявления                                                                                                                   |
| `locationAvito`          | Локация                                                                                                                             |
| `linkDialogAvito`        | Ссылка на диалог в Авито                                                                                                            |
| `avitoClientId`          | Числовой ID клиента в Авито. Одинаков во всех чатах клиента, в отличие от `userId` и `chatId`, которые относятся к конкретному чату |
| `avitoProAccountName`    | Имя аккаунта Avito Pro                                                                                                              |
| `avitoProSpecialistName` | Имя сотрудника Avito Pro, который ведёт диалог                                                                                      |
| `avitoProManagers`       | Менеджеры компании в чате Avito Pro, имена через запятую                                                                            |

</details>

<details>

<summary>Instagram</summary>

| Поле                | Что содержит                             |
| ------------------- | ---------------------------------------- |
| `instagramSource`   | Откуда сообщение: `direct` или `comment` |
| `instagramPostLink` | Ссылка на пост                           |

</details>

<details>

<summary>Salebot и Wazzup</summary>

| Поле                 | Что содержит              |
| -------------------- | ------------------------- |
| `platformIdSalebot`  | ID платформы Salebot      |
| `wazzupChannelId`    | ID канала Wazzup          |
| `wazzupContactName`  | Имя контакта в Wazzup     |
| `wazzupContactPhone` | Телефон контакта в Wazzup |

</details>

### Запросы в CRM штатным подключением

Если к агенту подключены [Битрикс24](https://doc.nextbot.ru/functional/functions/sending-result/bitrix24.md), [amoCRM](https://doc.nextbot.ru/functional/functions/sending-result/amocrm.md) или [Kommo](https://doc.nextbot.ru/functional/functions/sending-result/kommo.md), скрипт может обращаться к CRM через это подключение. Токен и адрес уже лежат в `args`, свой вебхук не нужен, а токен Nextbot обновляет сам.

Если CRM к агенту не подключена, в полях токена и адреса будет строка `"none"`. Проверяйте это и возвращайте понятную причину, иначе запрос уйдёт на несуществующий адрес.

Пример: скрипт создаёт сделку в Битрикс24.

```python
import requests

domain = args.get("bitrixDomain")
token = args.get("bitrixToken")

if "none" in (domain, token) or not domain or not token:
    result = "Битрикс24 не подключён к агенту"
else:
    response = requests.post(
        f"https://{domain}/rest/crm.deal.add.json",
        params={"auth": token},
        json={"fields": {"TITLE": "Заявка из чата"}},
        timeout=20,
    )
    data = response.json()
    result = data.get("error_description") or f"Сделка {data.get('result')} создана"
```

Для amoCRM запросы идут на `https://{amoDomain}/api/v4/...` с заголовком `Authorization: Bearer {amoToken}`. Для Kommo — то же самое с `kommoDomain` и `kommoToken`.

Свой вебхук нужен, только если CRM к агенту не подключена или скрипт работает с другим порталом.

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

[Пользовательские переменные](https://doc.nextbot.ru/functional/setting-up-agent/polzovatelskie-peremennye.md) приходят в `args["variables"]` двумя словарями:

* `agent` — переменные агента;
* `dialog` — переменные диалога.

```python
variables = args.get("variables") or {}

agent_vars = variables.get("agent") or {}
dialog_vars = variables.get("dialog") or {}

lead_score = dialog_vars.get("lead_score") or 0
client_name = dialog_vars.get("ClientName") or ""
```

Здесь скрипт берёт из переменных диалога оценку клиента и его имя. Как записать переменные из скрипта — в разделе «Действия в Nextbot» ниже, поле `variables`.

### Данные формы: form\_data

Словарь `form_data` есть только у скрипта, который обрабатывает [форму персональных данных](https://doc.nextbot.ru/functional/functions/sending-result/forma-personalnykh-dannykh.md). В нём лежат поля, которые заполнил клиент:

```python
form = dict(args.get("form_data") or {})

phone = form.get("phone")
email = form.get("email")
```

Так можно проверить телефон и e-mail клиента и исправить формат, прежде чем данные сохранятся.

## Результат: result

Всё, что нужно передать Nextbot, скрипт кладёт в переменную `result`. Есть два способа это сделать.

### Простой результат

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

```python
result = "Заказ №123 найден, статус: в пути"
```

```python
result = {"status": "ok", "eta_days": 3}
```

Подходит, когда скрипту нужно только сообщить ИИ-модели данные.

### Структурированный результат

Словарь со служебными полями: каждое поле — команда для Nextbot. Например, отправить клиенту сообщение и добавить тег:

```python
result = {
    "send_message": "Ваша заявка принята!",
    "tags": ["new_lead"],
}
```

Все служебные поля необязательные: используйте только нужные. Ключи, которых нет в списке служебных полей, Nextbot игнорирует. Полный список — в разделе «Действия в Nextbot» ниже.

### Присваивайте result на каждой ветке

Если в коде есть условия или обработка ошибок, задайте `result` в каждой ветке `if/else` и `try/except`. Иначе в одной из веток скрипт завершится без результата.

```python
try:
    quantity = int(args.get("quantity") or 0)
except (TypeError, ValueError):
    quantity = 0

if quantity > 0:
    result = {"total": quantity * 1500}
else:
    result = "Количество должно быть больше нуля"
```

Параметр `quantity` может прийти строкой, например `"3"`, поэтому код сначала приводит его к числу через `int(...)`. Без этого сравнение `quantity > 0` завершится ошибкой.

## Действия в Nextbot

Служебные поля структурированного результата:

| Поле                      | Тип значения       | Что делает                                                                                                                                                                                                                                                     |
| ------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tool_result`             | Строка             | Результат для ИИ-модели в функции: модель получит его и ответит клиенту. В форме попадает в диалог вместе с отчётом об отправке формы. В сценарии модели не уходит, см. раздел «Чем отличаются функция, сценарий и форма»                                      |
| `send_message`            | Строка или словарь | Отправляет клиенту готовое сообщение, без генерации ИИ-моделью. В словаре можно передать текст и `image`, `document`, `video`, `audio`, `buttons`, `files`, `sequence`                                                                                         |
| `info_message`            | Строка             | Добавляет служебную запись в историю диалога                                                                                                                                                                                                                   |
| `system_message`          | Строка             | Добавляет в диалог контекст для ИИ-модели с тегом `python_script_context`. Клиент его не видит                                                                                                                                                                 |
| `variables`               | Словарь            | Записывает пользовательские переменные. Ключи плоские, без деления на `agent` и `dialog`: область Nextbot определяет сам. Значение записывается как есть, а переменная должна быть заранее создана                                                             |
| `form_data`               | Словарь            | Обновляет поля формы персональных данных. Работает только в форме                                                                                                                                                                                              |
| `silent`                  | `True` / `False`   | Выполняет остальные действия и ничего не отвечает клиенту                                                                                                                                                                                                      |
| `pause`                   | `True` / `False`   | Ставит диалог на паузу                                                                                                                                                                                                                                         |
| `resume`                  | `True` / `False`   | Снимает диалог с паузы                                                                                                                                                                                                                                         |
| `block_user`              | `True` / `False`   | Блокирует пользователя. Завершающее действие: ответ клиенту не отправляется                                                                                                                                                                                    |
| `clear_dialog`            | `True` / `False`   | Очищает и перезапускает диалог. Завершающее действие: ответ клиенту не отправляется                                                                                                                                                                            |
| `switch_agent`            | Строка или словарь | Переключает диалог на другого агента по его `agent_hash`                                                                                                                                                                                                       |
| `handoff_to_operator`     | `True` / `False`   | Передаёт диалог оператору. Работает только с Битрикс24: если он не подключён, действие пропускается                                                                                                                                                            |
| `delayed_message`         | Словарь            | Планирует отложенное сообщение                                                                                                                                                                                                                                 |
| `cancel_delayed_messages` | `True` / `False`   | Отменяет все отложенные сообщения диалога                                                                                                                                                                                                                      |
| `notify_admin`            | Словарь            | Отправляет уведомление администратору. Без `messager` — во все настроенные каналы администратора: `telegram`, `whatsapp`, `max`, `maxbot`, `telegram_personal`. С `messager` — только в указанный канал. Если ни один канал не настроен, действие пропускается |
| `tags`                    | Список строк       | Добавляет теги к диалогу. Существующие теги не удаляет                                                                                                                                                                                                         |

Каналы для уведомлений администратору настраиваются в разделе [«Админу в мессенджер»](https://doc.nextbot.ru/functional/functions/sending-result/adminu-v-messendzher.md).

## Примеры действий

### Передать результат ИИ-модели

Агент сам сформулирует ответ клиенту с учётом этих данных и контекста диалога.

```python
result = {
    "tool_result": "Заказ №45821 находится в доставке."
}
```

### Отправить сообщение напрямую

Текст уже известен, и генерация не нужна: сообщение уйдёт клиенту как есть, ИИ-модель не вызывается.

```python
result = {
    "send_message": "Ваша заявка принята! Менеджер свяжется с вами."
}
```

### Отправить файлы и кнопки

`send_message` в виде словаря отправляет текст вместе с изображением, документом, видео, аудио и кнопками. Файлы передаются ссылками.

```python
result = {
    "send_message": {
        "text": "Вот материалы по заявке",
        "document": "https://example.com/contract.pdf",
        "buttons": ["Всё понятно", "Есть вопрос"],
    }
}
```

Чтобы отправить несколько файлов подряд, используйте список `files`. У каждого файла укажите тип в `kind`: `image`, `document`, `video` или `voice`. Для `voice` ссылка передаётся в `audio`, для остальных — в `url`.

```python
result = {
    "send_message": {
        "text": "Отправляю файлы",
        "files": [
            {"kind": "image", "url": "https://example.com/photo.jpg", "caption": "Фото"},
            {"kind": "document", "url": "https://example.com/file.pdf", "caption": "Договор"},
            {"kind": "voice", "audio": "https://example.com/voice.mp3"},
        ],
    }
}
```

Для полного контроля над порядком и видом сообщений есть поле `sequence` — в нём передаётся список элементов во внутреннем формате сообщений Nextbot.

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

```python
result = {
    "variables": {
        "lead_score": 8,
        "lead_checked": True,
    },
    "tool_result": "Клиент прошёл квалификацию.",
}
```

Скрипт сохраняет оценку клиента и отметку о квалификации, а затем передаёт результат ИИ-модели.

{% hint style="info" %}
Переменные `lead_score` и `lead_checked` должны быть заранее созданы в [пользовательских переменных](https://doc.nextbot.ru/functional/setting-up-agent/polzovatelskie-peremennye.md) агента. Если переменной нет, Nextbot пропустит её запись.
{% endhint %}

### Выполнить действия без ответа клиенту

```python
result = {
    "silent": True,
    "variables": {"lead_checked": True},
    "tags": ["checked"],
}
```

Скрипт обновит переменную и добавит тег, но клиент ничего не получит.

### Уведомить администратора

Основной вариант — без `messager`: уведомление уйдёт во все каналы администратора, которые настроены у агента. Такой скрипт можно перенести в другого агента без правок.

```python
result = {
    "notify_admin": {"message": "Клиент просит связаться с ним по телефону."},
    "tool_result": "Администратор уведомлён.",
}
```

Если уведомление нужно только в один канал, укажите его в `messager`:

```python
result = {
    "notify_admin": {
        "messager": "telegram",
        "message": "Клиент просит связаться с ним по телефону.",
    }
}
```

### Запланировать отложенное сообщение

Например, напомнить клиенту о заявке через час:

```python
result = {
    "send_message": "Заявка принята! Менеджер свяжется с вами.",
    "delayed_message": {
        "message": "Напоминаем о вашей заявке. Чем можем помочь?",
        "delay_ms": 60 * 60 * 1000,
        "delete_after_user_message": True,
        "restriction_policy": "next_window_start",
    },
    "tags": ["follow_up_scheduled"],
}
```

Поля `delayed_message`:

* `message` — текст сообщения;
* `delay_ms` — задержка в миллисекундах: `60 * 60 * 1000` — это один час;
* `delete_after_user_message` — если `True`, сообщение отменится, когда клиент напишет раньше;
* `restriction_policy` — что делать, если время отправки выпадает на нерабочее время агента:
  * `ignore_schedule` — отправить в любом случае;
  * `do_not_send` — не отправлять;
  * `next_window_start` — перенести на начало ближайшего рабочего окна;
  * `next_day_at_time` — перенести на следующий день, на время из `restriction_policy_time`, например `"09:00"`.

Отменить все запланированные сообщения диалога:

```python
result = {"cancel_delayed_messages": True}
```

{% hint style="warning" %}
Отложенные сообщения не работают в виджете, iframe и окне «Чат на сайт».
{% endhint %}

### Передать диалог оператору

```python
result = {
    "handoff_to_operator": True,
    "pause": True,
    "tags": ["operator_handoff"],
    "notify_admin": {"message": "Клиент запросил оператора."},
}
```

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

{% hint style="warning" %}
`handoff_to_operator` работает только при подключённом [Битрикс24](https://doc.nextbot.ru/functional/functions/sending-result/bitrix24.md).
{% endhint %}

### Переключить на другого агента

```python
result = {
    "switch_agent": {"agent_hash": "ID_агента"},
    "tags": ["switched_by_python"],
}
```

Замените значение `agent_hash` на ID нужного агента. Можно передать и короткую форму: `"switch_agent": "ID_агента"`.

## Что получит клиент: приоритет ответа

Если в `result` несколько служебных полей, Nextbot решает, что отправить клиенту, в таком порядке:

1. **Задан `send_message`** — сообщение уходит клиенту напрямую, ИИ-модель не вызывается.
2. **Задан `silent: True`, `block_user: True` или `clear_dialog: True`** — клиенту ничего не отправляется, ИИ-модель не вызывается.
3. **Во всех остальных случаях** ИИ-модель получает `tool_result` и формирует ответ. Так работает в функции; в сценарии `tool_result` модели не уходит.
4. **Переменные, теги, пауза, уведомления, отложенные сообщения и служебные записи применяются всегда**, в любом из случаев выше.

Поэтому не задавайте `send_message` и `tool_result` одновременно в расчёте на два ответа: клиент получит только `send_message`.

## Чем отличаются функция, сценарий и форма

Скрипт работает одинаково во всех трёх местах, но входные данные разные, и результат обрабатывается по-разному.

|                         | Функция                                                    | Сценарий                                         | Форма персональных данных                                                                                        |
| ----------------------- | ---------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Параметры функции       | Есть: `args.get("имя")`                                    | Нет                                              | Нет                                                                                                              |
| Куда идёт `tool_result` | ИИ-модели как результат функции                            | Остаётся в журнале шага, ИИ-модели не уходит     | Весь `result` попадает в диалог служебным сообщением об отправке формы, и ИИ-модель видит его в следующем ответе |
| `form_data`             | Нет                                                        | Нет                                              | Есть: можно прочитать и изменить                                                                                 |
| Когда выполняется       | Когда ИИ-модель вызывает функцию, после интеграций функции | Когда срабатывает триггер, в порядке шагов ветки | Когда клиент отправил форму, до сохранения данных                                                                |

{% hint style="warning" %}
**В сценарии ИИ-модель не видит `tool_result`.** Чтобы агент учёл данные скрипта в ответе, верните их в `system_message` или поставьте после скрипта в той же ветке действие [«Добавить контекст в диалог»](https://doc.nextbot.ru/functional/functions/sending-result/dobavit-kontekst-v-dialog.md) со значением `{{system_data_pythonScriptResult}}`.
{% endhint %}

{% hint style="warning" %}
**В функции скрипт выполняется после интеграций**: CRM, календаря, счёта и других. Поэтому результат скрипта и записанные им переменные в этом же вызове в интеграции не попадут. Если в CRM нужно значение, которое считает скрипт, разделите работу на две функции. Первая считает и записывает результат в переменную диалога. Вторая оформляет заказ и берёт значение для поля CRM из этой переменной.
{% endhint %}

## Библиотеки

Скрипту доступна стандартная библиотека Python: `json`, `re`, `datetime`, `math` и другие модули подключаются обычным `import`.

```python
import json
import re
from datetime import datetime, timezone

import requests
```

Кроме неё установлены внешние пакеты:

| Пакет                 | Для чего                                                   |
| --------------------- | ---------------------------------------------------------- |
| `requests`            | HTTP-запросы к внешним сервисам                            |
| `curl_cffi==0.16.3`   | HTTP-запросы, которые сервер принимает за запросы браузера |
| `jsonpath-ng`         | Поиск и извлечение данных из JSON                          |
| `jsonschema`          | Проверка структуры JSON                                    |
| `python-dateutil`     | Разбор и вычисления с датами                               |
| `pytz`                | Часовые пояса                                              |
| `supabase==1.2.0`     | Работа с Supabase                                          |
| `gspread==5.12.0`     | Работа с Google Таблицами                                  |
| `oauth2client==4.1.3` | Авторизация в сервисах Google                              |

Установить пакет из скрипта нельзя. Если нужной библиотеки нет, запросите её — как это сделать, описано в статье [«Запрос библиотеки»](https://doc.nextbot.ru/functional/python-script/zapros-biblioteki.md).

## Внешние API

Прежде чем писать скрипт, проверьте, не хватит ли [Custom API](https://doc.nextbot.ru/functional/functions/sending-result/custom-api.md): чтобы просто отправить данные во внешнюю систему, код не нужен. Скрипт пригодится, когда ответ нужно обработать, сделать несколько запросов подряд или посчитать что-то по полученным данным.

```python
import requests

try:
    response = requests.get(
        "https://jsonplaceholder.typicode.com/posts/1",
        timeout=10,
    )
    response.raise_for_status()
    data = response.json()

    result = {
        "tool_result": f"Заголовок: {data.get('title')}"
    }

except requests.RequestException as e:
    print(f"Ошибка API: {e}")
    result = {
        "tool_result": "Не удалось получить данные из внешнего сервиса."
    }
```

Здесь:

* `timeout=10` ограничивает ожидание ответа десятью секундами. Задавайте таймаут в каждом запросе: без него зависший сервис займёт всё время выполнения скрипта;
* `raise_for_status()` превращает ответ с ошибкой, например 404 или 500, в исключение;
* `try/except` перехватывает сбой, и скрипт всё равно возвращает понятный `result`.

## Ограничения

| Что                               | Ограничение                                                    |
| --------------------------------- | -------------------------------------------------------------- |
| Время выполнения                  | До 285 секунд                                                  |
| Вывод `print()` в stdout и stderr | До 256 КБ каждый                                               |
| Размер `result`                   | До 1 МБ                                                        |
| Временные файлы                   | До 50 МБ                                                       |
| Shell-команды и `subprocess`      | Запрещены: вызов завершится ошибкой                            |
| Библиотеки                        | Только стандартная библиотека и пакеты из раздела «Библиотеки» |

## Логи

Чтобы понять, что происходит внутри скрипта, выводите сообщения через `print()`. Они попадут в лог выполнения.

```python
import sys

print("Скрипт запущен")

name = args.get("name") or ""
if not name:
    print("Имя не передано", file=sys.stderr)

result = {"tool_result": f"Имя: {name or 'не указано'}"}
```

Обычный `print()` пишет в stdout, а `print(..., file=sys.stderr)` — в stderr. Второй удобно использовать для ошибок и предупреждений: их проще найти в логе.

{% hint style="warning" %}
Не выводите в логи пароли, API-ключи, токены и другие секретные данные. Если передаёте лог нейросети, сначала удалите из него персональные данные клиентов.
{% endhint %}

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

| Что происходит                                  | Почему                                                                                                | Как исправить                                                                                                                         |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Не указан `codeId`                              | Скрипт не сохранён или не привязан к действию                                                         | Откройте настройки Python Script, вставьте код и сохраните                                                                            |
| `result` не определён                           | Не во всех ветках кода задан `result`                                                                 | Задайте `result` в каждой ветке `if/else` и `try/except`                                                                              |
| `KeyError: 'phone'`                             | Скрипт обращается к отсутствующему ключу через `args["phone"]`                                        | Используйте `args.get("phone")`                                                                                                       |
| `TypeError` при сравнении чисел                 | Параметр пришёл строкой, например `"3"`                                                               | Приведите значение к числу: `int(...)` или `float(...)`                                                                               |
| Сообщение клиенту не отправилось                | Вместо `send_message` задан `tool_result`                                                             | Проверьте структуру `result`                                                                                                          |
| ИИ-модель в сценарии не видит результат скрипта | В сценарии `tool_result` ИИ-модели не уходит                                                          | Верните `system_message` или добавьте после скрипта «Добавить контекст в диалог» с `{{system_data_pythonScriptResult}}`               |
| В CRM не попало то, что посчитал скрипт         | В функции интеграции выполняются раньше скрипта                                                       | Разделите на две функции: расчёт пишет результат в переменную, оформление берёт его из переменной                                     |
| Скрипт вернул «Битрикс24 не подключён к агенту» | В `bitrixToken` и `bitrixDomain` пришло `"none"`: Битрикс24 не подключён к этому агенту               | Подключите [Битрикс24](https://doc.nextbot.ru/functional/functions/sending-result/bitrix24.md) к агенту. То же для amoCRM и Kommo     |
| Переменная не обновляется                       | Переменной с таким ключом нет у агента                                                                | Создайте переменную в [пользовательских переменных](https://doc.nextbot.ru/functional/setting-up-agent/polzovatelskie-peremennye.md)  |
| Отложенное сообщение не пришло                  | Диалог идёт в виджете, iframe или окне «Чат на сайт», либо сработало ограничение `restriction_policy` | Проверьте канал и значение `restriction_policy`                                                                                       |
| `handoff_to_operator` не работает               | Не подключён Битрикс24                                                                                | Подключите [Битрикс24](https://doc.nextbot.ru/functional/functions/sending-result/bitrix24.md)                                        |
| Уведомление администратору не пришло            | У агента не настроен ни один канал администратора                                                     | Настройте канал в разделе [«Админу в мессенджер»](https://doc.nextbot.ru/functional/functions/sending-result/adminu-v-messendzher.md) |
| Ошибка при вызове `subprocess`                  | Shell-команды запрещены                                                                               | Используйте средства Python                                                                                                           |
| `SyntaxError`                                   | Пропущена скобка или кавычка, неверный отступ                                                         | Проверьте код или попросите ИИ найти ошибку                                                                                           |

Если не получается найти причину, скопируйте лог выполнения и передайте его ИИ вместе с кодом. Как это сделать — в статье [«Создание 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/spravochnik-python-script-v2.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.
