🚀 Deploy in less than 5 minutes

• Docker Compose ready.
• Raspberry Pi compatible.
• Jellyfin webhook integration.
• WhatsApp notifications with posters and trailers.
• No database required.

🎯 Key Features

• Smart Message Aggregation: Instead of flooding users with single texts when a season of a TV show indexes, notifications are batched into a single unified broadcast based on a configurable interval window.
• Quiet Hours Shield: Automatically holds back notifications received during late-night hours. Pending media aggregates silently in memory and flushes immediately as a single summary once morning hours kick in.
• One-Click Unsubscribe Link: Every single notification message attaches a dynamically-built, native WhatsApp deep-link (wa.me) passing a unique cancellation payload.
• Local-First Architecture: Eliminates complex database management. Subscriptions and runtime parameters are fully handled via lightweight, localized, system-synced JSON layers.
• Delivery Optimization & Smart Throttling: Multi-layered message pacing, batching, and rate-control mechanisms designed to improve notification delivery quality and reduce unnecessary message bursts across the Python and Node.js services.

📋 Template Management & Customization

Features a dynamic, decoupled templating system that allows you to fully customize the notification text, layout, and branding without modifying the source code.

🛡️ 4. Delivery Optimization & Rate Control

Delivering automated notifications to multiple recipients requires careful pacing to avoid excessive message bursts and maintain a consistent user experience.

To address this, the Notifications Engine implements a multi-layered delivery optimization strategy across the Python and Node.js services. By combining message aggregation, configurable scheduling, randomized delivery intervals, and content variation mechanisms, the system distributes notifications gradually and efficiently while reducing unnecessary traffic spikes.

⚡ Quick Start

Clone the repository and start the services:

git clone https://github.com/hfilippi/jellyfin-whatsapp.git

cd jellyfin-whatsapp

cp config/config.example.json config/config.json
cp config/users.example.json config/users.json

docker compose up -d --build