Документация › Инструменты бота › Функции

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

Раздел «Функции» в проекте 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 (по QR, привязанное устройство),
• боевой Telegram,
• демо-чат на главной странице сайта,
• фоновые задачи: дожимы и авто-возобновление диалога.

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

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

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

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

3.1 Шапка

• Заголовок: «Функции».
• Подзаголовок: «Инструменты, которые ИИ сам решает когда использовать».
• Кнопка «Импорт»: загрузить функции из JSON (см. 10.5).
• Кнопка «+ Новая функция»: создать новую (см. раздел 4). Становится неактивной при достижении лимита 40 функций.
• Счётчик функций использовано / 40. Меняет цвет: серый → жёлтый (осталось ≤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 Таблицы, приём оплаты, поведение бота, фото и видео, письмо клиенту. Параметры уже настроены правильно, вам остаётся заполнить подключение. Рекомендуется в 90% случаев.
• «Кастомная»: свой запрос на любой сервер (вебхук). Для интеграции с вашей CRM, n8n, Zapier или собственным API.

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

Показываются семь групп: Уведомления владельцу (Telegram, почта), Запись на время (Google Calendar и движок окошек), Google Таблицы, Приём оплаты (Kaspi), Поведение бота (теги, отложить дожимы, остановить диалог), Фото и видео, Письмо клиенту. У каждой: иконка, описание, число шаблонов. Плюс поиск по слову («оплата», «запись», «уведомление»).

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

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

Шаг 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.

5.1 Предохранитель: как запретить боту то, о чём вы его просили не делать

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

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

Открывается на шаге «Когда выполнять» в конструкторе функции, там же, где триггер и поведение при ошибке.

Условий можно поставить несколько, тогда должны выполниться все.

«Счёт выставлен» и «деньги пришли» это разные условия, не путайте их. Первое даёт «Сначала отработала другая функция», и оно проходит уже в момент, когда бот отправил ссылку на оплату. Второе даёт «Оплата реально прошла», и оно ждёт ответа банка. Для записи на время берите второе: между выставленным и оплаченным счётом клиент успевает сказать «я оплатил», и на этих словах бот займёт время, за которое никто не заплатил.

Что вы увидите. На карточке функции появляется отметка «Предохранитель». Каждый отказ попадает в раздел Логи проекта с причиной, поэтому «функция молчит» никогда не остаётся без объяснения.

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

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 Письмо клиенту (builtin_email) и Gmail (builtin_gmail)

«Отправить письмо клиенту» (send_customer_email): бот шлёт письмо на адрес, который клиент назвал в переписке (счёт, подтверждение записи, коммерческое предложение). Работает сразу, без почтового сервиса, ответ клиента приходит на указанный тобой адрес. Подробно: Письмо клиенту.

Шаблон «Отправить с Gmail (Workspace)» (send_gmail) из каталога скрыт с июня 2026: он требовал Google Workspace и доступ сервисного аккаунта, и почти никто им не пользовался. У старых проектов такие функции продолжают работать. Для новых берите «Письмо клиенту».

7.4 Уведомления владельцу: Telegram (builtin_telegram) и почта (builtin_email)

«Уведомление в Telegram» (notify_telegram) шлёт сообщение в Telegram-чат (например владельцу о новой заявке). Config: bot_token , chat_id , message_template (шаблон сообщения с подстановкой переменных). Параметров нет, сообщение собирается из шаблона. Откуда берётся бот: если проект настраиваем мы, подключаем свой @dosaitech_bot* и токен вписываем сами, если настраиваете вы, создаёте бота через @BotFather. Подробно в Уведомлениях владельцу.

«Уведомление на почту» (notify_email) делает то же самое письмом на твой email: тема и текст из шаблона с переменными ({{client_name}}, {{phone}} и т.д.), настройка почтового сервиса не нужна.

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

7.4a Свободные окошки для записи (builtin_booking)

find_free_slots: для бизнеса с несколькими специалистами. График живёт в Google-таблице (специалист, услуга, дни, обеды), занятость берётся из Education CRM или только из графика, а движок сам собирает свободные слоты и отдаёт боту готовый список. Config: таблица с графиком, услуги, длительность слота (60 мин), горизонт (7 дней, максимум 14), окно бизнеса (09:00-21:00). Подробно: Запись на время.

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, до которой пауза. Пусто (и нет pause_hours) = пауза 1 день.
• reason: причина для истории.

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

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

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

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

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

7.10 Отключить дожимы (builtin_lead_meta)

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

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

Отличие от паузы: без срока и без возврата. Если клиент назвал срок, бот выберет паузу. Подробно, раздел 9.4.

✅ Три функции про паузы и остановки (7.8, 7.9, 7.10) стоят у каждого проекта с рождения и включены, а у проектов, созданных с 14 сентября 2026, к ним добавлена и включена функция «Помечать лида тегами». Управляются здесь же, в разделе «Функции», как любые другие: выключить тумблером, поправить описание «когда вызывать» под свою нишу, удалить. Паузы при ответе оператора и после звонка, автовозобновление живут в «Расширенных настройках» бота.

🛑 Как вообще останавливается диалог. Бот никогда не решает остановиться сам, он всегда дообщается с клиентом, пока его не остановят явно. Остановить можно четырьмя способами: (1) функцией «Остановить диалог» (её вызывает бот, когда клиент просит не писать); (2) галочкой «Завершать диалог после выполнения этой функции», она есть у любой функции (в настройках функции, внизу), когда функция успешно отработала, бот выключается на этом чате и отменяет дожимы (удобно, например, после записи на приём или передачи заявки менеджеру); (3) состоявшимся звонком, если включена настройка «Выключать ИИ после состоявшегося звонка» (по умолчанию включена, см. справочник настроек); (4) вручную: тумблером AI в шапке диалога. Во всех случаях бот молчит, пока вы не включите AI обратно вручную.

⏰ Отдельно про дожимы. Рядом с галочкой «Завершать диалог» есть вторая, «Останавливать дожимы после этой функции». Она решает только судьбу автонапоминаний и не трогает бота. Включайте, когда после функции напоминать уже не о чем: заявку передали живому человеку, клиента записали, оплату приняли. Оставляйте выключенной для уведомлений, которые разговор НЕ заканчивают: эскалация вопроса, пометка отказа, сигнал о жалобе. Раньше любое уведомление владельцу гасило дожимы само, без настройки, поэтому вопрос клиента «а куда можно позвонить?» мог молча выключить напоминания живому лиду.

Обе галочки действуют на вызовы, которые делает сам бот по ходу разговора. Если у функции выбран автозапуск (по событию или по смене статуса лида), она срабатывает ещё и сама: в этом случае уведомление уходит отдельным путём, и галочки в нём не участвуют. Бот при этом может вызвать её и обычным образом, тогда галочки работают как всегда. В настройках такой функции под галочками стоит та же пометка.

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

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

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

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

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

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

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

• Только POST.
• Тело, JSON со всеми параметрами одним объектом.
• Стандартные заголовки.
• Таймаут до 60 секунд (по умолчанию 10).

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

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

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

• URL (webhook_url): обязателен. Проверяется на безопасность (нельзя внутренние адреса 127.0.0.1, 10.x, 192.168.x и т.п.: защита от SSRF).
• HTTP-метод: GET / POST / PUT / PATCH / DELETE. PATCH нужен для частичного обновления записи (так работают многие CRM).
• Таймаут: до 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 по Алматы, если указана только дата; либо точное время);
• если даты нет или она в прошлом → пауза +1 день (до 09:00 по Алматы следующего дня);
• счётчики дожимов сбрасываются, чтобы по истечении паузы пришло одно мягкое напоминание;
• бот в чате НЕ выключается, если клиент напишет раньше, ответит как обычно;
• пауза соблюдается даже если раздел «Дожимы» у проекта выключен: в назначенный срок бот всё равно вернётся с одним сообщением о договорённости, без запуска лестницы касаний.

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

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

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

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

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

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

9.4 Отключить дожимы (stop_followups)

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

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

• подписчик дожимов по этому диалогу переводится в cancelled (если его ещё нет, он заводится сразу отменённым, чтобы более поздний авто-зачисл не вернул напоминания);
• ai_on не трогается: бот продолжает отвечать на сообщения клиента;
• вернуть дожимы можно вручную из таблицы дожимов.

Три способа одним взглядом: пауза = помолчи с напоминаниями до срока, отключить дожимы = напоминаний больше нет, бот отвечает, стоп-диалог = замолчи совсем.

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

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

Успех возвращает боту: invoice_id, provider_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. Лимиты и ограничения

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

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 точках входа: расхождение обычно в настройке подключения.

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

Два клиента бронируют один слот.
Для 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: служебный поиск по базе знаний, он работает автоматически, настраивать его как функцию не нужно.

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 точек входа: места, где отвечает ИИ (тест-чат, WhatsApp, Telegram, демо-чат на сайте, фоновые задачи вроде дожимов); функции работают одинаково везде.

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

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

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

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

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

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

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

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

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