gotify_flutter

Gotify push notifications for Flutter (Android) — self-hosted WebSocket receive, REST send, and local alerts. No Firebase required.

Send a message from Postman (or any HTTP client) → the app receives it in real time (system alert + in-app snackbar).

Compatible with Gotify 3.x. Android only for now.

---

Table of contents

• Features
• Getting started
• Usage
• Background delivery
• API overview
• Example
• How it works
• Author
• License

---

Features

• Login / restore session / logout with secure token storage
• Real-time WebSocket stream with auto-reconnect
• Send messages and load history via Gotify REST
• Android local notifications for incoming pushes
• Optional closed-app keep-alive (foreground service)
• One-command Android setup: dart run gotify_flutter:configure
• In-app handling via onMessage (SnackBar, dialogs, etc.)

---

Getting started

1. Add the dependency

dependencies:
  gotify_flutter: ^1.1.0

2. Install & configure Android

flutter pub get
dart run gotify_flutter:configure

That finishes Android setup (permissions, foreground service, desugaring, notification icon).

Flag	Purpose
--cleartext	Allow http:// Gotify URLs (local / dev only)
--dry-run	Preview changes without writing files

Prefer HTTPS in production.

---

Usage

Initialize

import 'package:gotify_flutter/gotify_flutter.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  GotifyBackgroundService.initCommunicationPort();
  runApp(const MyApp());
}

Login & listen

final gotify = GotifyPushClient();

await gotify.login(
  baseUrl: 'https://gotify.example.com',
  username: 'admin',
  password: 'your-password',
  clientName: 'My Flutter App',
);

await gotify.ensureSendApplication();

await gotify.startListening(); // foreground WebSocket; no sticky status bar

gotify.onMessage.listen((msg) {
  // Update UI — e.g. SnackBar / list
});

gotify.onConnectionState.listen((state) {
  // disconnected | connecting | connected | reconnecting
});

Restore a saved session

final session = await gotify.restoreSession();
if (session != null) {
  await gotify.startListening();
}

Send a message

await gotify.sendMessage(
  title: 'Hello',
  message: 'Push from Flutter',
  priority: 5,
);

In-app only (no system alert banners)

await gotify.startListening(showLocalNotifications: false);

gotify.onMessage.listen((msg) {
  // Show your own SnackBar / dialog
});

Test from Postman / HTTP

POST https://gotify.example.com/message
X-Gotify-Key: YOUR_APP_TOKEN
Content-Type: application/json

{
  "title": "Test",
  "message": "Hello from HTTP",
  "priority": 5
}

---

Background delivery (Android)

By default there is no permanent status notification.

Gotify has no FCM bridge. For delivery after the app is swiped away, opt in to a foreground service:

await gotify.startListening(
  keepAliveInBackground: true,
  keepAliveNotificationTitle: 'My App',
  keepAliveNotificationText: 'Running in background',
);

• Android requires the ongoing keep-alive notification (text is customizable; it cannot be fully hidden).
• Force-stop kills the process — pushes cannot be received until the app is opened again.
• Manifest / Gradle wiring is handled by dart run gotify_flutter:configure (and plugin merge).

---

API overview

GotifyPushClient

Method	Description
login(...)	Create client token (Gotify 3: shown once) and persist session
restoreSession()	Load saved session from secure storage
connectWithToken(...)	Attach an existing client token
ensureSendApplication()	Create/store an app token for sending
startListening()	WebSocket stream + optional local notifications
stopListening()	Close the stream / stop keep-alive
sendMessage(...)	Push via app token
getMessages()	Message history
logout()	Clear local session

Streams

• onMessage → GotifyMessage
• onConnectionState → GotifyStreamState

Logging

[gotify_flutter] Listener starting → https://…
[gotify_flutter] Connection state: connected
[gotify_flutter] Message #12 «Title»: body text

---

Example

Package example:

cd example
flutter pub get
dart run gotify_flutter:configure
flutter run

Monorepo demo app:

cd apps/gotify_demo
flutter pub get
flutter run

---

How it works

┌─────────────┐   REST POST /message    ┌──────────────┐
│  Your app / │ ───────────────────────►│ Gotify       │
│  HTTP client│      (app token)        │ Server       │
└─────────────┘                         └──────┬───────┘
                                               │ WebSocket /stream
                                               │ (client token)
                                        ┌──────▼───────┐
                                        │ Flutter app  │
                                        │ (Android)    │
                                        └──────────────┘

Token	Purpose
Application token	Send only
Client token	Receive stream

Per-client targeting by name is not supported by Gotify; use separate users if you need per-person delivery.

---

Author

Mirshad KVR Flutter · Android · Gotify pub.flutter-io.cn · GitHub · LinkedIn · Instagram

---

License

MIT — see LICENSE.