> 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. Откройте раздел **Конструктор** вашего проекта. 

<figure><img src="/files/5rvVq4iSivl0aPdzA6gE" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/jCcJGaIyikSUAWkIiglB" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Расположение шаблона именно в этой группе опционально, по API можно отправлять любые созданные шаблоны (node) на платформе.
{% endhint %}

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

<details>

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

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

<figure><img src="/files/kyLFQBDoseMv4UFgTi4E" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/WH04uv596sUPYHZONaRn" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/4R5aIfQVd7uATK2OOPCk" alt=""><figcaption></figcaption></figure>

4. Нажмите на кнопку `Сохранить`
5. Повторите действия для ВКонтакте

<figure><img src="/files/JceBOg7Z1jqoC3lb4euJ" alt=""><figcaption></figcaption></figure>

</details>

<details>

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

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

<figure><img src="/files/kyLFQBDoseMv4UFgTi4E" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/hTplKDK58rdO9dCJB3aD" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/LcovhBknB0dCn9s3uje1" alt=""><figcaption></figcaption></figure>

4. Нажмите на кнопку `Сохранить`
5. Повторите действия для ВКонтакте

<figure><img src="/files/kkUsADOF1wxS1okPlXsi" alt=""><figcaption></figcaption></figure>

</details>

<details>

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

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

<figure><img src="/files/kyLFQBDoseMv4UFgTi4E" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/4d2MH1QipeincApQsIf7" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/YKTyLEwnXMpEvqv4gDaq" alt=""><figcaption></figcaption></figure>

4. Нажмите на кнопку `Сохранить`
5. Нажмите на `+` для создания inline-кнопки под сообщением

<figure><img src="/files/0sKCAZssjWQDPiF3p23b" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/88G1z5wkW46El664ttX8" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/H60NDzQUNrUXop4nRpXm" alt=""><figcaption></figcaption></figure>

</details>

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` — убедитесь, что кампания с таким идентификатором уже создана в системе.

<details>

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

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

<figure><img src="/files/324zUPjHTHGG3gOqgBdF" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/h3ykYKKCCnx5sgNZXzQY" alt=""><figcaption></figcaption></figure>

4. Нажмите на кнопку `Сохранить`
5. Скопируйте uuid рассылки

<figure><img src="/files/YybVUbznx8TZQCZQ32Pb" alt=""><figcaption></figcaption></figure>

</details>

***

### Шаг 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`    | <p>типы событий, на которые хотите подписаться.<br><code>stream.status</code> - статус отправки сообщения<br><code>stream.reaction</code> - реакция пользователя на сообщение (<code>нажатие на кнопку</code>, <code>переход по ссылке</code>, <code>отправка ответа</code>)</p> |
| `webhook_platforms` | Платформы, события на которых нужно подписаться                                                                                                                                                                                                                                  |

<details>

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

{% 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 %}

</details>

<details>

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

{% code overflow="wrap" %}

```json
{
 "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
}
```

{% endcode %}

</details>

<details>

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

{% code overflow="wrap" %}

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

{% endcode %}

</details>

<details>

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

{% code overflow="wrap" %}

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

{% endcode %}

</details>

***

### Ограничения

#### Тротлинг

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

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

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

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

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

***

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

Перед тем как запустить отправку в 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