Would you like to automatically notify your friends and family whenever new content is added to your library? This tool allows your Jellyfin users to receive updates about your latest additions via WhatsApp.

Surprise them with new releases, childhood movies you used to share, or those classics everyone wants to watch again. Everything is handled automatically, securely, and non-intrusively.

This is an open-source project under the MIT license, allowing anyone to improve it, contribute new features, or customize it to their needs.

⚙️How it works

• Jellyfin Media Server: The process begins when new content is added or a library event triggers on your Jellyfin server.
• Webhook: Jellyfin triggers a webhook endpoint configured for ‘Media Added / Library Event’ notifications.
• jellyfin-whatsapp Notification Engine: This core engine receives the webhook payload. It processes the event by applying aggregation and filtering, checking quiet hours, matching users, and scheduling message delivery. It relies on Local JSON Storage to manage configurations (config.json), user preferences (users.json), and message layouts (templates.json).
• WhatsApp Message: Finally, a WhatsApp message containing the movie poster, trailer link, and full details (such as title, year, TMDB rating, genres, and metadata links) is automatically sent to the users via a dedicated bot.

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

🛡️ 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

Then:

1. Configure Jellyfin webhooks to point to http://<host>:8000/jellyfin.
2. Scan the WhatsApp QR code generated by the gateway service.
3. Edit /config/config.json.
4. Add subscribers to /config/users.json.
5. Enjoy automated notifications!