Отправка рассылок через stream-api

  •  OAuth-токен действителен и не истёк; в заголовке запроса указан корректный Bearer-токен.
  •  Имя узла в поле node.name точно совпадает с именем в редакторе сценариев (регистр, пробелы).
  •  Используется правильный идентификатор пользователя: telegram_id для Telegram, vkontakte_id для ВКонтакте.
  •  Частота запросов не превышает 15 в секунду: реализована очередь или задержка.
  •  В ответе сохраняется uuid для последующей отладки и трекинга.

Обычные рассылки через stream-api позволяют отправить шаблон (узел) из сценария конкретному пользователю из внешней системы (CDP, CRM, бэкенд, сервис уведомлений).

Предварительные требования

  • У вас должны храниться идентификаторы пользователя в мессенджере: telegram_id или vkontakte_id.
  • Получен OAuth-токен для работы с API.
  • Потребуется создать шаблоны в редакторе сценариев, который будет отправляться.
  • У пользователя должен быть активный чат с ботом. Если он ни разу не взаимодействовал с ботом, сообщение не уйдёт.

Шаг 1. Подготовьте шаблон

  1. Создайте в «Конструкторе» узел с нужным контентом: текст, картинка, кнопка.
  2. Для подстановки значений из запроса используйте переменные вида {{ get_params.text }}, {{ get_params.pictureUrl }}, {{ get_params.url }}.
  3. Запомните точное имя узла. Имя чувствительно к регистру и пробелам: «Подтверждение заказа» и «подтверждение заказа» — разные узлы.

Шаг 2. Получите OAuth-токен

Все запросы к API авторизуются через Bearer-токен по схеме OAuth.

Полная инструкция по получению токена: Подключение OAuth.

После получения токена используйте его в заголовке каждого запроса:

Authorization: Bearer <_>

Шаг 3. Отправьте рассылку через API

Эндпоинт для отправки:

POST https://dashboard.fstrk.io/api/partners/stream/

Заголовки запроса:

ЗаголовокЗначение
Content-Typeapplication/json
AuthorizationBearer <ваш_токен>

Отправка в Telegram

{
 "type": "regular_message",
 "payload": {
 "chat": {
    "telegram_id": 123456789
},
 "content": {
 "type": "NODE",
 "node": {
    "name": "Имя шаблона"
},
 "get_params": {
    "foo": "значение параметра"
}
 },
 "campaign": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "Наименование кампании"
}
 }
}

Отправка во ВКонтакте

{
 "type": "regular_message",
 "payload": {
 "chat": {
    "vkontakte_id": 123456789
},
 "content": {
 "type": "NODE",
 "node": {
    "name": "Имя шаблона"
},
 "get_params": {
    "foo": "значение параметра"
}
 },
 "campaign": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "Наименование кампании"
}
 }
}

Описание полей запроса

ПолеТипОбязательноОписание
typestring✅Тип отправки: regular_message/priority_message для приоритетных отправок
payload.chat.telegram_idinteger✅*ID пользователя в Telegram
payload.chat.vkontakte_idinteger✅*ID пользователя во ВКонтакте
payload.content.typestring✅Всегда "NODE"
payload.content.node.namestring✅Имя шаблона для отправки
payload.content.get_paramsobject❌Динамические параметры для шаблона
payload.campaign.uuidstring (UUID)❌UUID рассылки для группировки статистики**
payload.campaign.namestring❌Название рассылки (альтернатива uuid)

* Укажите одно из двух: telegram_id или vkontakte_id — в зависимости от канала.
** Рассылка должна быть предварительно создана.

Важно: поле get_params используется для передачи переменных внутрь шаблона узла. Например, если в тексте узла используется переменная {{foo}}, она будет подставлена значением из get_params. Если шаблон не использует переменные, передавать get_params не нужно.

Объединение отправок в рассылку

Если вы отправляете сообщения в рамках одной акции или цепочки, передавайте campaign.uuid или campaign.name. Это позволит объединить всю статистику по отдельным отправкам в единый отчёт.

Достаточно передать одно из двух полей: либо uuid, либо name. Предварительно рассылку необходимо создать.

Как создать рассылку для группировки отправок:

  1. Перейдите в раздел Маркетинг → Push-сообщения.
  2. Нажмите Новая рассылка.
  3. Придумайте название рассылки.
  4. Нажмите Сохранить.
  5. Скопируйте uuid рассылки.

Шаг 4. Обработайте ответ

Успешная отправка возвращает HTTP 201:

{
    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
ПолеОписание
uuidUUID отправленного сообщения

Сохраняйте uuid в вашей системе: он понадобится для отладки и сверки статистики доставки.

Шаг 5. Пример кода для интеграции

Python

import requests
TOKEN = "ваш_oauth_токен"
API_URL = "https://dashboard.fstrk.io/api/partners/stream/"
payload = {
 "type": "regular_message",
 "payload": {
 "chat": {
    "telegram_id": 123456789
},
 "content": {
 "type": "NODE",
 "node": {
    "name": "Шаблон только текст"
},
 "get_params": {
    "text": "✅ Заказ ORD-9912 от 19.05.2026 успешно собран.\r\n\r\nСовсем скоро передадим его в доставку. Как только трек-номер будет готов — пришлем вам сообщение.\r\n\r\nСпасибо за покупку! 😊"
}
 },
 "campaign": {
    "name": "Подтверждения заказов — май 2026"
}
 }
}
response = requests.post(
 API_URL,
 json=payload,
 headers={"Authorization": f"Bearer {TOKEN}"}
)
if response.status_code == 201:
 data = response.json()
 print(f"Сообщение отправлено. UUID: {data['uuid']}")
else:
 print(f"Ошибка {response.status_code}: {response.text}")

Шаг 6. Получение статусов отправок

Для получения статусов отправок и реакций пользователей необходимо подписаться на вебхуки (единоразово):

curl -X 'PUT' \
 'https://dashboard.fstrk.io/api/partners/integrations/credentials/' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <_>' \
 -H 'Content-Type: application/json; camelcase=1' \
 -d '{
    "webhook_url": "https://your-domain.com/webhook",
    "webhook_events": [
 "stream.status",
    "stream.reaction"
 ],
    "webhook_platforms": [
 "Telegram",
    "Vkontakte"
 ]
}'
ПолеОписание
webhook_urlАдрес, на который нужно отправлять вебхуки
webhook_eventsТипы событий, на которые хотите подписаться: stream.status — статус отправки сообщения; stream.reaction — реакция пользователя на сообщение (нажатие на кнопку, переход по ссылке, отправка ответа)
webhook_platformsПлатформы, события на которых нужно получать

Пример вебхука по событию stream.status

{
 "event_type": "stream.status",
 "payload": {
    "uuid": "93275992-9d27-4e59-88e9-f3e8a351c056",
    "status": "UNDELIVERED | SENT | DELIVERED | IN_PROCESS | READ",
    "status_detail": "описание ошибки"
},
 "timestamp": 1739272006194
}

Поле status принимает одно из значений: UNDELIVERED, SENT, DELIVERED, IN_PROCESS, READ. В status_detail приходит описание ошибки.

Пример вебхука по событию stream.reaction (переход по ссылке)

{
 "event_type": "stream.reaction",
 "payload": {
    "uuid": "<uuid>",
    "jumped_url": "https://ya.ru",
    "jumped_url_at": "2026-02-13T13:38:23.493618+00:00"
},
 "timestamp": 1770989903682
}

Пример вебхука по событию stream.reaction (нажатие на кнопку)

{
 "event_type": "stream.reaction",
 "payload": {
    "uuid": "<uuid>",
    "clicked_name": "Меню",
    "clicked_at": "2026-02-13T13:38:04.702250+00:00"
},
 "timestamp": 1770989884882
}

Пример вебхука по событию stream.reaction (написал в ответ)

{
 "event_type": "stream.reaction",
 "payload": {
    "uuid": "<uuid>",
    "replied_at": "2026-02-13T13:38:04.702250+00:00",
    "replied_content": "сколько стоит?"
},
 "timestamp": 1770989884882
}

uuid в вебхуках совпадает с uuid сообщения из ответа на отправку (шаг 4).

Ограничения

Тротлинг

Эндпоинт /api/partners/stream/ ограничен 15 запросами в секунду. При превышении лимита вы получите ответ HTTP 429 Too Many Requests.

Если нужно отправить сообщения нескольким тысячам пользователей, используйте очередь с равномерным распределением запросов.

Прочие ограничения

  • Пользователь должен быть известен боту. Если он ни разу не взаимодействовал с ботом, сообщение не уйдёт.
  • Если пользователь заблокировал чат-бот, сообщение не отправится.
  • Имя узла должно существовать. Если переданное node.name не найдено в сценарии, запрос вернёт ошибку. Проверьте имя в редакторе сценариев.
  • campaign.uuid и campaign.name — взаимозаменяемые поля. Не передавайте оба одновременно.
  • get_params не валидируется на сервере. Если передать параметр, которого нет в шаблоне, он будет проигнорирован. Если не передать нужный, переменная в тексте останется незаполненной, что может привести к ошибке при отправке.

Чеклист для самопроверки

Перед тем как запустить отправку в production, убедитесь:

Связанные статьи