gidlinet/zabbix-whatsapp-notify repository overview

⁠Zabbix WhatsApp Notify

A JavaScript webhook bridge that receives alerts from your Zabbix server media and queues them for delivery to a configured WhatsApp contact.

⁠What's New in V2

⁠Zabbix Screenshot

You can now snap a screenshot of your Zabbix dashboard directly from a WhatsApp chat.

• Resolution: 1920x1080
• Note: Only the visible area within the 1920x1080 canvas will be captured — this is not a scrollable screenshot. Make sure all critical information is placed within this canvas.
• You can screenshot a specific dashboard by supplying its ID: !screenshot <dashboard_id>

⁠Commands

The following commands are now available in V2:

⁠Prerequisites

The following are required before running this service:

⁠Deployment

⁠Option 1 — Docker Run

docker run --name whatsapp-notify \
  -u 0:0 \
  --restart unless-stopped \
  -p 3002:3000 \
  -e ZABBIX_USERNAME=zabbix \
  -e ZABBIX_PASSWORD=Admin \
  -e ZABBIX_IP=0.0.0.0 \
  -e ENABLE_SCREENSHOT=true \
  -v /session/:/app/data/session \
  --security-opt seccomp:unconfined \
  gidlinet/zabbix-whatsapp-notify:v2

⁠Option 2 — Docker Compose

services:
  whatsapp-bot:
    image: gidlinet/zabbix-whatsapp-notify:v2
    container_name: whatsapp-notify
    user: "0:0"
    restart: unless-stopped
    ports:
      - "3002:3000"
    environment:
      # Your Zabbix username
      - ZABBIX_USERNAME=zabbix
      # Your Zabbix password
      - ZABBIX_PASSWORD=Admin
      # Your Zabbix IP address
      - ZABBIX_IP=0.0.0.0
      # Enable screenshot command — value can be true or false
      - ENABLE_SCREENSHOT=true
    volumes:
      - /session/:/app/data/session
    security_opt:
      - seccomp:unconfined

To start the service, run the following command from the directory containing your docker-compose.yml:

sudo docker compose down && sudo docker compose pull && sudo docker compose up -d

This command performs three sequential operations:

⁠Environment Variables

⁠Account Setup

Once the container is running, navigate to the login page in your browser to scan the QR code:

http://<your-ip>:<port>/login

Examples:

http://localhost:3002/login
http://192.168.0.1:3002/login

Scan the QR code using the WhatsApp mobile app under Linked Devices to complete authentication.

⁠Commands

Commands are only available when sent from your own linked account (i.e., messaging yourself).

Note: Additional commands are planned for future releases.

⁠How It Works

Zabbix Server  ->  Webhook (Media)  ->  zabbix-whatsapp-notify  ->  WhatsApp Contact

1. Zabbix triggers an alert and dispatches a webhook to this service.
2. The service queues the incoming message.
3. The message is forwarded to the configured WhatsApp recipient specified in the To field.

⁠Zabbix Media Type Configuration

The following steps describe how to configure a Webhook media type in Zabbix to forward alerts to this service.

⁠Step 1 — Create the Media Type

Navigate to Alerts > Media types in the Zabbix web interface and create a new media type with the following settings:

⁠Step 2 — Configure Parameters

Add the following parameters under the Media type tab:

Replace <your-ip> and <port> with the host address and port where the container is running (e.g., http://172.20.35.248:3002/queuealert).

⁠Step 3 — Add the Webhook Script

Paste the following script into the Script field:

var req = new HttpRequest();
try {
  var params = JSON.parse(value);
  var url = params.URL;
  var message = params.Message;
  var to = params.To;
  var subject = params.Subject || "";
  var problem_host = params.problem_host || "";
  var problem_name = params.problem_name || "";
  var problem_severity = params.problem_severity || "";
  var problem_date = params.problem_date || "";

  var payload = JSON.stringify({
    to: to,
    message: message,
    subject: subject,
    problem_host: problem_host,
    problem_name: problem_name,
    problem_severity: problem_severity,
    problem_date: problem_date,
  });

  req.addHeader("Content-Type: application/json");
  var response = req.post(url, payload);
  var statusCode = req.getStatus();
  return "OK";
} catch (error) {
  Zabbix.Log(3, "[WhatsApp Webhook] Error: " + error);
}

⁠Step 4 — Configure Message Templates

Switch to the Message templates tab and ensure the following message types are configured:

⁠Step 5 — Assign the Media Type to a User

Navigate to Users > Users, select the user that should receive alerts, and under the Media tab add the Whatsapp media type. Set the Send to field to the WhatsApp contact number or group ID obtained via the !groups command.

⁠Docker Image

⁠Dependencies

The following Node.js packages are used by this project:

⁠Known Issues

Root User Requirement The container currently requires running as root (-u 0:0) due to a bug that prevents the process from writing to the session directory under a non-root user. This is a known issue and will be addressed in a future release. Until resolved, omitting or changing the user flag will result in permission errors when the service attempts to persist session data to ./session/.

⁠Issues and Contributions

To report a bug, request a feature, or contribute to the project, visit the GitHub repository:

https://github.com/GidliNet/Zabbix-Whatsapp-Notify⁠

⁠Disclaimer

This project is an independent, open-source integration and is not affiliated with, endorsed by, or associated with WhatsApp LLC or Meta Platforms, Inc. in any way. WhatsApp is a trademark of WhatsApp LLC. Use of this software is at your own discretion and risk. Ensure that your usage complies with WhatsApp's Terms of Service⁠.

Maintained by GidliNet⁠