Documentation · For providers

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. 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 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” 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

# 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.

This page in Markdown · Every page is available as Markdown: add .md to its address without the trailing slash. The list is in llms.txt, everything at once in llms-full.txt.