Gotify Documentation¶

Installation¶

If you already have Gotify installed and running at https://push.yourdomain.com, skip this section. If not, follow the Gotify installation guide to set up your server.

Requirements¶

A server to host Gotify
Docker or direct binary installation
Domain name with HTTPS enabled (e.g., https://push.yourdomain.com)

Configuring Gotify¶

Creating an Application¶

Log in to your Gotify instance at https://push.yourdomain.com.
Navigate to the Applications tab.
Click Add Application.
Provide a name (e.g., My App) and optional description.
Note down the Application Token generated.

User Management¶

Gotify allows multiple users with different access levels. Navigate to Users to add and manage users.

Sending Notifications¶

API Endpoint¶

Send notifications using the following API endpoint:

POST https://push.yourdomain.com/message

Headers¶

Use the Application Token generated earlier for authentication. Include it as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_APPLICATION_TOKEN

Request Body¶

Send notifications with a JSON payload:

{
  "title": "Your Notification Title",
  "message": "Your notification message",
  "priority": 5
}

Priority Levels¶

0: Low priority
1-3: Moderate priority
4-8: High priority (default is 5)
>8: Emergency priority

Example cURL Request¶

curl -X POST https://push.yourdomain.com/message \
     -H "Authorization: Bearer YOUR_APPLICATION_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "title": "Hello World",
           "message": "This is a test notification.",
           "priority": 5
         }'

Response¶

A successful request returns:

{
  "id": 123,
  "appid": 1,
  "message": "This is a test notification.",
  "priority": 5,
  "title": "Hello World",
  "date": "2025-01-24T12:00:00Z"
}

Features¶

1. Priority Handling¶

Notifications can be categorized by priority levels. You can configure your client apps to handle them differently (e.g., display alerts only for high-priority messages).

2. Message Expiry¶

Gotify automatically purges older messages to save storage. You can configure message retention policies.

3. Plugins¶

Gotify supports plugins for extended functionality, such as email notifications or webhook triggers. Visit the Gotify Plugin Documentation for details.

4. Mobile Apps¶

Download the Gotify mobile app for Android or use third-party apps for iOS to receive push notifications on your phone.

5. Custom Webhook Integration¶

Gotify integrates seamlessly with services like Home Assistant, Grafana, and more via webhooks.

Advanced Usage¶

WebSocket Notifications¶

Gotify supports WebSocket connections for real-time notifications. You can connect using:

wss://push.yourdomain.com/stream?token=YOUR_APPLICATION_TOKEN

Filtering Messages¶

Clients can filter messages by priority or application using query parameters in the WebSocket URL.

Grouping Applications¶

Use separate applications for different notification categories (e.g., monitoring, alerts, logs) and manage them independently.

Example Integrations¶

1. Using Python¶

Install the requests library and send notifications:

import requests

url = "https://push.yourdomain.com/message"
token = "YOUR_APPLICATION_TOKEN"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}
data = {
    "title": "Test Notification",
    "message": "This is a test from Python",
    "priority": 5
}
response = requests.post(url, json=data, headers=headers)
print(response.json())

2. Using Node.js¶

Install axios and send notifications:

const axios = require('axios');

const url = 'https://push.yourdomain.com/message';
const token = 'YOUR_APPLICATION_TOKEN';

axios.post(url, {
  title: 'Test Notification',
  message: 'This is a test from Node.js',
  priority: 5
}, {
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
}).then(response => {
  console.log(response.data);
}).catch(error => {
  console.error(error);
});

3. Integration with Home Assistant¶

Add the following to your configuration.yaml:

notify:
  - name: Gotify
    platform: rest
    resource: https://push.yourdomain.com/message
    method: POST
    headers:
      Authorization: "Bearer YOUR_APPLICATION_TOKEN"
    data:
      priority: 5

Troubleshooting¶

Common Issues¶

Unauthorized Request: Ensure the Application Token is correct.
Connection Errors: Verify your server is accessible and HTTPS is properly configured.
Delayed Notifications: Check network connectivity or server load.

Debugging¶

Enable verbose logging on the Gotify server for more detailed error messages.

Resources¶

Conclusion¶

Gotify is a powerful, self-hosted notification solution that is simple to set up and use. With features like WebSocket support, priority handling, and integrations, it is an excellent choice for real-time notifications in your projects. Configure your instance at https://push.yourdomain.com and start sending notifications today!