Действия
Что бот может сделать после сообщения или нажатия: ответить, сохранить заявку, выдать доступ, запросить данные или принять оплату. Настройки и ограничения.
На этой странице
Действие описывает конкретную работу бота: отправить ответ, сохранить телефон, создать заказ или уведомить менеджера. В одной реакции их может быть несколько. Например, после заявки сначала сохранить данные, затем поставить метку «Новая заявка» и отправить подтверждение клиенту.
Откройте раздел Действия редактора и нажмите Добавить действие. Бот выполняет список сверху вниз. Результат одного шага можно передать следующему через временные данные (ctx). Сведения, которые нужны и при следующих обращениях, сохраняйте в параметры пользователя. Примеры: Подстановки и формулы.
Сообщения и ответы
- Отправить сообщение: главное действие: собирает ответ из блоков (текст, фото, файл, задержка, ИИ, вызов реакции), добавляет inline-кнопки, меню и шаги диалога. Подробно: Сообщения и кнопки.
- Сохранить сообщение: записывает текст входящего сообщения в параметр пользователя.
- Переслать: пересылает входящее сообщение в указанные чаты (с опциональным ID топика).
- Уведомление: отправляет уведомление в служебные чаты с данными о пользователе, чате и тексте.
- Кнопка меню: меняет кнопку меню Telegram (
setChatMenuButton) без перезапуска бота: стандартная, список команд или Mini App с текстом и URL (подстановки работают). Область «этот чат» работает только в личной переписке с подписчиком, вызвавшим реакцию, – в группе или другом типе чата действие завершится ошибкой; область «все чаты» меняет общую кнопку бота для всех, у кого нет своей, и не может стоять внутри цикла. На каналах, отличных от Telegram, действие тихо пропускается.
Пользователь: метки и параметры
- Изменить метки: добавляет и/или удаляет метки подписчика. Поле «Срок, дней» (
ttl_days) делает добавляемые метки временными: по истечении срока метка снимается автоматически, а бот получает системное событие «Метка истекла» (см. триггеры). Так можно выдавать доступ по подписке: после оплаты поставить метку на 30 дней, а после её истечения исключить человека из закрытого чата. - Изменить параметры: задаёт, удаляет или увеличивает значения параметров пользователя.
Модерация
- Удалить полученное: удаляет входящее сообщение (опционально: все сообщения пользователя, с задержкой).
- Удалить отправленные: удаляет сообщения бота (этой реакции или все в чате, с задержкой).
- Изменить права: заглушить / снять заглушку / забанить / разбанить / ограничить права / исключить / одобрить заявку / отклонить заявку участника; для отдельных действий можно указать срок, а для ограничения выбираются конкретные права.
Исключить (kick) убирает участника из чата без чёрного списка: в Telegram это бан и сразу разбан, в VK – только через чёрный список сообщества (groups.ban), иначе VK исключать не умеет.
Одобрить заявку (approve) принимает уже поданную заявку подписчика на вступление в закрытый чат или сообщество – так выдаётся доступ в клуб.
Отклонить заявку (decline) отвечает отказом на уже поданную заявку. Заявка снимается, но человек не попадает в чёрный список и может подать её снова. Поэтому у действия нет ни срока, ни набора прав. Если заявки нет, отклонять нечего. В Telegram боту нужно право can_invite_users – оно же управляет заявками на вступление. VK эту операцию не поддерживает: одобрить заявку в сообщество он умеет, отклонить – нет. Поэтому узел кампании завершится ошибкой, а обычная реакция будет отклонена при подготовке отправки.
Заявитель берётся из самого события – это подавший заявку пользователь, а не user_chat_id. user_chat_id Telegram присылает рядом с заявкой: это временный личный диалог, открытый для того, чтобы бот мог написать заявителю, и он не идентификатор для модерации и не id заявителя – модерация по нему не отклонила бы ничего и адресовала бы личную переписку.
Поле «Чат» (chat_id) задаёт целевой чат явно; пустое значение берёт чат события, но только если реакция сработала в группе или канале. Для события «Метка истекла», расписания, узлов кампании и любого другого запуска из личного диалога чат нужно указать явно, иначе действие пропускается.
- Важная реакция (цвет): помечает диалог цветом для оператора.
Данные и коллекции
- Создать запись: добавляет строку в коллекцию. Если задан ключ дедупликации, повтор с тем же ключом обновит прежнюю строку вместо создания новой. Такая операция называется
upsert. - Обновить записи: меняет строки, подходящие под фильтр.
- Найти записи: читает строки в контекст как массив (для перебора).
- Поиск по коллекции (
record_search): ищет по выбранным текстовым полям, альтернативным названиям и, при включённой настройке, с учётом опечаток. Сохраняет строки и сведения о полноте поиска. - Найти связанные записи (
record_related): читает строки по общему ключу, например даты занятия по его коду, или одну строку по_record_id. - Прочитать страницу коллекции (
record_page): читает следующую порцию записей с фильтрами и сортировкой. Курсор продолжает тот же запрос; последняя страница не становится всей коллекцией. - Итоги всей коллекции (
record_aggregate): считает по всем подходящим записям, доступным по правилам хранения, без предварительной загрузки списка в реакцию. - Атомарная транзакция коллекций (
collection_transaction): проверяет условия и сохраняет несколько изменений вместе. При конфликте ни одно из них не остаётся частично сохранённым. Три упражнения с коллекциями. - Удалить записи: удаляет строки по фильтру.
- Цикл по списку: перебирает массив из
ctxи выполняет вложенные действия для каждого элемента: посчитать сумму заказов, записать каждый элемент в коллекцию, дёрнуть внешний сервис по каждой строке.
Цикл не подходит для рассылки: одно событие может отправить не больше 50 сообщений, а цикл берёт до 500 элементов. Массовая отправка: это Рассылки и Кампании, у них своя скорость и свой учёт. Подробности: ниже, «Бюджет одного события».
Подробнее о коллекциях: Коллекции и данные.
Внешние запросы
- Веб-запрос: HTTP-запрос с заголовками, телом (JSON или текст), кодами успеха, временем ожидания и повторами. Поддерживаются
GET,HEAD,OPTIONS,POST,PUT,PATCHиDELETE. Автоматически повторяются только сетевые ошибки и ответы429или5xx; другие4xxне повторяются. ДляPOSTиPATCHповторы включаются только тогда, когда вы сами задалиIdempotency-Keyи принимающий сервис умеет отбрасывать дубли по этому ключу. Платформа также отправляет собственный ключ, одинаковый при повторе шага, но одного его для включения повторовPOSTиPATCHнедостаточно. Ответ можно сохранить в параметр пользователя или во временные данныеctx, выбрав нужную часть через JSONPath. Запрос можно выполнять в фоне и направлять успешный или ошибочный результат в разные реакции. - Загрузить URL: скачивает страницу и сохраняет её читаемый текст в
ctx(для последующей обработки или ИИ). - Запрос к источнику: читает данные из подключённого коннектора (REST / OzmaDB) в
ctx. - Запись в источник: пишет данные в коннектор (POST/PUT/DELETE).
Об источниках и ключах: Источники и ключи.
ИИ и вычисления
- ИИ: обращается к языковой модели: промпт, сохранение ответа в параметр/
ctx, опциональная JSON-схема для извлечения структуры, отправка ответа пользователю. См. ИИ-ответы. - Вычисление: считает значение в одном из трёх режимов, в действии выбирается ровно один: «Формула» (короткое выражение,
expr), «Таблица решений» (правила «когда → тогда», первое истинное побеждает,rules) или «Расширенная формула» (полный язык со списками, JSON и хэшами,formula). Результат сохраняется вctxи/или параметр. См. Формулы.
Логика и сценарии
- Цепная реакция: запускает другую реакцию по её имени.
- Вызвать блок (
call_block): выполняет общую логику с объявленными входами и выходами. Можно закрепить конкретную версию или выбирать последнюю. Пример расчёта заказа. - Следующая реакция: передаёт управление следующей подходящей реакции в списке.
- Выбрать следующий шаг (
branch_result): проверяет результат поиска. Можно отдельно обработать отсутствие записей, одну или несколько записей, нечёткое совпадение и неполную выдачу. Первое подходящее условие выбирает целевую реакцию; обработку неполной выдачи ставьте раньше остальных веток. - Запустить сценарий: задаёт вопросы по очереди и сохраняет ответы (
flow). См. Сценарии. - Запросить подтверждение: отправляет карточку сотруднику, который принимает решение. Кнопки «Подтвердить» и «Отклонить» запускают указанные реакции.
- Передать оператору: переводит диалог в инбокс оператора. См. Чаты и операторы.
Платежи
- Выставить счёт: создаёт счёт в кассе бота и отдаёт ссылку на оплату в подстановке
{payment:url}. Оплата обрабатывается отдельной реакцией с триггером Платёж. См. Платежи и баланс.
Сумма задаётся десятичным значением в основных единицах валюты, например
1500.50, и преобразуется действием в минимальные единицы. Явный срок ссылки:
от 300 до 2 592 000 секунд, 0 использует значение по умолчанию.
Создание подписки задаёт стабильный ключ тарифа, сумму и период. Обновление
может сохранить текущую сумму или период, отмена прекращает будущие списания
без возврата уже списанного. Необязательный ключ тарифа сужает выбор подписок.
Интеграции
Действия GetCourse, Google Таблица и Google Диск подключаются через одноимённые интеграции (см. Интеграции). Универсальная отправка во внешний сервис доступна через Вебхук-интеграцию и действие Веб-запрос.
Google Таблица поддерживает пять операций. Поля сопоставляются с заголовками колонок строки заголовков (по умолчанию первой), порядок колонок листа не важен:
- Добавить строку – пары «заголовок → типизированное значение» с подстановками; неизвестный заголовок – ошибка. Результат:
{row_number, range}. - Прочитать строки – строки после заголовков как объекты с номером
_row; лимит страницы (по умолчанию 50, максимум 500), смещение,has_moreиnext_offsetв отдельный ключ. - Прочитать последнюю строку – последняя непустая строка листа.
- Найти строку по значению колонки – первая строка, где колонка (заголовок без учёта регистра или буква
A,B, …) равна искомому значению; значение поддерживает подстановки ({{param.email}}). - Обновить строку – меняет ячейки строки с номером
row_number, например{{ctx.lead.row_number}}.
Результат чтения одной строки сохраняется в параметр или контекст как JSON {"found":true,"row_number":12,"cells":[…],"values":{"Email":"…","Plan":"…"}}. При сохранении в контекст lead доступны {{ctx.lead.found}}, {{ctx.lead.row_number}} и {{ctx.lead.<заголовок>}} – например, {{ctx.lead.Plan}}. Если строка не найдена, found = false и ячейки пустые. Если лист слишком велик для просмотра, шаг завершается ошибкой, а не возвращает неверную строку.
GetCourse создаёт или обновляет пользователя и сделку секциями (user, system, session, deal, дополнительные поля) и выгружает пользователей, сделки и группы; результат импорта – {user_id, deal_id, lead_id}. Google Диск загружает файл и сохраняет {file_id, web_view_link}. У всех интеграционных действий и у ИИ есть необязательный разбор ответа, а сбой запускает настроенный маршрут ошибки. Подробности: Интеграции.
Бюджет одного события
У работы, запущенной одним сообщением или нажатием кнопки, есть общий предел: бюджет события. В него входят действия самой реакции, вызванных ею реакций, вложенных циклов и веб-запросов, которые продолжаются в фоне. Ограничение не даёт ошибочному сценарию бесконечно выполнять действия или отправлять сообщения.
Три границы:
| Что ограничено | Сколько | Что происходит на границе |
|---|---|---|
| Действий на событие | 5000, включая вложенные | Действие не выполняется, шаг помечен ошибкой |
| Исходящих сообщений на событие | 50 | Сообщение не ставится в очередь, шаг помечен ошибкой |
| Время события | 5 минут | Событие прекращается, незавершённые внешние вызовы отменяются |
Отдельно ограничен один цикл: до 500 элементов за проход. Если в массиве больше, лишние элементы просто не обрабатываются, и в карточке реакции этого не видно: поэтому не полагайтесь на цикл там, где важно обработать список целиком.
Почему сообщений именно 50, а элементов 500
Циклом можно обработать до 500 записей, например обновить статус каждой. Но отправить из одного события можно не больше 50 сообщений.
Реакция: это ответ конкретному человеку на его действие. Пятьдесят исходящих сообщений на одно входящее: это уже с большим запасом.
Рассылка: это доставка многим. У неё своя скорость, свои паузы, свой учёт отправленного и возможность поставить на паузу. См. Рассылки и Кампании.
Если каждый из 500 элементов цикла отправляет одно сообщение, первые 50 смогут уйти, а остальные получат отказ по лимиту. Для отправки по списку используйте рассылку: она учитывает получателей и отправляет сообщения с заданной скоростью.
Считаются именно исходящие сообщения, а не действия. Ответ из нескольких блоков (текст, фото, файл) расходует бюджет по одному на блок. Если очередной ответ не помещается в остаток бюджета, он не отправляется целиком: лучше не отправить сообщение, чем отправить его половину.
Как понять, что упёрлись в бюджет
Отказ виден в карточке реакции внутри диалога подписчика (раздел Люди → диалог): среди шагов появляется шаг с ошибкой «Превышен бюджет события», и в нём написано, какой именно бюджет кончился: actions, sends или deadline.
Подписчик не получает этот технический отказ, и успешный ответ API не подтверждает выполнение всех шагов. API может принять запуск, а действие внутри реакции затем превысит лимит. Проверяйте результат в карточке реакции.
После отказа цикл не прерывается: он продолжает перебирать оставшиеся элементы, и каждый следующий получает такой же отказ. Поэтому в карточке будет не один шаг с ошибкой, а много: по одному на каждый непоместившийся элемент. Сама реакция при этом завершается с ошибкой.
Что делать вместо
- Нужно отправить многим: Рассылки или Кампании. У них бюджета события нет: это отдельный, размеренный процесс с собственным учётом.
- Нужно обработать большой список без отправки (записать, посчитать, синхронизировать): цикл подходит, но помните про 500 элементов за проход: разбивайте выборку фильтром или лимитом коллекции.
- Нужны вложенные циклы: считайте произведение: внешние 100 × внутренние 100: это уже 10 000 действий, вдвое больше бюджета.
- Реакция упирается в 5 минут: почти всегда дело во внешних вызовах. Сделайте Веб-запрос асинхронным и продолжите работу отдельной реакцией по успеху или ошибке.
Проверка контакта
Действие Проверка контакта поддерживает запрос кода на email, проверку введённого кода или проверку владения телефоном. Для подтверждения email:
- Сохраните адрес человека в параметр и добавьте действие Отправить код на email.
- Попросите человека ввести код и в следующем шаге добавьте действие Проверить код из письма.
- Сохраните результат в параметр:
1означает успешную проверку,0– проверка не завершилась успешно. Ветвь с0должна предложить повторить попытку.
Код действует 15 минут и допускает до пяти попыток. После успешной проверки
адрес связывается с текущей карточкой человека. Если у адреса уже есть другая
карточка в том же проекте, она объединяется с текущей при отсутствии конфликта
внешних CRM-связей. Самостоятельный ввод адреса без подтверждения кодом
карточки не объединяет. Если склейку не удалось завершить, результат проверки
будет 0, а код можно использовать повторно до истечения его срока.
Чтобы не отправлять код на уже подтверждённый адрес, в действии Отправить код
на email включите Не отправлять код, если email уже подтверждён
(skip_if_verified) и заполните поле Сохранить результат в параметр
(save_result_to): без него реакцию нельзя сохранить. Для такого адреса код не
отправляется, а в параметр записывается already_verified.
Реакция сохранится только с такой цепочкой:
- Сразу после отправки кода идёт действие Выбрать шаг по значению, и оно последнее в реакции. Редактор может добавить его сам.
- Значение действия читает сохранённый результат, например
{user:email_status}. - Первая ветка проверяет условие равно
already_verifiedи ведёт к следующей реакции. - Если ни одна ветка не подошла ведёт к другой реакции, и именно в ней бот спрашивает код.
Для этой настройки используйте простое имя параметра без символов :, #,
{ и }. Не размещайте действие внутри цикла for_each; дополнительные
ветки сравнивают текст без регулярных выражений и числовых операторов.
Если реакция вызывается другой реакцией через chain или встроенный блок,
не ставьте вопрос о коде в родительской реакции после вызова: родитель может
продолжиться даже при ошибке дочерней реакции.
Отправка и проверка кода поддерживаются и в веб-виджете при настроенной почте. Проверка телефона использует уже подтверждённую идентичность WhatsApp и не отправляет код.
Капча
Капча доступна в Telegram. Задайте вопрос и от двух до восьми кнопок, отметьте ровно один верный ответ. Проверку может пройти только тот человек, которому она адресована. Срок ожидания составляет от 10 секунд до суток, по умолчанию две минуты. После неверного ответа человек может попробовать снова до истечения этого срока.
При вступлении в группу бот ограничивает права новичка до правильного ответа.
Если человек не ответил вовремя, бот исключает или блокирует его в зависимости
от настройки. Для этого боту необходимо право can_restrict_members.
При заявке на вступление вопрос приходит заявителю в личный чат. Верный ответ
одобряет заявку, а истечение срока отклоняет её. Боту необходимо право
can_invite_users; поле действия при ошибке для этого режима не требуется.
Telegram позволяет боту написать заявителю в течение ограниченного времени,
обычно до пяти минут после заявки; это ограничение относится к отправке
вопроса, а не к настроенному сроку ответа. Готовые варианты доступны в шаблонах
реакций категории «Группы и каналы»: «Капча для новых участников» и «Капча по
заявке на вступление».
Списки, итоги и переходы по данным
Для обработки произвольных данных доступны следующие действия:
- Обработать список (
list_transform): фильтры, сортировка, удаление повторов и выбор страницы. - Преобразовать поля списка (
list_map): вложенные поля, новые значения и расчёт для каждой строки. - Соединить списки (
list_join): дополнение строк данными другого списка по общему ключу. - Группы и итоги (
list_aggregate): количество, сумма, среднее, минимум, максимум и число разных значений, в том числе по группам. - Выбрать шаг по значению (
branch_value): упорядоченные условия по тексту, числу или состоянию. - Изменить запись при условии (
record_update_if): атомарное изменение одной записи с проверкой ожидаемых полей.
Эти действия не предполагают определённой предметной области бота. Списки можно брать из контекста, HTTP-ответов и коллекций. Проверка данных в редакторе не запускает последующие шаги. Подробные параметры и примеры.
Начать можно с практических уроков: поиск занятия, обработка HTTP-ответа, итоги по категориям и подтверждение заявки с проверкой текущего состояния. В каждом упражнении указано, что настроить и какой результат проверить.
В уроке по полям и объединению можно подготовить заявки: извлечь имя клиента, рассчитать сумму и добавить название занятия из справочника.
Результаты шагов и проверка черновика
В полях, принимающих данные предыдущих шагов, используйте помощник выбора данных. Он показывает имя результата и доступные поля. Для обработки списка выбирайте весь результат, если нужно сохранить сведения о его полноте.
У поддерживаемых действий можно настроить переходы по исходу: например, отдельно ответить при успешном изменении, конфликте и технической ошибке. Успех шага означает выполнение его операции; поставленное в очередь сообщение ещё не означает доставку.
Проверка черновика выполняет текущую несохранённую цепочку на учебных данных. В ней видны расчёты, выбранные ветки и предполагаемые действия. Рабочие сообщения не отправляются, коллекции не изменяются.
Что дальше
- Сообщения и кнопки: конструктор ответов и диалогов.
- Подстановки и формулы: переменные в текстах и логике.
- Рассылки: массовая отправка, когда цикла недостаточно.