Приоритетные отправки сообщений

Приоритетные индивидуальные сообщения позволяют оперативнее доставить нужный контент конкретному пользователю — минуя очередь обычных сообщений API-рассылок.

---

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

Перед началом работы убедитесь, что выполнены следующие условия:

• Вы знаете идентификатор пользователя в нужном мессенджере (telegram_id или vkontakte_id).

• Для отправки через API: получен OAuth-токен . Подробнее о получении токена — в статье Подключение OAuth.

• В редакторе сценариев создан шаблон (node), который будет отправляться пользователю.

Важно: Если у пользователя нет активного чата с вашим ботом (он никогда не писал или заблокировал бота), сообщение не будет доставлено. Telegram и ВКонтакте запрещают первое входящее сообщение от бота без явного согласия пользователя.

---

Шаг 1. Подготовьте шаблон сценария

Приоритетное сообщение отправляет пользователю содержимое конкретного шаблона (node) вашего сценария — текст, кнопки, изображения и т. д.

1. Откройте раздел Конструктор вашего проекта.

1. Перейдите в группу Шаблоны для рассылок для хранения шаблонов для рассылок

Расположение шаблона именно в этой группе опционально, по API можно отправлять любые созданные шаблоны (node) на платформе.

1. Создайте новый шаблон или выберите существующий, который будет использоваться как шаблон сообщения.

Как создать шаблон для отправки текстового сообщения

1. Создайте новый узел и назовите его Шаблон только текст

1. Нажмите на + Создать сообщение

1. Вставьте конструкцию {{ get_params.text }}

1. Нажмите на кнопку Сохранить

2. Повторите действия для ВКонтакте

Как создать шаблон для отправки текста + картинки

1. Создайте новый узел и назовите его Шаблон картинка + текст

1. Нажмите на + Создать сообщение

1. Вставьте конструкцию ![{{ get_params.text }}]({{ get_params.pictureUrl }})

1. Нажмите на кнопку Сохранить

2. Повторите действия для ВКонтакте

Как создать шаблон для отправки текста + картинки + кнопка

1. Создайте новый узел и назовите его Шаблон картинка + текст + кнопка

1. Нажмите на + Создать сообщение

1. Вставьте конструкцию ![{{ get_params.text }}]({{ get_params.pictureUrl }})

1. Нажмите на кнопку Сохранить

2. Нажмите на + для создания inline-кнопки под сообщением

1. Заполните название кнопки, выберите действие Ссылка . В качестве значения ссылки укажите {{ get_params.url }}

1. Повторите действия для ВКонтакте

1. Запомните точное имя узла — оно будет передаваться в поле node.name при вызове API.

Осторожно: Имя узла и названия передаваемых параметров чувствительно к регистру и пробелам. Значение "Подтверждение заказа" и "подтверждение заказа" — это разные узлы.

---

Шаг 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": "priority_message",
  "payload": {
    "chat": {
      "telegram_id": 123456789
    },
    "content": {
      "type": "NODE",
      "node": {
        "name": "Имя шаблона"
      },
      "get_params": {
        "foo": "значение параметра"
      }
    },
    "campaign": {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "name": "Наименование кампании"
    }
  }
}

---

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

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

---

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

Поле	Тип	Обязательно	Описание
type	string	✅	Всегда "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}}, она будет подставлена значением "bar" из get_params. Если шаблон не использует переменные — передавать get_params не нужно.

---

Объединение отправок в кампанию

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

Достаточно передать одно из двух полей: либо uuid, либо name. Если передаёте uuid — убедитесь, что кампания с таким идентификатором уже создана в системе.

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

1. Перейдите в раздел Маркетинг → Push-сообщения

2. Нажмите на кнопку Новая рассылка

1. Придумайте название рассылки

1. Нажмите на кнопку Сохранить

2. Скопируйте uuid рассылки

---

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

Успешная отправка — HTTP 201

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Поле	Описание
uuid	UUID отправленного сообщения

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

---

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

Python

import requests

TOKEN = "ваш_oauth_токен"
API_URL = "https://dashboard.fstrk.io/api/partners/stream/"

payload = {
    "type": "priority_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 == 200:
    data = response.json()
    print(f"Сообщение отправлено. UUID: {data['message_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
}

Пример вебхука по событию 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
}

---

Ограничения

Тротлинг

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

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

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

• Пользователь должен быть известен боту. Если он ни разу не взаимодействовал с ботом — сообщение не уйдёт.

• Если пользователь заблокировал чат-бот сообщение не отправится.

• Имя узла должно существовать. Если переданное node.name не найдено в сценарии, запрос вернёт ошибку. Проверьте имя в редакторе сценариев.

• campaign.uuid и campaign.name — взаимозаменяемые поля. Не передавайте оба одновременно.

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

Осторожно: Не используйте приоритетные сообщения для массовых промо-рассылок — для этого предназначен модуль «Рассылки».

---

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

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

• OAuth-токен действителен и не истёк; в заголовке запроса указан корректный Bearer-токен.

• Имя узла в поле node.name точно совпадает с именем в редакторе сценариев (регистр, пробелы).

• Используется правильный идентификатор пользователя: telegram_id для Telegram, vkontakte_id для ВКонтакте.

• Частота запросов не превышает 15 в секунду — реализована очередь или задержка.

• В ответе сохраняется message_uuid для последующей отладки и трекинга.

---

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

• Подключение OAuth — как получить токен для авторизации в API

• Рассылки по API — массовая отправка сообщений по пользователям через API