Кампании
Как настроить серию сообщений и действий на несколько дней: условия, паузы, публикация и проверка пути конкретного клиента.
На этой странице
Кампания выполняет несколько шагов с паузами и проверками. Например, после заявки бот отправляет программу курса, через день проверяет оплату и напоминает о записи тем, кто ещё не оплатил.
В редакторе шаги соединяются на схеме. Шаг может отправить сообщение, подождать, проверить условие или выполнить действие. Путь одного клиента по этой схеме называется путешествием. Кампания может длиться несколько дней или недель. Если нужно отправить одно сообщение группе людей, используйте рассылку или email-рассылку.
Версии и черновик
Настройки меняются в одном черновике (draft). При публикации платформа сохраняет его копию, которую уже нельзя изменить, – опубликованную версию (published). После остановки её можно перевести в архив (retired). По номеру версии видно, какие правила действовали для конкретного клиента.
Черновик содержит условие запуска, аудиторию, настройки и схему шагов. При сохранении через API используйте PUT /draft с expected_revision. Если другой сотрудник сохранил изменения раньше, сервер сообщит о конфликте. Загрузите свежий черновик перед повторной правкой.
Публикация (POST /publish) сохраняет текущий черновик как новую неизменяемую версию и сразу создаёт следующий черновик с тем же содержимым. Клиент, вошедший в кампанию на версии N, проходит её до конца по версии N, даже если позже выйдет версия N+1. Новая версия не меняет условие запуска, аудиторию, настройки и шаги уже начатого путешествия.
Схему шагов можно изменить только после остановки кампании. Пока кампания выполняется или стоит на паузе, сохранение изменений схемы отклоняется: клиент может находиться на одном из её шагов.
Любую версию, включая черновик и архивную версию, можно клонировать в текущий черновик. При этом прежнее содержимое черновика будет заменено. Остановленную кампанию можно архивировать: она исчезнет из активного списка, но её история сохранится.
Триггеры входа
- Вручную: без настроек; кнопка «Отправить тест себе» в редакторе вызывает тот же путь и сразу выполняет входной узел, не дожидаясь фонового обхода.
- Событие сайта: то же событие клиентского SDK/виджета, что и в
реакциях, с тем же редактором условий. Кнопка «Подписка на email через поп-ап» выбирает системное событие
$email_subscribed: оно возникает после отдельного подтверждения новой подписки или повторной подписки после отписки через форму поп-апа. - По расписанию: один раз в момент
atили регулярно. Для регулярного запуска укажите местное время (ЧЧ:ММ) и часовой пояс IANA. Значение «Local» не принимается. При необходимости выберите дни недели. Укажите началоstart_atи конецend_at: между ними должно быть не больше двух лет. Конец обязателен, чтобы забытая кампания не проверяла аудиторию бесконечно. Если из-за весеннего перевода часов заданное местное время не наступит, запуск по умолчанию пропускается. Режим «следующий существующий момент» вместо этого переносит запуск на ближайшее допустимое время. - Изменение метки: добавление или снятие одной конкретной метки. Эти события запускают разные путешествия с разным содержанием.
- Изменение свойства: изменение разрешённого свойства профиля. Условия «было» и «стало» можно задать независимо друг от друга или оставить пустыми. Повторное сохранение того же значения не запускает кампанию.
- Вход в сегмент: переход участия в готовом сегменте из «не входит» в «входит». Обычный пересчёт, который лишь подтверждает уже имеющееся участие, входом не считается.
Узлы графа
Шаги на схеме соединены линиями. Подпись линии, например yes или no, показывает, когда выбирается этот путь. Начальный шаг должен быть один. Из каждого шага должен существовать путь к Цели или Выходу. Кампанию нельзя сохранить, если на схеме есть недостижимый шаг или путь без завершения. В API шаги называются узлами, а линии – рёбрами. У одного узла может быть до 32 КиБ настроек; вся кампания ограничена 200 узлами и 400 рёбрами.
- Сообщение: отправляет текст, фото или файл и может включать задержку, как обычная реакция этому клиенту. Блоки ИИ, вложенные реакции, ожидание ответа и сохранение параметров с побочным эффектом здесь недоступны. Это позволяет безопасно повторить шаг после сбоя.
- Контент: отправляет документ, который уже опубликован и закреплён за конкретной версией, через выбранный канал: Telegram, VK, WhatsApp, веб-чат, email, браузерный или мобильный пуш. Для email нужен опубликованный документ типа Email, тема письма и настроенная отправка. Шаг сам не переключается на другой канал. Если связаться с клиентом нельзя, он переходит по настроенной ветке «когда канал недоступен» либо завершается ошибкой. Для пуша нужен опубликованный документ типа Push.
- Задержка: ждёт заданное число секунд (не больше 180 дней).
- Ожидание события: ждёт клиентское событие по имени (до 64 символов, без
зарезервированного префикса
$) с таймаутом до 180 дней; у узла ровно две ветки: основная (событие пришло) иtimeout. - Условие: ветвится
yes/noпо параметрам подписчика, периодам времени, давности последнего визита или числу сообщений: тот же словарь условий, что у реакций. - Разделение: весовое A/B-ветвление: подписчик детерминированно попадает в одну и ту же ветку по хэшу узла и своего идентификатора, и это не меняется при повторной проверке или перезапуске.
- Эксперимент: выбирает ветку по варианту общего эксперимента, у которого закреплены идентификатор и версия. В эксперименте от двух до шестнадцати вариантов. Для каждого нужна своя ветка, иначе путь назначенного этому варианту клиента оборвался бы без объяснения.
- Доступность канала: ветвится
yes/noпо тому, можно ли именно сейчас достучаться до подписчика на явно названном канале (email и телефон не подходят: это не канал доставки). Существует, чтобы автор явно решал вопрос резервного канала, а не полагался на то, что отправка сама переключится. - Действие: меняет данные или запускает другую работу. Доступны:
- добавление и снятие меток, в том числе временных с
ttl_days; - изменение прав участника в указанном чате (
change_rights): блокировка, разблокировка, исключение, одобрение или отклонение заявки, заглушение, снятие заглушения и ограничение. Полеchat_idобязательно: шаг кампании выполняется без чата. Укажитеchat_idобычным числом, без пробелов, плюса и ведущих нулей. Например, чтобы исключить человека из закрытого чата через несколько дней после добавления метки, поставьте Задержку, затем Действие → Изменить права → Исключить. Доступные операции зависят от канала, см. Изменение прав по каналам; - удаление параметров. Установка, добавление и увеличение значения здесь недоступны, чтобы повтор шага после сбоя не менял данные дважды;
- синхронный веб-запрос. Фоновый режим и вложенные реакции на успех или
ошибку не поддерживаются. Заголовок
Idempotency-Keyплатформа задаёт сама и сохраняет одно и то же значение при повторе шага. Ваш сервер может по нему распознать дубликат; задать собственное значение нельзя; - синхронизация с подключённой CRM, назначение
диалога поддержки агенту или группе, отправка клиентского события через
track()для сегментов, воронок и подходящих триггеров, запуск lead-бота.
- добавление и снятие меток, в том числе временных с
- Цель и Выход: завершают путешествие. «Цель» означает успешное завершение, «Выход» – завершение без достижения цели. Настройки им не нужны.
Два письма после подписки
- Подготовьте условия для отправки: тариф с email, подтверждённый домен и настроенный способ доставки. Создайте и опубликуйте в Студии контента два документа типа Email.
- Создайте кампанию и выберите триггер «Подписка на email через поп-ап». В форме поп-апа добавьте обязательное поле email и отдельный флажок согласия на письма, затем включите подписку и выберите оба поля. Адрес должен быть подтверждён и связан с профилем; при необходимости посетитель может подтвердить его кодом в поп-апе. Подтверждение владения адресом само по себе не является согласием на рассылку.
- Соедините на схеме Контент → Задержка → Контент → Цель. В каждом узле Контент выберите канал email, опубликованный документ и укажите тему письма; прехедер необязателен. Настройте ветку «когда канал недоступен» и соедините её с Выходом.
- Выполните предпроверку, опубликуйте и запустите кампанию. После отправки формы посетитель получает отдельное письмо о подписке: ему нужно перейти по ссылке и подтвердить подписку на открывшейся странице. Только после этого возникает событие
$email_subscribedи может начаться цепочка. Уже оформленная подписка повторного события не создаёт. Убедитесь, что участник подписан и для него доступен email. Перед каждой отправкой сервис проверяет согласие и отписку: если человек отписался после первого письма, второе не отправится. Предпроверка не подтверждает фактическую доставку.
Если не удаётся использовать настройки SMTP
Если при отправке автоматического письма сервис не может использовать сохранённые настройки SMTP проекта, например расшифровать пароль, в истории путешествия появится причина «Проверьте настройки SMTP-сервера проекта». Шаг будет ждать исправления, не расходуя попытку и без списания за эту отправку. Сервис не переключится на платформенный сервер автоматически. Проверьте и сохраните настройки в разделе Email; после исправления шаг будет проверен снова автоматически.
Если до начала отправки не удалось подключиться к SMTP-серверу проекта, установить TLS или пройти авторизацию, шаг также ждёт восстановления без расхода попытки и списания. Проверьте подключение и учётные данные; после восстановления сервис автоматически повторит проверку. Другие ошибки SMTP, включая отказ на этапе MAIL или RCPT и ошибки после начала отправки, могут обрабатываться иначе.
Изменение прав по каналам
Возможность заблокировать или заглушить участника зависит от площадки. Перед выполнением платформа проверяет, доступна ли выбранная операция в указанном чате. Если нет, шаг завершится ошибкой, а путешествие останется на нём до следующей попытки. Частичного изменения прав не произойдёт.
- Telegram: доступны все восемь операций (забанить, разбанить, исключить,
одобрить заявку, отклонить заявку, заглушить, снять заглушение, ограничить)
в явно указанном в
chat_idчате: группе, супергруппе или канале, где бот администратор. - VK: сообщество модерирует только само себя. Доступны четыре операции:
забанить, разбанить, исключить, одобрить заявку, а
chat_idобязан быть равен идентификатору того самого подключённого сообщества (то же число, что показано у канала VK в разделе Каналы). Любое другое значение отклоняется: VK всё равно применил бы действие к подключённому сообществу, и граф говорил бы одно, а платформа делала другое. Заглушить, снять заглушение, ограничить и отклонить заявку в VK недоступны: у сообществ нет соответствующего API. - WhatsApp, Instagram Direct, Messenger, email и веб-виджет вовсе
не поддерживают управление правами участников: узел
change_rightsна таком канале всегда завершается ошибкой.
Предпроверка и публикация
POST /preflight проверяет текущий черновик, включая схему шагов и ссылки на сегменты, документы контента и эксперименты. Сообщения при этом не отправляются. В ответе есть ready, номер версии, контрольная сумма и ошибки с кодами invalid_graph или invalid_reference и пояснением. Предпроверка не считает аудиторию и не проверяет доступность каналов или согласие клиентов.
POST /publish повторяет проверку ссылок непосредственно перед публикацией. Даже если предпроверку пропустили или после неё удалили сегмент либо документ, кампания с недействительной ссылкой не будет опубликована. Нужна актуальная ревизия черновика. При устаревшей ревизии или повторной публикации того же черновика сервер сообщит о конфликте; частично опубликованной версии не останется.
Отчёт по версии и трейс путешествия
Отчёт (GET /report) строится для каждой версии отдельно. У версий N и N+1 разные счётчики; публикация новой версии не меняет цифры старой. Отчёт показывает, сколько клиентов вошли, остаются активными, ждут, находятся на повторной попытке, достигли цели, вышли или столкнулись с ошибкой. Для каждого шага также показано, сколько клиентов вошли в него, завершили его или получили ошибку.
Отчёт становится окончательным (sealed), когда версия больше не принимает новых клиентов и ни одно путешествие по ней уже не может продвинуться. Его цифры сохраняются и больше не пересчитываются. Отчёт работающей опубликованной версии обновляется при каждом чтении.
Чтобы понять, почему конкретный клиент не получил продолжение, откройте журнал его прохождения кампании, трейс (GET /journeys/{subscriberID}/{runNo}). Он показывает пройденные шаги, ожидания, выбранные ветки, повторные попытки и ошибки. Текст сообщений и ответы внешнего сервиса в журнал не копируются.
Флаг truncated означает, что событий оказалось больше лимита и часть записей не сохранилась. Список GET /failures показывает клиентов, у которых исчерпаны попытки выполнения шага. Такое прохождение можно запустить повторно: POST /journeys/{subscriberID}/{runNo}/retry.
Тихие часы
Каждая версия хранит настройки окна отправки. Включите тихие часы, чтобы откладывать узлы сообщения, контента и проверки доступности канала на время недельных интервалов или исключённых дат. После окончания запрета исполнитель проверяет узел заново. Закрытое окно само по себе не переводит клиента в ветку недоступного канала.
Выберите часовой пояс бота или получателя. Пояс получателя сейчас определяется для браузерных и мобильных push, а для мессенджеров используется пояс бота. Если пояс получателя неизвестен, также применяется пояс бота. Например, интервал 22:00–08:00 отложит ночное напоминание до разрешённого времени. Повторный вход настраивается отдельно у самой кампании.
Права
Для работы с кампаниями предусмотрены три отдельных права токена или роли: campaigns:read, campaigns:write и campaigns:publish. Публикация версии и повторный запуск остановившегося путешествия требуют иного права, чем редактирование черновика. Для всех трёх также нужно право бота «Реакции». Без него раздел кампаний не виден и недоступен даже для чтения.
Что дальше
- Рассылки: разовая отправка одного документа, без графа и без версий.
- Email-рассылки: похожий разовый сценарий для почты.
- Эксперименты и атрибуция: общий эксперимент, на который может ссылаться узел «Эксперимент».
- Люди (CRM): сегменты и метки для аудитории и триггеров.
- Студия контента: документы для узла «Контент».
- REST API и токены: маршруты кампаний и их scope.