ZNC to Ntfy IRC Bridge

A lightweight Python service that connects directly to a ZNC bouncer 24/7, monitors configured IRC channels and direct messages (DMs), logs all activity to the terminal, and conditionally pushes notifications to a self-hosted or public ntfy server.

Features

• Multi-Network & Channel Monitoring: Connects to multiple ZNC networks and tracks various channels simultaneously.
• Per-Channel Alert Toggling: Selectively enable or disable push alerts per channel.
• Smart Keyword Triggering: Restrict alerts to only messages containing specific keywords (e.g., your name or warnings) when you don't want every message pushed.
• Direct Message (DM) Forwarding: Captures private messages sent directly to your user and routes them to a dedicated DM topic.
• Custom Ntfy Topics: Override default topic structures per channel or use automatic $network-$channel formatting.
• Robust Reconnection Logic: Automatically handles network drops, socket timeouts, and ZNC authentication.

---

Configuration (config.json)

Create a config.json file in the root directory of the project alongside your Python script.

Example config.json

{
    "bot": {
        "trigger": "!zncbot"
    },
    "znc": {
        "server": "znc.myserver.com",
        "port": 8443,
        "user": "your_znc_user",
        "pass": "your_znc_password",
        "use_ssl": true,
        "networks": {
            "Libera": {
                "dm_alerts": true,
                "dm_ntfy_topic": "Libera-DMs",
                "channels": {
                    "#somechannel": {
                        "alerts": true,
                        "all_messages": false,
                        "triggers": ["your_nick", "warning"],
                        "ntfy_topic": "somechannel-alerts"
                    },
                    "#anotherchannel": {
                        "alerts": true,
                        "all_messages": true
                    },
                    "#athirdchannel": {
                        "alerts": false
                    }
                }
            }
        }
    },
    "ntfy": {
        "base_url": "https://ntfy.sh",
        "auth": true,
        "token": "",
        "user": "your_ntfy_user",
        "pass": "your_ntfy_password"
    }
}

Root: bot

Attribute	Type	Status	Default	Description
trigger	String	Required	None	Command prefix the bot listens for in channels (e.g., !gumbybot).

Root: znc

Attribute	Type	Status	Default	Description
server	String	Required	None	Hostname or IP address of your ZNC server.
port	Integer	Required	None	Port number for the ZNC bouncer (typically 8443 or 6697).
user	String	Required	None	Your primary ZNC username.
pass	String	Required	None	Your primary ZNC password.
use_ssl	Boolean	Optional	true	Whether to connect to ZNC using SSL/TLS encryption.
networks	Object	Required	None	Dictionary container holding your ZNC network configurations.

Network Level (inside znc.networks.<network_name>)

Attribute	Type	Status	Default	Description
dm_alerts	Boolean	Optional	true	Enables or disables forwarding private DMs to ntfy.
dm_ntfy_topic	String	Optional	$network-DMs	Custom ntfy topic for incoming direct messages.
channels	Object	Required	None	Dictionary of channels to join and monitor on this network.

Channel Level (inside znc.networks.<network_name>.channels.<channel_name>)

Attribute	Type	Status	Default	Description
alerts	Boolean	Optional	false	Master switch to allow or suppress push notifications for this channel.
all_messages	Boolean	Optional	true	If true, fires alerts for every message. If false, filters messages based on triggers.
triggers	Array	Optional	[]	List of words/phrases to match against messages when all_messages is false.
ntfy_topic	String	Optional	$network-$channel	Custom ntfy topic destination for this specific channel.

Root: ntfy

Attribute	Type	Status	Default	Description
base_url	String	Required	None	Base URL of your ntfy server (trailing slashes are automatically stripped).
auth	Boolean	Optional	false	Set to true if your ntfy server requires authentication.
token	String	Optional	""	Bearer token for ntfy authentication (recommended if using tokens).
user	String	Optional	""	Username for ntfy Basic Authentication.
pass	String	Optional	""	Password for ntfy Basic Authentication.

If ntfy.auth is true, it will attempt to use token first. If you want to use user/pass, be sure that token is an empty string.

Installation & Running

1. Clone or copy the project files onto your server.

2. Ensure you have Python 3 installed along with the required requests library:

pip install requests

3. Populate your config.json with your server parameters and channel preferences.

4. Run the script:

python3 znc_listener.py

5. (Optional) Set it up as a systemd service to run continuously in the background.