Функции (Инструменты бота) — полный гайд

Раздел «Функции» в проекте DOS AI. Путь: Проект → Функции (/projects/<id>/functions).

Подзаголовок раздела: «Инструменты, которые ИИ сам решает когда использовать».

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

🆕 Обновление каталога (2026-06-13). Шаблоны теперь сгруппированы по задаче: Уведомления владельцу (Telegram, почта), Запись на время (Calendar + движок окошек), Google Таблицы, Приём оплаты (Kaspi) (как работает), Поведение бота (теги, пауза дожимов, стоп-диалог), Фото и видео, Письмо клиенту (гайд). Что ещё изменилось:

• В модалке создания есть поиск по шаблонам — напишите «оплата», «запись», «уведомление».
• У каждого шаблона на карточке видно «цену входа» (сколько полей, сколько минут, что понадобится) и ссылку 📖 Инструкция.
• У шаблонных полей человеку показывается короткая подпись, а полная инструкция для ИИ спрятана в спойлер «Инструкция для ИИ».
• Проверить функцию можно прямо в мастере (кнопка «Проверить»), не закрывая его.
• Письмо клиенту через обычную почту теперь доступно как шаблон (см. «Письмо клиенту»); Gmail остался продвинутым вариантом.
• HTTP-запрос — это не шаблон, а путь «Своя интеграция по API» (для разработчика). См. Кастомные вебхуки.

Оглавление

1. Что такое функции и зачем они
2. Как бот ими пользуется (механика)
3. Страница «Функции»: весь интерфейс
4. Как создать функцию
5. Анатомия функции (из чего состоит)
6. Параметры — подробно
7. Каталог встроенных функций
8. Кастомные вебхуки: простой и продвинутый режим
9. Управление диалогом и лидом (теги, пауза, стоп, медиа, оплата)
10. Тестирование, версии, лог, импорт/экспорт
11. Связь функций с промптом бота
12. Лимиты и ограничения
13. Безопасность и приватность
14. Все статусы и состояния
15. Лучшие практики и чек-лист
16. FAQ и крайние случаи
17. Глоссарий

1. Что такое функции и зачем они

Функция (инструмент) — это действие, которое бот может выполнить во время диалога с клиентом. Сам по себе ИИ умеет только писать текст. Функции дают ему «руки»: записать клиента в календарь, добавить строку в Google-таблицу, выставить счёт на оплату, уведомить владельца в Telegram, поставить тег лиду и так далее.

Главная идея: вы не программируете «если клиент написал X — сделай Y». Вы просто описываете боту что умеет каждая функция и когда её вызывать, а ИИ сам решает в нужный момент диалога, какую функцию вызвать и с какими данными. Это принципиально отличается от жёстких сценариев-кнопок.

📌 Функция не создаёт лида. Карточку лида заводит статус лида, который бот ставит сам по ходу диалога — на уровне промпта, без функций. Функция «Уведомление владельцу» лишь сообщает вам о заявке; сам лид в CRM появляется из-за статуса. Для аналитики (диалоги/лиды/конверсия) функции тоже не нужны — она считается автоматически.

Пример. У стоматологии подключены две функции: «проверить свободное время» и «записать клиента». Клиент пишет «хочу на чистку завтра после обеда». Бот сам:

1. вызывает проверить свободное время на завтра,
2. получает свободные слоты,
3. предлагает клиенту «14:00 или 16:30?»,
4. когда клиент выбрал — вызывает записать клиента,
5. подтверждает: «Записала вас на завтра 14:00 ✅».

Никто не прописывал этот сценарий шагами. Бот связал функции сам, потому что у каждой было понятное описание.

Что важно понять с самого начала:

• Функция = пара «описание для ИИ (когда вызывать)» + «подключение (куда отправить данные)».
• Бот вызывает функцию, только если она включена и её описание подсказывает, что сейчас подходящий момент.
• Плохое описание = бот не вызывает функцию или вызывает не вовремя. Описание — самое важное поле.

2. Как бот ими пользуется (механика)

Простыми словами, что происходит под капотом на каждое сообщение клиента:

1. Сборка инструментов. Платформа берёт все включённые функции проекта и превращает их в «меню инструментов» для модели (формат OpenAI tools). Каждая функция = имя + описание + список параметров.
2. Решение модели. ИИ читает сообщение клиента, контекст диалога, системный промпт и это меню. Дальше он либо просто отвечает текстом, либо решает «здесь нужно вызвать функцию X с такими-то параметрами».
3. Выполнение. Если ИИ вызвал функцию, платформа выполняет реальное действие (запрос в Google Calendar, HTTP-запрос на ваш сервер, запись в таблицу и т.д.) и получает результат.
4. Возврат результата модели. Результат функции (успех/ошибка/данные) отдаётся обратно ИИ. Он смотрит на него и формулирует человеческий ответ клиенту на его основе.
5. Цепочка. За один ход бот может вызвать несколько функций подряд (например, сначала проверить слот, потом записать). Это «round-trip»: вызов → результат → следующее решение.

Где это работает (5 точек входа). Функции одинаково работают во всех местах, где отвечает ИИ:

• тест-чат в кабинете (песочница, без реальных списаний),
• боевой WhatsApp (и другие каналы через Wazzup, если появятся),
• боевой Telegram,
• ручная отправка сообщения оператором из диалога,
• переотправка упавшего ответа.

То есть если функция работает в тест-чате — она так же сработает в бою.

Что НЕ является функцией:

• База знаний (RAG). Документы и факты, которые вы загрузили в «Базу знаний», бот использует автоматически — это не вызов функции, контекст подмешивается сам. В логах вызовов вы можете встретить служебный kb_search, но настраивать его как функцию не нужно.
• Системный промпт. Это «характер и правила» бота, отдельная настройка в Настройки. Функции и промпт работают вместе (см. раздел 11).

3. Страница «Функции»: весь интерфейс

3.1 Шапка

• Заголовок: «Функции».
• Подзаголовок: «Инструменты, которые ИИ сам решает когда использовать».
• Кнопка «Импорт» — загрузить функции из JSON (см. 10.5).
• Кнопка «+ Новая функция» — создать новую (см. раздел 4). Становится неактивной при достижении лимита 20 функций.
• Счётчик функций использовано / 20. Меняет цвет: серый → жёлтый (осталось ≤2) → красный (лимит).

3.2 Строка статистики

Показывает по проекту: Всего, Активных (включённых), Подключено (с настроенным подключением), Типов, Цепочек.

3.3 Полоса готовности (Readiness)

Сводка состояния одной строкой:

• ✅ «Все функции готовы» — всё в порядке.
• ⚠️ Жёлтые предупреждения с количеством: «N с ошибками», «N не упомянуты в промпте», «N не протестированы». Это подсказки, а не блокировки.

3.4 Фильтры и поиск

• Чипы-категории: «Все» + по типам (Calendar, Sheets, Telegram, Email, Webhook, CRM и т.д.), у каждого счётчик.
• Поиск по названию функции.
• Чекбокс «Только включённые» — спрятать выключенные.

3.5 Баннер рассинхрона с промптом

Жёлтый баннер появляется, если в системном промпте упоминается функция, которой не существует (например, вы написали в промпте «вызови book_table», а функции с таким именем нет). Баннер:

• показывает каждое недостающее имя,
• предлагает «возможно, имелась в виду ...»,
• даёт кнопку «Создать» недостающую функцию в один клик,
• ссылку «Открыть промпт бота».

3.6 Карточка функции

Каждая функция — карточка. У неё два режима отображения:

Бизнес-режим (по умолчанию):

• иконка + имя + бейдж типа («Оплата», «Google Calendar» и т.д.) + статус + переключатель вкл/выкл;
• описание (до 2 строк);
• для встроенных — инфо о ресурсе («ID таблицы…», «Календарь…», «⚠ не задано» если не настроено);
• параметры в виде цветных пилюль (имя + тип + * если обязательный);
• бейдж здоровья (если тестировалась): процент успеха, статус последнего вызова;
• алерт об ошибке (если последние вызовы падали) с куском текста ошибки;
• нижняя строка: статус • тип подключения • число параметров • таймаут • бейдж цепочки (если в цепочке);
• кнопки: «Проверить», «Редактировать», меню «⋯».

Меню «⋯»: Попробовать в чате • Превью запроса • Дублировать • История версий • Лог вызовов • Экспорт как JSON • Восстановить предыдущую версию • переключить Dev/Бизнес режим • Удалить.

Dev-режим (переключается в меню) — техническая карта функции: HTTP-метод + URL, заголовки, JSON-схема параметров, готовая команда cURL с копированием, панель здоровья, таймлайн последних 5 вызовов, инлайн-форма редактирования.

3.7 Пустое состояние

Если функций нет:

• «Нет функций»,
• «Создайте первую функцию — ИИ будет сам решать когда её вызвать во время диалога»,
• три шага: «1. Создайте действие → 2. Укажите, куда отправить данные → 3. Бот сам вызовет, когда нужно»,
• кнопка «+ Новая функция».

3.8 Обновление в реальном времени

Список функций обновляется сам (realtime), без перезагрузки страницы. Если другая вкладка/сессия что-то изменила — вы увидите это сразу.

4. Как создать функцию

Нажмите «+ Новая функция». Открывается выбор пути:

Шаг 1 — Выбор пути

• «Из шаблона» — готовые обёртки: Google Sheets, Google Calendar, Telegram, Gmail, приём оплаты, медиа и т.д. Параметры уже настроены правильно, вам остаётся заполнить подключение. Рекомендуется в 90% случаев.
• «Кастомная» — свой запрос на любой сервер (вебхук). Для интеграции с вашей CRM, n8n, Zapier или собственным API.

Шаг 2 — Выбор системы (для шаблона)

Показываются группы: Google Sheets, Google Calendar, Gmail, Telegram уведомления, HTTP API, Сегментация лидов, Приём оплаты (Kaspi), Пауза дожимов, Остановить диалог, Отправка фото и видео. У каждой — иконка, описание, число шаблонов.

Шаг 3 — Выбор конкретного действия

Внутри группы — список шаблонов (например в Sheets: «Узнать структуру», «Прочитать», «Найти», «Добавить строку», «Обновить строку», «Удалить», «Раскрасить», «Создать лист»).

Шаг 4 — Мастер настройки (ActionWizard)

Один экран с четырьмя секциями:

1) «Когда боту это вызывать»

• Название (snake_case, только для кастомных; у шаблонов подставляется). Правило: ^[a-z][a-z0-9_]*$ — маленькие латинские буквы, цифры, _, начинается с буквы. Пример: create_appointment.
• Описание для AI — критическое поле, минимум 5 символов. Пишите с точки зрения бота: когда и зачем вызывать. Кнопка «Улучшить с ИИ» дорабатывает формулировку автоматически.

2) «Подключение»

• Для встроенных — специфичная настройка (ID таблицы и лист; ID календаря и рабочие часы; токен и chat_id Telegram; и т.д.). Показывается email сервисного аккаунта, которому надо дать доступ к таблице/календарю.
• Для кастомных вебхуков — URL, HTTP-метод, таймаут и сворачиваемые блоки: Авторизация, Заголовки, Параметры URL, Тело запроса, Маппинг ответа, Повторы, Пагинация (см. раздел 8).

3) «Что бот спросит у клиента» — конструктор параметров (см. раздел 6). Показывается только для кастомных вебхуков, где вы сами проектируете, какие данные бот собирает. У встроенных функций набор параметров уже задан шаблоном и менять его нельзя — поэтому отдельной секции нет: встроенную функцию достаточно включить (и при наличии — потыкать настройки в «Подключении»). Справочный список «что бот соберёт» для встроенных доступен read-only в блоке «Дополнительно».

4) «Дополнительно» (сворачиваемое) — триггеры, поведение при ошибке (fallback), цепочки. Для встроенных функций здесь же — read-only список параметров, заданных шаблоном.

Кнопка «Создать функцию» (или «Сохранить» при редактировании). При редактировании есть автосохранение со статусом «Сохранение… / Сохранено / Ошибка сохранения».

5. Анатомия функции (из чего состоит)

Каждая функция хранит набор полей. Самые важные для вас — первые три.

Имя — правила и подводные камни:

• только a-z, 0-9, _, начинается с буквы;
• уникально в рамках проекта (регистронезависимо);
• нельзя использовать зарезервированные слова языков программирования (if, for, function, await и ещё ~200) — система отклонит.

Тип действия (`action_type`) — все допустимые значения:
webhook, builtin_calendar, builtin_sheets, builtin_booking, builtin_telegram, builtin_email, builtin_whatsapp, builtin_crm, builtin_edu_crm, builtin_gmail, builtin_lead_meta, builtin_owner_payment, builtin_send_media.

6. Параметры — подробно

Параметр — это данные, которые бот соберёт у клиента в разговоре и передаст в функцию. Например: имя, телефон, дата, сумма. В конструкторе каждый параметр — карточка с номером.

6.1 Поля параметра

• Тип: String (Aa) / Number (#) / Boolean (да-нет) / Array (список []) / Object (объект {}). Для массива дополнительно указывается тип элементов.
• Обязательность: переключатель *« ОБЯЗ»** / «НЕОБЯЗ». Обязательный параметр бот будет добиваться у клиента, прежде чем вызвать функцию.
• Имя (snake_case).
• Описание — что бот спросит у клиента. Пишите как живой вопрос: «На какую дату вы хотите записаться?». От этого зависит, поймёт ли ИИ, что туда подставить.
• Enum (для строк) — фиксированный список допустимых значений через запятую: low, normal, high. ИИ выберет только из них.
• Перемещение (↑ ↓) и удаление (✕).

6.2 Подсказки для ИИ (делают функцию точнее)

У параметра можно задать (в шаблонах часто уже заданы):

• examples — примеры значений, помогают ИИ понять формат;
• minimum / maximum — границы для чисел;
• format — date, date-time, email;
• pattern — регулярное выражение (например дата ^\d{4}-\d{2}-\d{2}$).

6.3 Заблокированные параметры (locked) — «ШАБЛОН»

У шаблонных функций часть параметров помечена бейджем «ШАБЛОН» и заблокирована: их нельзя переименовать, удалить или сменить тип. Это сделано специально — они завязаны на встроенный обработчик (например start_time у записи в календарь). Описание у некоторых можно дополнить, структуру — нет. Не заблокированные параметры шаблона (например необязательное customer_name) редактировать можно.

6.4 Пустое состояние

Если параметров нет: «Параметры — данные, которые бот соберёт у клиента. Например: имя, телефон, дата, услуга.» Кнопка «+ Параметр».

7. Каталог встроенных функций

Ниже — встроенные шаблоны с параметрами и сценарием «когда использовать». * = обязательный, 🔒 = заблокирован (ШАБЛОН).

Config-поля (ID таблицы, ID календаря, токен и т.д.) вы заполняете один раз при настройке — ИИ их не видит. Параметры — то, что ИИ собирает у клиента в каждом вызове.

7.1 Google Sheets (builtin_sheets)

Требует доступа к таблице для сервисного аккаунта (его email показывается при настройке — дайте ему доступ «Редактор» к таблице). Config у всех: `spreadsheet_id` (ссылка на таблицу) + `sheet_name`* (лист, по умолчанию первый).

Про «защиту от двойной брони»: expected_current_value / expected_other_cell позволяют записать в слот «только если он ещё свободен». Если за это время слот успели занять — функция вернёт CELL_VALUE_CHANGED, и бот предложит другое время. Это спасает от ситуации, когда два клиента бронируют один слот одновременно.

Старые Sheets-шаблоны (скрыты в интерфейсе) заменены актуальными выше. Они работают у давних проектов для совместимости, но создавать новые функции из них нельзя — используйте 6 актуальных.

7.2 Google Calendar (builtin_calendar)

Config у всех: `calendar_id` * (primary или email календаря). Дополнительно: длительность слота, на сколько дней вперёд, рабочие часы/дни, минимальное предупреждение, перерывы между записями.

7.3 Gmail (builtin_gmail)

Отправляет письмо с рабочего Gmail-адреса. Требует подключённый Google Workspace с доступом для сервисного аккаунта. Config-полей нет.

`send_gmail`: to🔒 (можно несколько через запятую), `subject`🔒, body*🔒, html🔒 (оформление), cc🔒, reply_to🔒.

7.4 Telegram уведомления (builtin_telegram)

Шлёт уведомление в Telegram-чат (например владельцу о новой заявке). Config: `bot_token` , `chat_id` , `message_template` * (шаблон сообщения с подстановкой переменных). Параметров нет — сообщение собирается из шаблона.

Это типичный способ «уведомить владельца / передать оператору»: бот зовёт notify_telegram, и вам в Telegram падает заявка с данными клиента.

7.5 Своя интеграция по API (webhook)

Бот умеет дёргать ваш собственный сервис по HTTP (GET/POST) — получить данные с вашего сервера/CRM или отправить заявку во внешнюю систему. Это путь «Своя интеграция по API» в мастере создания функции: метод, URL, заголовки и параметры вы задаёте сами. Подробности — в разделе 8.

7.6 Сегментация лидов (builtin_lead_meta)

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

Теги управляются на странице «Теги» (там же описания, которые видит бот). Функции «добавить один тег» и «тип клиента» удалены 2026-06-13 — теги покрывают сегментацию.

7.7 Приём оплаты — Kaspi (builtin_owner_payment)

Бот выставляет клиенту счёт прямо в чате, клиент платит push-ом в Kaspi, деньги идут напрямую на вашу Kaspi-кассу (DOS их не хранит). Сначала подключите платежи в разделе «Платежи».

`create_payment_invoice`:

• amount_kzt*🔒 — сумма в тенге, целое, минимум 50;
• customer_phone*🔒 — номер клиента, привязанный к Kaspi (любой формат: +7 705…, 8705…);
• description*🔒 — за что платит (видно в Kaspi-push и чеке);
• customer_name — имя (необязательно, для истории).
• Config: catalog_description — описание по умолчанию для чека.

Клиенту приходит push в Kaspi, подтвердить нужно в течение ~30 минут. Подробно про ответы и ошибки — раздел 9.5.

7.8 Пауза дожимов (builtin_lead_meta)

`pause_followups` — клиент сказал «свяжусь сам в четверг» / «подумаю». Бот ставит автонапоминания на паузу, не выключая себя — в чате он продолжит отвечать, замолкает только авто-дожим.

• until🔒 — дата YYYY-MM-DD, до которой пауза. Пусто = пауза 3 дня.
• reason — причина для истории.

Подробное поведение — раздел 9.3.

7.9 Остановить диалог (builtin_lead_meta)

`stop_dialog` — клиент явно просит не писать («не пишите», «отстаньте», «stop») или окончательно отказался. Бот выключается на этом диалоге навсегда (до ручного включения оператором) и отменяет все дожимы.

• reason — причина для истории.

Это «липкая» остановка — авто-возобновление её не оживит. Подробно — раздел 9.4.

7.10 Отправка фото и видео (builtin_send_media)

`send_media` — бот шлёт материал из медиа-библиотеки проекта (видео, фото, отзывы, прайс) прямо в чат, когда это уместно. Сначала загрузите материалы в разделе «Медиа».

• media_key*🔒 — ярлык материала (список реальных ярлыков и подсказки «когда слать» подставляются автоматически);
• caption — короткая подпись.

Ограничение: не более 3 медиа за 60 секунд на диалог (защита от спама). Подробно — раздел 9.6.

8. Кастомные вебхуки: простой и продвинутый режим

Кастомная функция — это HTTP-запрос на ваш адрес. Используйте, когда нужной встроенной функции нет: своя CRM, n8n, Zapier, собственный API.

8.1 Простой режим (по умолчанию)

• Только POST.
• Тело — JSON со всеми параметрами одним объектом.
• Стандартные заголовки.
• Таймаут до 30 секунд.

Этого хватает для большинства интеграций «отправить данные на сервер».

8.2 Продвинутый режим (mode: advanced)

Включается, когда нужен полный контроль над запросом:

• URL (webhook_url) — обязателен. Проверяется на безопасность (нельзя внутренние адреса 127.0.0.1, 10.x, 192.168.x и т.п. — защита от SSRF).
• HTTP-метод — GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS.
• Таймаут — до 60 секунд.
• Формат тела — JSON / form-data / raw / x-www-form-urlencoded.
• Шаблон тела (body_template) — свой шаблон с подстановкой {{параметр}}, до 50 КБ.
• Параметры URL (query) — пары ?ключ=значение, до 30 шт.
• Авторизация — Bearer-токен / Basic / API-key (хранится в зашифрованном виде).
• Заголовки — произвольные пары «ключ: значение».
• Маппинг ответа — выбрать из ответа API только нужные поля, чтобы вернуть их ИИ (до 50 полей, обрезка по длине). Это важно: не возвращайте боту огромный JSON — выберите 2–3 нужных поля.
• Повторы (retry) — до 5 попыток при 5xx / 429 / таймауте.
• Пагинация — авто-сбор нескольких страниц (cursor / offset / page), до 10 страниц.

8.3 Подстановка переменных

В URL, заголовках и теле можно подставлять собранные параметры через {{имя_параметра}} (а также системные переменные). Пример тела:

{ "name": "{{client_name}}", "phone": "{{client_phone}}", "source": "whatsapp" }

8.4 Что важно про ответ

ИИ увидит то, что вернул ваш сервер (с учётом маппинга). Поэтому ваш ответ должен быть понятен модели: лучше вернуть { "status": "ok", "booking_id": 123 }, чем сырой дамп БД. На основе этого бот сформулирует ответ клиенту.

9. Управление диалогом и лидом

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

9.1 Теги (set_lead_tags)

• Бот добавляет теги к уже стоящим (merge), не затирая операторские. Снять тег может оператор.
• Выбирает из словаря проекта (со страницы «Теги», с описаниями) или создаёт новый — если включён тумблер «Разрешить боту создавать новые теги».
• Максимум 20 тегов на лида. Теги видны и фильтруются в CRM/лидах, считаются в отчётах. Подробно — Теги и сегментация.

9.2 Пауза дожимов (pause_followups)

Когда вызывать (по описанию для ИИ): клиент написал «напишу в четверг», «наберу после 15-го», «свяжусь сам», «подумаю», «позже».

Что происходит:

• ставится snoozed_until (на 09:00 по Алматы, если указана только дата; либо точное время);
• если даты нет или она в прошлом → пауза +3 дня от текущего момента;
• счётчики дожимов сбрасываются, чтобы по истечении паузы пришло одно мягкое напоминание;
• бот в чате НЕ выключается — если клиент напишет раньше, ответит как обычно.

Отличие от стоп-диалога: пауза = «помолчи с напоминаниями до даты», стоп = «замолчи совсем».

9.3 Остановить диалог (stop_dialog)

Когда вызывать: клиент явно просит не писать или окончательно отказался после отработки возражений. НЕ вызывать на первое «дорого/подумаю» — это возражение (его отрабатывают или ставят pause_followups).

Что происходит:

• ai_on = false на диалоге, фиксируется время паузы;
• причина client_stop — «липкая»: авто-возобновление бота не оживит этот диалог;
• все дожимы по диалогу отменяются автоматически (триггер БД);
• заново включить может только оператор из дашборда.

Зачем так строго: защита от назойливости и от блокировок WhatsApp за спам.

9.4 Приём оплаты (create_payment_invoice)

Поток: клиент согласился платить → бот вызывает функцию с суммой, телефоном и описанием → создаётся счёт в apipay → клиенту приходит Kaspi-push → он подтверждает в приложении.

Успех возвращает боту: invoice_id, apipay_invoice_id, status, сумму, телефон, сообщение и подсказку для ИИ — бот говорит клиенту «Счёт на N ₸ отправил вам в Kaspi, подтвердите в приложении».

Коды ошибок (бот объяснит клиенту человеческими словами):

Важно: суммы и номера бот не выдумывает — описание функции прямо запрещает это, он уточнит у клиента.

9.5 Отправка медиа (send_media)

• Бот выбирает media_key из enum реальных ярлыков вашей медиа-библиотеки (список и подсказки «когда отправлять» подмешиваются в схему функции автоматически).
• Материал ищется в библиотеке проекта (только активные), отправляется в канал (WhatsApp/Telegram), запись попадает в историю сообщений как image/video/....
• Лимит: 3 медиа / 60 сек на диалог.
• В тест-чате медиа не отправляется реально — показывается превью.

«Передать оператору / эскалация владельцу» как отдельной встроенной функции нет — это делается через `notify_telegram` (уведомить владельца), ручное выключение ИИ на диалоге, или кастомный вебхук в вашу CRM. В конкретных проектах такие функции часто называют send_lead / escalate_to_owner — это кастомные функции, а не встроенные шаблоны.

10. Тестирование, версии, лог, импорт/экспорт

10.1 Тест функции («Проверить»)

Кнопка «Проверить» на карточке открывает тест-модалку «Тест: <имя>»:

• кнопка «Заполнить пример» подставляет примеры;
• по каждому параметру — поле ввода (для enum — выпадающий список), с подсказкой формата;
• «Отправить тест» реально выполняет вызов (для вебхука — шлёт запрос на ваш URL);
• результат: код статуса, отформатированный JSON-ответ, длительность (мс), ошибка если была.

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

10.2 Попробовать в чате

Пункт меню «Попробовать в чате» открывает тест-чат, где можно проверить, вызовет ли бот функцию сам по описанию (а не только технически работает ли вебхук). Это проверка качества описания.

10.3 История версий

Каждое изменение функции сохраняет снимок (хранятся последние ~50 версий). Меню → «История версий» → список с датами → «Восстановить» любую (с подтверждением). Спасает, если случайно сломали настройку.

10.4 Лог вызовов (Executions)

Меню → «Лог вызовов» — все реальные вызовы функции ботом: статус (успех/ошибка), время, длительность, разворачиваемые детали запроса/ответа. Первое место, куда смотреть, если «функция не сработала».

10.5 Импорт / экспорт

• Экспорт как JSON (меню карточки) — выгрузить одну функцию.
• Импорт (кнопка в шапке) — вставить JSON одной функции или массива, либо перетащить файл (до 1 МБ). Удобно переносить функции между проектами.

10.6 Дублировать и превью

• Дублировать — копия функции (быстро сделать похожую).
• Превью запроса — посмотреть, как будет выглядеть запрос, не отправляя его.

10.7 «Улучшить с ИИ»

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

11. Связь функций с промптом бота

Функции и системный промпт (Настройки → Промпт) работают вместе:

• Описание функции говорит ИИ, что она делает и когда её звать. Это первично.
• Промпт задаёт общий характер, правила и может явно направлять: «когда клиент готов записаться — вызови book_appointment».
• Если в промпте упомянута функция, которой нет — на странице «Функции» появится баннер рассинхрона (см. 3.5) с кнопкой создать её.
• Полоса готовности предупреждает: «N не упомянуты в промпте» — это намёк, что функция есть, но бот может про неё «забыть», если в промпте нет подсказки. Для важных функций стоит и хорошее описание, и упоминание в промпте.

Правило большого пальца: описание — для понимания «что это», промпт — для управления «в какой момент сценария это использовать».

12. Лимиты и ограничения

При попытке создать 21-ю функцию кнопка заблокируется, а импорт вернёт ошибку «лимит достигнут».

13. Безопасность и приватность

• Секреты маскируются. Токены, пароли, ключи (bot_token, api_key, access_token, password, secret и т.п.) в ответах API возвращаются как ***hidden***. При редактировании, если прислать обратно ***hidden***, старое значение сохранится — вы не затрёте секрет случайно.
• Шифрование. Конфиги авторизации и встроенных функций хранятся в зашифрованном виде (AES-GCM).
• Защита от SSRF. URL вебхуков нельзя указывать на внутренние адреса (127.0.0.1, 10.x, 192.168.x, IPv6-приватные) — защита от обращения бота к внутренней инфраструктуре. Проверка идёт с учётом DNS-резолва.
• Заголовки чистятся от переносов строк (защита от инъекций).
• Права доступа. Создавать/менять/удалять функции может участник проекта с ролью editor и выше; просматривать — viewer. URL и секреты не отдаются участникам без прав владельца.
• Аудит. Каждое создание/изменение пишется в журнал аудита.

14. Все статусы и состояния

Статус функции на карточке:

Предупреждения полосы готовности:

• «N с ошибками» — функции с красным статусом.
• «N не упомянуты в промпте» — есть функция, но в промпте нет наводки (бот может её не звать).
• «N не протестированы» — нажмите «Проверить».

UX-состояния страницы: загрузка (скелетоны), пусто (см. 3.7), ошибка загрузки (инлайн-сообщение, не белый экран).

15. Лучшие практики и чек-лист

Описание функции:

• ✅ Пишите от лица бота: «Записывает клиента на приём. Вызывай, когда клиент подтвердил время.»
• ✅ Укажите когда вызывать и когда НЕ вызывать.
• ❌ Не пишите формально «Функция записи» — ИИ не поймёт момент.

Параметры:

• ✅ Описание параметра = живой вопрос клиенту.
• ✅ Помечайте обязательным только то, без чего действие невозможно.
• ✅ Используйте enum для фиксированных вариантов и examples для форматов.

Подключение:

• ✅ Для Sheets/Calendar — выдайте доступ сервисному аккаунту (его email показан при настройке).
• ✅ Для вебхука — верните боту короткий понятный ответ, а не сырой JSON (настройте маппинг).
• ✅ Поставьте разумный таймаут (медленный сервер = клиент ждёт спиннер).

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

• ☐ Нажал «Проверить» — подключение работает.
• ☐ «Попробовал в чате» — бот вызывает функцию сам по описанию.
• ☐ Функция включена.
• ☐ Если важная — упомянул её в промпте.
• ☐ Статус «Работает», полоса готовности зелёная.

Сценарии управления:

• ✅ Возражение «дорого/подумаю» → отрабатывай или pause_followups, не stop_dialog.
• ✅ «Не пишите мне» → stop_dialog.
• ✅ Готов платить → create_payment_invoice (не выдумывай сумму — уточни).

16. FAQ и крайние случаи

Бот не вызывает функцию, хотя она включена.
Причина почти всегда в описании. Откройте «Попробуй в чате» и проверьте, понимает ли ИИ момент. Улучшите описание (кнопка «Улучшить с ИИ»), при необходимости добавьте наводку в промпт.

Функция вызывается не вовремя / слишком часто.
Описание слишком широкое. Добавьте «вызывай ТОЛЬКО когда…» и «НЕ вызывай если…».

В тест-чате работает, в бою — нет.
Проверьте, что функция включена в боевом проекте, подключение настроено (не ⚠ не задано), и канал/интеграция активны. Логика ИИ одинаковая во всех 5 точках входа — расхождение обычно в настройке подключения.

Достиг лимита 20 функций.
Удалите неиспользуемые или объедините близкие. Часто несколько узких вебхуков можно заменить одним с параметром «действие».

Два клиента бронируют один слот.
Для Sheets используйте update_row с expected_current_value/expected_other_cell (запись только если слот свободен). Для Calendar — check_available_slots непосредственно перед book_appointment.

Случайно сломал настройку функции.
Меню → «История версий» → «Восстановить» нужную.

Нужно перенести функции в другой проект.
«Экспорт как JSON» в одном → «Импорт» в другом.

Где функции `send_lead` / `escalate_to_owner` / `kb_search`?
send_lead / escalate_to_owner — это кастомные функции конкретных проектов (вебхуки или Telegram-уведомления), а не встроенные шаблоны. kb_search — служебный поиск по базе знаний, он работает автоматически, настраивать его как функцию не нужно.

Удалил фичу «Услуги» / Flow Builder / Automation Rules — почему grep их находит?
Эти сущности удалены из продукта и к функциям отношения не имеют (см. CLAUDE.md → «Удалённые фичи»). Не путайте с живым CRM-микродвижком (crm_automations).

17. Глоссарий

• Функция / Инструмент / Tool — действие, которое бот может выполнить (синонимы).
• action_type — тип действия: webhook (свой HTTP) или builtin_* (встроенный обработчик).
• builtin_config — настройки встроенной функции (ID таблицы, токен и т.д.), которые ИИ не видит.
• Параметр — данные, которые бот собирает у клиента и передаёт в функцию.
• locked / ШАБЛОН — заблокированный параметр шаблона, его нельзя ломать.
• enum — фиксированный список допустимых значений параметра.
• Цепочка (chain) — группа связанных функций с порядком вызова.
• fallback — поведение при ошибке функции (silent / notify / retry / transfer).
• Дожим (follow-up) — автоматическое напоминание клиенту; управляется pause_followups / stop_dialog.
• Сервисный аккаунт — технический Google-аккаунт DOS AI, которому вы даёте доступ к таблице/календарю.
• RAG / База знаний — автоматический поиск по вашим документам, НЕ функция.
• 5 точек входа — места, где отвечает ИИ (тест-чат, Wazzup, Telegram, ручная отправка, переотправка); функции работают одинаково везде.

💬 Простыми словами (вся статья в двух минутах)

Обычный бот умеет только разговаривать. Функции — это «руки» бота: они позволяют ему не просто отвечать словами, а делать дела — записать клиента в календарь, добавить строку в Google-таблицу, выставить счёт на оплату в Kaspi, скинуть тебе заявку в Telegram, отправить клиенту видео, поставить пометку на клиента. Каждая функция — это «одно умение».

Самое важное и непривычное: ты не программируешь сценарий «если клиент сказал X — сделай Y». Ты просто по-человечески описываешь каждое умение — «эта функция записывает клиента, вызывай её, когда он подтвердил время» — а бот сам решает, когда им воспользоваться, прямо посреди разговора. Поэтому в функциях главное поле — описание. Плохо описал — бот не поймёт, когда применять; хорошо описал — он сам всё свяжет (сначала проверит свободное время, потом запишет, потом подтвердит).

Делать функции можно двумя путями. Из шаблона — это готовые умения (Google Таблицы, Календарь, Telegram, приём оплаты, отправка фото): тебе остаётся только подключить свою таблицу или номер, всё остальное уже настроено. Кастомная — если у тебя своя система (CRM, сайт), бот может «постучаться» на твой адрес и передать туда данные.

Есть и особые функции, которые управляют самим ботом: поставить напоминания на паузу («клиент сказал — напишу в четверг»), совсем остановить диалог («клиент попросил не писать»), пометить клиента тегом, выставить счёт. Их тоже бот применяет сам по смыслу разговора.

Что важно помнить на каждый день:

• Функция работает, только если она включена и у неё настроено подключение (для таблицы — дать доступ, для оплаты — подключить Kaspi).
• Всё новое проверяй в тест-чате: там видно, реально ли бот вызвал функцию, а не просто написал «записал» словами.
• Функций можно сделать до 20 на проект.
• Секреты (токены, пароли) платформа прячет и шифрует — участники их не видят.
• Не получается? Загляни в «Лог вызовов» функции — там видно, что именно пошло не так.

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

Документ описывает раздел «Функции» DOS AI по состоянию на июнь 2026. Каталог встроенных функций — источник истины: `packages/@dos/admin/src/function-templates.ts`. Логика выполнения: `packages/@dos/ai-pipeline/src/pipeline/tool-executor.ts`.