The Problem
Media‑request workflows in home‑theater setups often require manual navigation of a web UI (e.g., Seerr/Jellyseerr). Users on the same household network must switch devices to submit a request, leading to friction and missed titles.
What This Does
whatseerr bridges WhatsApp and Seerr, turning a simple chat into a request channel. The core server lives in lib/server.js, exposing two webhook endpoints (/requests for WAHA messages and /seerr for Seerr notifications). Incoming WhatsApp texts are parsed by lib/command-parser.js and routed through command classes such as lib/commands/search-command.js and lib/commands/selection-command.js.
State handling (user‑phone mapping, rate‑limiting, duplicate detection) is implemented in lib/state/cache-state.js and the middleware stack under lib/middleware/. Requests are queued via lib/queue/message-queue.js before being sent to Seerr through lib/http-client.js. The CLI entry point cli.js can launch the server directly, while Docker provides an isolated runtime.
How To Use It
Setup (Docker – recommended)
Pull the published image docker pull ghcr.io/sufxgit/whatseerr:latest
Create a persistent config directory
mkdir -p /path/to/config
Run the container (adjust TZ and ports as needed) docker run -d \ --name whatseerr-bot \ -p 3006:3006 \ -v /path/to/config:/config \ -e TZ=UTC \ ghcr.io/sufxgit/whatseerr:latest
If you prefer a local Node environment:
git clone https://github.com/SuFxGIT/whatseerr.git cd whatseerr npm ci # installs exact versions from package-lock.json cp config/config.example.json config/config.json Edit config/config.json with your Seerr API key, WAHA key, and phone‑to‑user mappings node cli.js # starts lib/server.js
Configuration
File: config/config.example.json → rename to config/config.json. Required fields: jellyseerr.apiKey – Seerr API key. waha.apiKey – WAHA HTTP API key. userIdMappings – map raw WhatsApp numbers (e.g., "1234567890") to Seerr userId and optional admin flag. Optional env var: TZ for container timezone (default UTC).
Running the Bot
Docker: container automatically runs node lib/server.js (see Dockerfile). Local: node cli.js starts the Express server on the port defined in config.json (webhook.requests.port defaults to 3006).
Interaction Flow
Send r The Matrix to the WAHA‑linked WhatsApp number. lib/commands/search-command.js queries Seerr, formats results via lib/message-formatters.js, and replies with a numbered list. Reply with a number (e.g., 1). lib/commands/selection-command.js creates a request payload and posts it through lib/http-client.js.
Real‑World Use
A household with a Plex server runs Seerr on http://seerr.local:5055. The user runs whatseerr on a Raspberry Pi behind the same LAN, exposing port 3006. WAHA is configured to forward WhatsApp messages to http://raspberrypi.local:3006/requests. Family members simply text “r Inception” to the shared WhatsApp number, and the bot automatically creates a request in Seerr under the correct user profile.
User (WhatsApp) → WAHA → /requests (whatseerr) → Seerr API → Request created
Code Health & Issues
Medium – No automated tests – repository contains no *.test.js files; code paths are unverified. Low – Limited CI – GitHub Actions only builds/publishes Docker image; no lint, type‑check, or security scanning steps. Low – Potential race condition – lib/queue/message-queue.js processes messages sequentially but lacks explicit back‑pressure handling under high load. Low – Input validation present but not exhaustive – validation schemas in lib/validation/schemas.js cover basic fields; complex payloads (e.g., custom request options) may bypass checks. Low – Documentation gaps – README covers Docker usage but does not detail the local‑node start command or required Node version. None – License – a LICENSE file is present, satisfying open‑source compliance.
The Bottom Line
whatseerr provides a functional, Docker‑first bridge between WhatsApp and Seerr, enabling quick media requests without a browser. The code is organized and configurable, but the lack of tests and minimal CI mean you should evaluate stability in your environment before production reliance. Suitable for tech‑savvy home users or small‑scale deployments where rapid setup outweighs formal quality guarantees.