> For the complete documentation index, see [llms.txt](https://docs.fstrk.io/knowledge_base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fstrk.io/knowledge_base/outbound-campaigns/prioritetnye-otpravki-soobshenii.md).
# Приоритетные отправки сообщений
Приоритетные индивидуальные сообщения позволяют оперативнее доставить нужный контент конкретному пользователю — минуя очередь обычных сообщений API-рассылок.
***
### Предварительные требования
Перед началом работы убедитесь, что выполнены следующие условия:
* Вы знаете **идентификатор пользователя** в нужном мессенджере (`telegram_id` или `vkontakte_id`).
* Для отправки через API: получен **OAuth-токен** . Подробнее о получении токена — в статье [Подключение OAuth](https://docs.fstrk.io/knowledge_base/intagrations/podklyuchenie-oauth).
* В редакторе сценариев создан **шаблон (node)**, который будет отправляться пользователю.
> **Важно:** Если у пользователя нет активного чата с вашим ботом (он никогда не писал или заблокировал бота), сообщение не будет доставлено. Telegram и ВКонтакте запрещают первое входящее сообщение от бота без явного согласия пользователя.
***
### Шаг 1. Подготовьте шаблон сценария
Приоритетное сообщение отправляет пользователю содержимое конкретного **шаблона (node)** вашего сценария — текст, кнопки, изображения и т. д.
1. Откройте раздел **Конструктор** вашего проекта.
2. Перейдите в группу **Шаблоны для рассылок** для хранения шаблонов для рассылок
{% hint style="info" %}
Расположение шаблона именно в этой группе опционально, по API можно отправлять любые созданные шаблоны (node) на платформе.
{% endhint %}
3. Создайте новый шаблон или выберите существующий, который будет использоваться как шаблон сообщения.
Как создать шаблон для отправки текстового сообщения
1. Создайте новый узел и назовите его `Шаблон только текст`
2. Нажмите на `+ Создать сообщение`
3. Вставьте конструкцию `{{ get_params.text }}`
4. Нажмите на кнопку `Сохранить`
5. Повторите действия для ВКонтакте
Как создать шаблон для отправки текста + картинки
1. Создайте новый узел и назовите его `Шаблон картинка + текст`
2. Нажмите на `+ Создать сообщение`
3. Вставьте конструкцию ``
4. Нажмите на кнопку `Сохранить`
5. Повторите действия для ВКонтакте
Как создать шаблон для отправки текста + картинки + кнопка
1. Создайте новый узел и назовите его `Шаблон картинка + текст + кнопка`
2. Нажмите на `+ Создать сообщение`
3. Вставьте конструкцию ``
4. Нажмите на кнопку `Сохранить`
5. Нажмите на `+` для создания inline-кнопки под сообщением
6. Заполните название кнопки, выберите действие `Ссылка` . В качестве значения ссылки укажите `{{ get_params.url }}`
7. Повторите действия для ВКонтакте
3. Запомните **точное имя узла** — оно будет передаваться в поле `node.name` при вызове API.
> **Осторожно:** Имя узла и названия передаваемых параметров чувствительно к регистру и пробелам. Значение `"Подтверждение заказа"` и `"подтверждение заказа"` — это разные узлы.
***
### Шаг 2. Получите OAuth-токен
Все запросы к API авторизуются через **Bearer-токен** по схеме OAuth.
Полная инструкция по получению токена: [Подключение OAuth →](https://docs.fstrk.io/knowledge_base/intagrations/podklyuchenie-oauth)
После получения токена используйте его в заголовке каждого запроса:
```
Authorization: Bearer <ваш_токен>
```
***
### Шаг 3. Отправьте приоритетное сообщение через API
Эндпоинт для отправки:
```
POST https://dashboard.fstrk.io/api/partners/stream/
```
**Заголовки запроса:**
| Заголовок | Значение |
| --------------- | -------------------- |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer <ваш_токен>` |
***
#### Отправка в Telegram
```json
{
"type": "priority_message",
"payload": {
"chat": {
"telegram_id": 123456789
},
"content": {
"type": "NODE",
"node": {
"name": "Имя шаблона"
},
"get_params": {
"foo": "значение параметра"
}
},
"campaign": {
"uuid": "00000000-0000-0000-0000-000000000000",
"name": "Наименование кампании"
}
}
}
```
***
#### Отправка во ВКонтакте
```json
{
"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. Нажмите на кнопку `Новая рассылка`
3. Придумайте название рассылки
4. Нажмите на кнопку `Сохранить`
5. Скопируйте uuid рассылки
***
### Шаг 4. Обработайте ответ
#### Успешная отправка — HTTP 201
```json
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```
| Поле | Описание |
| ------ | ---------------------------- |
| `uuid` | UUID отправленного сообщения |
Сохраняйте `message_uuid` в вашей системе — он понадобится для отладки и сверки статистики доставки.
***
### Шаг 5. Пример кода для интеграции
#### Python
```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. Получение статусов отправок
Для получения статусов отправок необходимо подписаться на вебхуки (**единоразово**).
{% code overflow="wrap" %}
```
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"
]
}'
```
{% endcode %}
| Поле | Описание |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `webhook_url` | адрес, на который нужно отправлять вебхуки |
| `webhook_events` |
типы событий, на которые хотите подписаться. stream.status - статус отправки сообщения stream.reaction - реакция пользователя на сообщение (нажатие на кнопку, переход по ссылке, отправка ответа)
|
| `webhook_platforms` | Платформы, события на которых нужно подписаться |
Пример вебхука по событию stream.status
{% code overflow="wrap" %}
```json
{
"event_type": "stream.status",
"payload": {
"uuid": "93275992-9d27-4e59-88e9-f3e8a351c056",
"status": "UNDELIVERED | SENT | DELIVERED | IN_PROCESS | READ",
"status_detail": "описание ошибки",
},
"timestamp": 1739272006194
}
```
{% endcode %}
Пример вебхука по событию stream.reaction (переход по ссылке)
{% code overflow="wrap" %}
```json
{
"event_type": "stream.reaction",
"payload": {
"uuid": "",
"jumped_url": "https://ya.ru",
"jumped_url_at": "2026-02-13T13:38:23.493618+00:00"
},
"timestamp": 1770989903682
}
```
{% endcode %}
Пример вебхука по событию stream.reaction (нажатие на кнопку)
{% code overflow="wrap" %}
```json
{
"event_type": "stream.reaction",
"payload": {
"uuid": "",
"clicked_name": "Меню",
"clicked_at": "2026-02-13T13:38:04.702250+00:00"
},
"timestamp": 1770989884882
}
```
{% endcode %}
Пример вебхука по событию stream.reaction (написал в ответ)
{% code overflow="wrap" %}
```json
{
"event_type": "stream.reaction",
"payload": {
"uuid": "",
"replied_at": "2026-02-13T13:38:04.702250+00:00",
"replied_content": "сколько стоит?"
},
"timestamp": 1770989884882
}
```
{% endcode %}
***
### Ограничения
#### Тротлинг
Эндпоинт `/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](https://docs.fstrk.io/knowledge_base/intagrations/podklyuchenie-oauth) — как получить токен для авторизации в API
* [Рассылки по API](/knowledge_base/push-messages/api.md) — массовая отправка сообщений по пользователям через API
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.fstrk.io/knowledge_base/outbound-campaigns/prioritetnye-otpravki-soobshenii.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.