Транзакционные сообщения и каскады

Транзакционные сообщения — подтверждения заказа, коды входа, уведомления о доставке. Покупатель их ждёт, поэтому они уходят сразу и через отдельную очередь: большая рассылка их не задерживает. Каскад отправляет одно сообщение по нескольким каналам по очереди. Например, сначала WhatsApp, а если за 2 минуты не доставлено — SMS.

Отправить такое сообщение можно из цепочки или со своего сервера через API.

Транзакционный шаблон

Чтобы сообщение считалось транзакционным, отметьте Транзакционное сообщение в его шаблоне. Такое сообщение уходит без проверки подписки, частотных ограничений и тихих часов. Письма через почтовый сервис OneTrace.ru отправляются без прогрева и отдельным потоком, без ссылки отписки в заголовках.

Не отмечайте так рекламу: это нарушает права получателей и портит репутацию отправителя.

Даже транзакционное сообщение не уходит, если канал у получателя закрыт:

Канал	Когда закрыт
Email	письмо на адрес вернулось с постоянной ошибкой (ящика нет)
SMS, WhatsApp	провайдер сообщил, что номера не существует; покупатель написал «стоп» в WhatsApp
Telegram	покупатель отправил боту /stop или заблокировал его
Viber	покупатель отписался от бота

Такое сообщение получает статус «Пропущено» с причиной «канал заблокирован у получателя». Канал снова открывается, когда покупатель подписывается заново — например, нажимает «Start» в боте. Жалоба на спам канал не закрывает: письма о заказах на этот адрес продолжают приходить.

Отправка через API

Ваш сервер отправляет сообщение запросом POST /api/v1/messages. Нужен секретный ключ с правом «Отправка отдельных сообщений», см. API-ключи.

curl -X POST https://cdp.onetrace.ru/api/v1/messages \
  -H "Authorization: Bearer $CDP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1001" \
  -d '{
    "identity": {"type": "email", "value": "anna@example.com"},
    "template_id": 12,
    "traits": {"first_name": "Анна"},
    "data": {"order_id": "A-1001", "amount": 4990}
  }'

Поле	Что значит
`identity`	Получатель: тип и значение идентификатора — `email`, `phone`, `user_id`, `telegram_chat_id` и другие. Если профиля нет, он создаётся
`template_id`	Шаблон сообщения. Его id виден в адресе страницы шаблона
`integration_id`	Интеграция канала шаблона. Нужна, только если у канала несколько активных интеграций
`traits`	Трейты, которые запишутся в профиль до отправки. В шаблоне — `{{ traits.first_name }}`
`data`	Данные только этого сообщения. В шаблоне — `{{ context.data.order_id }}`

Ответ 202 содержит id сообщения и его статус. Текущий статус возвращает GET /api/v1/messages/{id}: queued, sent, delivered, failed, skipped и другие, с причиной пропуска или ошибки.

Повтор безопасен. Запрос с тем же заголовком Idempotency-Key возвращает уже созданное сообщение, второе не отправляется. Используйте номер заказа или id операции.
Предел на получателя — 20 сообщений в час через API. При превышении придёт 429 с заголовком Retry-After.
Обычный шаблон без отметки «Транзакционное» тоже можно отправить через API. Тогда проверяются все правила рассылок.

В готовой PHP-библиотеке это $onetrace->messages()->send(Identity::email('anna@example.com'), 12, ['data' => [...]], 'order-A-1001'), в пакете для Laravel — тот же метод messages()->send(...) фасада.

Каскад в цепочке

Добавьте в цепочку узел Каскадная отправка из группы «Действия». В поле Каналы по очереди задайте от 2 до 5 шагов. Для каждого шага укажите:

Интеграцию и Шаблон канала.
Ждать — что считать успехом: «отправлено», «доставлено» или «прочитано».
Время ожидания — для «доставлено» и «прочитано», по умолчанию 15 минут.

Настройки узла «Каскадная отправка»: SMS, а если не доставлено за 10 минут — письмо

Каскад переходит к следующему шагу, если:

у профиля нет адреса или номера для канала, или канал у него закрыт — шаг пропускается сразу, сообщение не создаётся;
сообщение не ушло: ошибка отправки или пропуск по правилам рассылок;
провайдер сообщил о недоставке;
за время ожидания не пришло подтверждение доставки или прочтения.

Ждать доставки и прочтения можно не во всех каналах:

Ждать	Каналы
отправлено	все
доставлено	SMS, WhatsApp, Viber, Telegram, вебхук; email — только через почтовый сервис OneTrace.ru, не через свой SMTP-сервер
прочитано	email, WhatsApp, Viber

У узла два выхода: дошло — сообщение одного из шагов достигло цели; ошибка — ни один канал не сработал. Пока каскад идёт, участник ждёт на узле.

Каскадная отправка доставляет одно и то же сообщение. Шаблоны цепочек вида «Корзина: push → email → SMS» устроены иначе: там разные сообщения уходят с паузами, пока покупатель не сделает заказ.

Каскад через API

Вместо template_id передайте steps — те же шаги, что в узле цепочки:

{
  "identity": {"type": "phone", "value": "+79991234567"},
  "steps": [
    {"integration_id": 3, "template_id": 21, "wait_for": "delivered", "timeout": {"amount": 2, "unit": "minute"}},
    {"integration_id": 4, "template_id": 22, "wait_for": "sent"}
  ],
  "data": {"code": "482913"}
}

wait_for принимает sent, delivered или opened, единицы timeout — minute, hour, day, week. Ответ 202 содержит id каскада, GET /api/v1/messages/cascades/{id} возвращает его состояние:

status — running, reached или failed;
текущий шаг step;
канал, который сработал, — reached_channel;
сообщения шагов messages.

Тариф

Транзакционные сообщения и отправка через API доступны на всех тарифах. Каскад — с тарифа «Рост», см. Тариф и оплата. На «Старте» узел в палитре редактора отмечен замком, а API отвечает 402. Если тариф понизили, в уже работающих цепочках отправляется только первый шаг каскада.