# Notifications and commands

> Messages to users of verified subscriptions: notifications, a window on top and safe commands to the app, recipients, scheduling and limits.

Cabinet → “Messages”, or the [API](https://flowlock.cc/en/docs/api.md#messages). Apps fetch messages at launch, after a subscription refresh
and every hour while they run, so a message usually arrives within an hour. Only [verified](https://flowlock.cc/en/docs/providers.md)
subscriptions receive them.

## Notification

- **Title**: up to 100 characters; **text**: up to 2000, plain text.
- **Link**: `https://…`, shown as an “Open” button. Optional.
- **Translation** into `ru` or `en`: the user sees their own language, otherwise the main text.
- **How to show it**:
  - regular (`optional`): a system notification and a banner on the subscription card;
  - window on top (`force`): a window over the app.

## Commands

| Command               | What it does                                                                                                                                                         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update-subscription` | refresh the subscription                                                                                                                                             |
| `sub-change`          | change the subscription's domain (`domain`) or address (`url`), only to your verified domain; `url` goes to selected devices only (every user has their own address) |
| `import-data`         | offer an import: a subscription link, server links, a profile, routing rules. **The user always confirms**                                                           |
| `set-settings`        | change settings, with keys from the [“App settings”](https://flowlock.cc/en/docs/app-management.md#app-settings) table                                                                       |

Before changing the address, the app checks that the new domain is verified by your cabinet; if the subscription
doesn't load from the new address, the old one comes back.

## To whom and when

- **To**: everyone, by system (`windows`, `macos`, `linux`) or selected devices, up to 20, with identifiers from the
  “Devices” section (you can tick them there and go straight to a message).
- **When**: now or on a schedule, up to 30 days ahead.
- **Delivery window**: from an hour to 30 days, 7 by default. After it the message is not delivered.
- **Cancel** at any time: those who haven't received it yet won't.

For each message you can see how many devices received it, saw it, opened the link, did it, declined or failed to do
it.

## Limits

- Messages to everyone or by system: no more than 2 a day (4 with Unlimited), at most once in 5 minutes.
- Messages to selected devices: up to 200 an hour, up to 20 devices each. Up to 500 waiting for delivery.
- The app shows at most 3 notifications from one provider a day and one window on top an hour; the rest stay in the
  notification list on the subscription card.
- Advertising and spam are forbidden: the cabinet gets suspended for them.

## API examples

```sh
# notification to everyone, with a translation
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": "Maintenance", "body": "Tonight 23:00 to 00:00 UTC service may be interrupted.",
  "link": "https://myvpn.example/status",
  "locales": {"ru": {"title": "Плановые работы", "body": "Сегодня с 02:00 до 03:00 МСК возможны перебои."}},
  "target": {"all": true}, "expires_in": 86400}'

# refresh the subscription on Windows and Linux on a schedule
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"}'
```

All the fields and more examples are in the [API reference](https://flowlock.cc/en/docs/api.md#messages).