# Уведомления и команды

> Сообщения пользователям подтверждённых подписок — уведомления, окно поверх и безопасные команды приложению, адресаты, расписание и ограничения.

Кабинет → «Сообщения» или [API](https://flowlock.cc/docs/api.md#сообщения). Приложения забирают сообщения при запуске, после
обновления подписки и раз в час, пока работают, — обычно сообщение доходит за час. Получают только
[подтверждённые](https://flowlock.cc/docs/providers.md) подписки.

## Уведомление

- **Заголовок** — до 100 символов, **текст** — до 2000, простой текст.
- **Ссылка** — `https://…`, кнопка «Открыть». Необязательно.
- **Перевод** на `ru` или `en`: пользователь видит свой язык, иначе основной текст.
- **Вид**:
  - обычное (`optional`) — системное уведомление и баннер в карточке подписки;
  - окно поверх (`force`) — окно поверх приложения.

## Команды

| Команда               | Что делает                                                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `update-subscription` | обновить подписку                                                                                                                                                  |
| `sub-change`          | сменить домен (`domain`) или адрес (`url`) подписки — только на ваш подтверждённый домен; `url` — только выбранным устройствам (у каждого пользователя свой адрес) |
| `import-data`         | предложить импорт: ссылка подписки, ссылки серверов, профиль, правила маршрутизации. **Пользователь всегда подтверждает**                                          |
| `set-settings`        | поменять настройки — ключи из таблицы [«Настройки приложения»](https://flowlock.cc/docs/app-management.md#настройки-приложения)                                                         |

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

## Кому и когда

- **Кому**: всем, по системам (`windows`, `macos`, `linux`) или выбранным устройствам — до 20, идентификаторы из
  раздела «Устройства» (там их можно отметить и сразу перейти к сообщению).
- **Когда**: сразу или по расписанию, до 30 дней вперёд.
- **Срок**: от часа до 30 дней, по умолчанию 7. После срока сообщение не доставляется.
- **Отмена** — в любой момент: кто ещё не получил, не получит.

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

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

- Рассылка всем или по системам — не больше 2 в сутки (с «Анлимитом» — 4) и не чаще раза в 5 минут.
- Выборочных сообщений — до 200 в час, до 20 устройств в каждом. Ждущих доставки — до 500.
- Приложение показывает не больше 3 уведомлений одного провайдера в сутки и одно окно поверх в час; лишние
  остаются в списке уведомлений карточки подписки.
- Реклама и спам запрещены: за них кабинет приостанавливают.

## Примеры API

```sh
# уведомление всем, с переводом
curl -s -X POST https://api.flowlock.cc/v1/provider/messages -H "Authorization: Bearer $FLOWLOCK_KEY" \
  -H 'Content-Type: application/json' -d '{
  "kind": "notification", "mode": "optional",
  "title": "Плановые работы", "body": "Сегодня с 02:00 до 03:00 МСК возможны перебои.",
  "link": "https://myvpn.example/status",
  "locales": {"en": {"title": "Maintenance", "body": "Tonight 23:00–00:00 UTC service may be interrupted."}},
  "target": {"all": true}, "expires_in": 86400}'

# обновить подписку на Windows и Linux по расписанию
curl -s -X POST https://api.flowlock.cc/v1/provider/messages -H "Authorization: Bearer $FLOWLOCK_KEY" \
  -H 'Content-Type: application/json' -d '{
  "kind": "command", "action": "update-subscription",
  "target": {"os": ["windows", "linux"]}, "send_at": "2026-11-01T09:00:00Z"}'
```

Все поля и остальные примеры — в [справочнике API](https://flowlock.cc/docs/api.md#сообщения).