- OAuth-токен действителен и не истёк; в заголовке запроса указан корректный Bearer-токен.
- Имя узла в поле
node.nameточно совпадает с именем в редакторе сценариев (регистр, пробелы). - Используется правильный идентификатор пользователя:
telegram_idдля Telegram,vkontakte_idдля ВКонтакте. - Частота запросов не превышает 15 в секунду: реализована очередь или задержка.
- В ответе сохраняется
uuidдля последующей отладки и трекинга.
Обычные рассылки через stream-api позволяют отправить шаблон (узел) из сценария конкретному пользователю из внешней системы (CDP, CRM, бэкенд, сервис уведомлений).
Предварительные требования
- У вас должны храниться идентификаторы пользователя в мессенджере:
telegram_idилиvkontakte_id. - Получен OAuth-токен для работы с API.
- Потребуется создать шаблоны в редакторе сценариев, который будет отправляться.
- У пользователя должен быть активный чат с ботом. Если он ни разу не взаимодействовал с ботом, сообщение не уйдёт.
Шаг 1. Подготовьте шаблон
- Создайте в «Конструкторе» узел с нужным контентом: текст, картинка, кнопка.
- Для подстановки значений из запроса используйте переменные вида
{{ get_params.text }},{{ get_params.pictureUrl }},{{ get_params.url }}. - Запомните точное имя узла. Имя чувствительно к регистру и пробелам: «Подтверждение заказа» и «подтверждение заказа» — разные узлы.
Шаг 2. Получите OAuth-токен
Все запросы к API авторизуются через Bearer-токен по схеме OAuth.
Полная инструкция по получению токена: Подключение OAuth.
После получения токена используйте его в заголовке каждого запроса:
Authorization: Bearer <_>
Шаг 3. Отправьте рассылку через API
Эндпоинт для отправки:
POST https://dashboard.fstrk.io/api/partners/stream/
Заголовки запроса:
| Заголовок | Значение |
|---|---|
Content-Type | application/json |
Authorization | Bearer <ваш_токен> |
Отправка в 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": "Наименование кампании"
}
}
}
Описание полей запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
type | string | ✅ | Тип отправки: regular_message/priority_message для приоритетных отправок |
payload.chat.telegram_id | integer | ✅* | ID пользователя в Telegram |
payload.chat.vkontakte_id | integer | ✅* | ID пользователя во ВКонтакте |
payload.content.type | string | ✅ | Всегда "NODE" |
payload.content.node.name | string | ✅ | Имя шаблона для отправки |
payload.content.get_params | object | ❌ | Динамические параметры для шаблона |
payload.campaign.uuid | string (UUID) | ❌ | UUID рассылки для группировки статистики** |
payload.campaign.name | string | ❌ | Название рассылки (альтернатива uuid) |
* Укажите одно из двух: telegram_id или vkontakte_id — в зависимости от канала.
** Рассылка должна быть предварительно создана.
Важно: поле
get_paramsиспользуется для передачи переменных внутрь шаблона узла. Например, если в тексте узла используется переменная{{foo}}, она будет подставлена значением изget_params. Если шаблон не использует переменные, передаватьget_paramsне нужно.
Объединение отправок в рассылку
Если вы отправляете сообщения в рамках одной акции или цепочки, передавайте campaign.uuid или campaign.name. Это позволит объединить всю статистику по отдельным отправкам в единый отчёт.
Достаточно передать одно из двух полей: либо uuid, либо name. Предварительно рассылку необходимо создать.
Как создать рассылку для группировки отправок:
- Перейдите в раздел Маркетинг → Push-сообщения.
- Нажмите Новая рассылка.
- Придумайте название рассылки.
- Нажмите Сохранить.
- Скопируйте
uuidрассылки.
Шаг 4. Обработайте ответ
Успешная отправка возвращает HTTP 201:
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
| Поле | Описание |
|---|---|
uuid | UUID отправленного сообщения |
Сохраняйте 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, убедитесь:
Связанные статьи
- Подключение OAuth — как получить токен для авторизации в API.
- Приоритетные отправки сообщений — индивидуальная отправка вне общей очереди.