Как настроить каскадную рассылку — База знаний

Каскадная рассылка — это не рассылка по аудитории (о ней — в статье «Запустите первую рассылку по аудитории бота») и не push. Это последовательная попытка достучаться до одного конкретного человека по номеру телефона через несколько каналов подряд: сначала через самый дешёвый и доступный, и только если это не сработало — через более дорогой следующий. Настраивается и запускается каскад целиком через API — в отличие от рассылок по аудитории, в интерфейсе платформы для этого отдельного экрана нет.

Разберём весь путь на примере каскада BOT → WhatsApp → VK Notify: сначала бесплатная попытка через бота, если человека там нет — WhatsApp, и в последнюю очередь — VK Notify.

Что даёт такая последовательность

Если пользователь уже писал вашему боту и его можно найти по номеру телефона, сообщение уйдёт туда бесплатно, и до платных каналов дело не дойдёт вовсе. Если нет — подключаются WhatsApp и VK Notify по очереди, платно, но с максимальной вероятностью, что сообщение всё-таки дойдёт хоть по одному из каналов.

Что нужно, прежде чем начать

Функция каскадов должна быть подключена на проекте 🔧 (это делается на стороне Fasttrack — уточни у своего менеджера или в поддержке, если каскады ещё не появились в личном кабинете).
api-key — ключ доступа к API каскадов.
Настроенный сценарий (узел) чат-бота для бесплатного шага — понадобится его ID.
Одобренный WhatsApp-шаблон и шаблон VK Notify — понадобятся их идентификаторы (name).

Как устроен запрос

Endpoint: https://cascades.fstrk.io/api/v1/transactions/async/
Метод: POST
Заголовки: api-key (ключ доступа), Content-Type: application/json

Пример полного запроса на каскад BOT → WHATSAPP → VK_NOTIFY:

curl -i -X POST \
 https://cascades.fstrk.io/api/v1/transactions/async/ \
 -H 'api-key: < >' \
 -H 'Content-Type: application/json' \
 -d '{
 "phone_number": "<НОМЕР ТЕЛЕФОНА>",
 "routing": [
 "BOT",
 "WHATSAPP",
 "VK_NOTIFY"
 ],
 "bot_node_id": 00001,
 "variables": {
    "first_name": "Иван"
},
 "whatsapp_template_name": "meet_presentation",
 "whatsapp_template_variables": {
    "v1": "Иван"
},
 "vk_notify_template_name": "meet_presentation",
 "vk_notify_template_variables": {
    "v1": "Иван"
},
 "waiting_time_route": 60,
 "validity_period_seconds": 600,
 "tag": "nedozvon",
 "context": {
    "cascade": "nedozvon",
    "deal_id": "18547661"
}
 }'

Важно: маршруты в routing выполняются строго в том порядке, в котором перечислены — переставить WHATSAPP и VK_NOTIFY местами означает изменить порядок попыток.

Разбор параметров запроса

Параметр	Что задаёт
`phone_number`	Номер телефона получателя — по нему транзакция и ведётся через все каналы
`routing`	Список маршрутов по порядку: `BOT`, `WHATSAPP`, `VK_NOTIFY` и другие доступные каналы
`bot_node_id`	ID сценария (узла) чат-бота — это и есть бесплатный первый шаг каскада
`variables`	Переменные, которые будут доступны в сценарии узла, если сообщение ушло через бота
`whatsapp_template_name` / `whatsapp_template_variables`	Идентификатор одобренного WhatsApp-шаблона и его переменные
`vk_notify_template_name` / `vk_notify_template_variables`	То же самое для VK Notify
`waiting_time_route`	Сколько секунд ждать реакции на текущем маршруте, прежде чем перейти к следующему
`validity_period_seconds`	Через сколько секунд транзакция считается просроченной целиком, независимо от того, на каком маршруте она остановилась
`tag`	Произвольная метка транзакции — для последующего поиска и группировки
`context`	Любые свои данные (id сделки, номер заказа и т. п.), которые сохранятся вместе с транзакцией и вернутся в событиях о её статусе

Синхронный и асинхронный режим

Для боевого запуска используется асинхронный режим (/transactions/async/, показан выше) — лимит 10 запросов в секунду, а по каждой транзакции дальше прилетают события о статусе (см. ниже).

Для теста, когда просто нужно сразу увидеть результат запроса на запуск, есть синхронный метод — https://cascades.fstrk.io/api/v1/transactions/, с теми же параметрами и заголовками, но с лимитом 1 запрос в секунду и с ответом сразу в теле, без ожидания событий.

Режим	Endpoint	Лимит	Ответ
Асинхронный (боевой)	`.../transactions/async/`	10 RPS	`201` — задача поставлена в очередь, вернётся UUID транзакции; статус — через события
Синхронный (для теста)	`.../transactions/`	1 RPS	`201` — сразу полный JSON созданной транзакции; `400` — неверный запрос

Оба метода при превышении лимита возвращают 429.

Как отследить результат

По каждой транзакции на ваш callback URL приходят два типа событий:

Событие	Когда приходит
`transaction.done`	Транзакция завершена, а также при каждом обновлении статуса у провайдера (например, доставлено → прочитано)
`transaction.error`	Ошибка в запросе — например, шаблон WhatsApp не найден

Пример transaction.done:

{
 "event_type": "transaction.done",
 "payload": {
 "uuid": "cc1f638a-f039-48b9-8885-af161e2838f8",
 "done_at": "2024-02-01T07:43:57.106701Z",
 "done_status": "MESSAGE_SENT",
 "successful_routes": ["WHATSAPP"],
 "route_details": {
 "BOT": {
    "uuid": "...",
    "state": "ERROR",
    "response_status": null,
    "response_description": null
},
 "WHATSAPP": {
    "uuid": "...",
    "state": "SENT",
    "response_status": "DELIVERED",
    "response_description": null
},
 "VK_NOTIFY": {
    "uuid": "...",
    "state": "CANCELLED",
    "response_status": null,
    "response_description": null
}
 },
 "context": {
    "some": "value"
}
 },
 "timestamp": 1706773437.1262264
}

В этом примере видно всю логику каскада разом: BOT не сработал (пользователя не нашли в боте), WHATSAPP сработал и сообщение доставлено, а до VK_NOTIFY дело не дошло — маршрут отменён, потому что предыдущий уже отработал.

state — статус на стороне Fasttrack:

Значение	Значит
`CREATED`	Сообщение создано
`ENQUEUED`	В очереди на отправку
`IN_PROCESS`	Отправляется
`SENT`	Отправлено
`ERROR`	Ошибка при отправке
`CANCELLED`	Отправка отменена (обычно потому что сработал более ранний маршрут)

response_status — статус от провайдера канала:

Значение	Значит
`SENT`	Отправлено
`DELIVERED`	Доставлено
`READ`	Прочитано
`ERROR`	Ошибка при отправке
`UNDELIVERED`	Не доставлено

Коротко: от и до

Убедитесь, что каскады подключены на проекте, и есть api-key.
Подготовьте бесплатный шаг — сценарий бота (bot_node_id) — и платные шаги — одобренные шаблоны WhatsApp и VK Notify.
Соберите запрос: порядок маршрутов в routing, переменные для каждого канала, время ожидания (waiting_time_route) и общий срок жизни транзакции (validity_period_seconds), при желании — tag и context.
Для проверки — отправьте запрос синхронным методом (1 RPS, ответ сразу). Для боевого запуска — асинхронным (10 RPS, статус — через события).
Настройте приём событий transaction.done / transaction.error на своём callback URL, чтобы видеть, через какой канал реально ушло сообщение.