Solved: Integration: Sending Zabbix Alerts to WhatsApp Business API

#devops #programming #tutorial #cloud

🚀 Executive Summary

TL;DR: Traditional Zabbix alerts via email or SMS often lead to ‘alert fatigue’ and delayed responses for critical infrastructure issues. This guide provides a step-by-step solution to integrate Zabbix with the WhatsApp Business API, enabling direct, high-visibility alert delivery to teams for faster incident resolution and improved system reliability.

🎯 Key Takeaways

The WhatsApp Business API mandates the use of pre-approved message templates for all business-initiated conversations, requiring template creation and approval in WhatsApp Manager before use.
A Python script acts as the intermediary, parsing Zabbix alert macros (recipient, subject, message) and forwarding them to the WhatsApp API using a permanent access token and the specified message template.
Zabbix media type configuration involves defining the Python script as the ‘Type’, specifying whatsapp-sender.py as the ‘Script name’, and passing Zabbix macros like {ALERT.SENDTO}, {ALERT.SUBJECT}, and {ALERT.MESSAGE} as script parameters.

Integration: Sending Zabbix Alerts to WhatsApp Business API

Introduction

In the world of infrastructure monitoring, the speed and reliability of alert delivery are paramount. While traditional channels like email and SMS are standard, they often suffer from “alert fatigue,” where critical notifications get lost in a sea of noise. For high-priority issues that demand immediate attention, we need a more direct and engaging channel.

This is where the WhatsApp Business API comes in. By integrating Zabbix with WhatsApp, you can send critical alerts directly to a platform your team uses daily, ensuring high visibility and drastically reducing response times. This tutorial will guide you through the entire process, from setting up the API to configuring a custom alert script in Zabbix. Let’s transform your monitoring workflow from reactive to proactive.

Prerequisites

Before we begin, ensure you have the following in place:

An active Zabbix instance (version 5.0 or newer is recommended).
Administrator-level access to your Zabbix web interface.
A server environment with network access to both your Zabbix server and the internet. This can be the Zabbix server itself.
Python 3 and the pip package manager installed on that server.
A Meta for Developers account with a configured App and access to the WhatsApp Business Platform.
From your Meta App dashboard, you will need three key pieces of information:
- Phone Number ID: The ID of the phone number you are sending messages from.
- WhatsApp Business Account ID: The ID of your business account.
- Permanent Access Token: A permanent token to authenticate API requests. Using a temporary token will cause the integration to fail after it expires.

Step-by-Step Guide

We’ll break down the integration into four clear steps: creating a WhatsApp message template, building the Python notification script, configuring Zabbix, and finally, setting up the user and action.

Step 1: Create a WhatsApp Message Template

The WhatsApp Business API requires that business-initiated conversations use pre-approved message templates to prevent spam. You must create a template for your Zabbix alerts within the WhatsApp Manager.

Navigate to your WhatsApp Manager > Account tools > Message templates and create a new template.

Choose the “Utility” category.
Give it a memorable name, like zabbix_alert_v1.
Select the languages you need.
For the message body, create a structure with placeholders. WhatsApp uses numbered placeholders like {{1}}, {{2}}, etc.

Here is a sample template body that works well for Zabbix alerts:

*Zabbix Alert: {{1}}*

Severity: *{{2}}*
Host: *{{3}}*
Problem Start Time: *{{4}}*

*Details:*
{{5}}

Please investigate immediately.

Submit this template for approval. It usually takes a few minutes to a few hours. Once approved, you are ready to use it in your script.

Step 2: Develop the Python Notification Script

Next, we will create a Python script that will be executed by Zabbix. This script will receive the alert details and forward them to the WhatsApp API using your approved template.

First, install the necessary Python library:

pip3 install requests

Now, create a file named whatsapp-sender.py in the directory Zabbix uses for alert scripts. You can find this path in your zabbix_server.conf file under the AlertScriptsPath directive. A common location is /usr/lib/zabbix/alertscripts.

Populate the file with the following code. Remember to replace the placeholder values for PHONE\_NUMBER\_ID, ACCESS\_TOKEN, and TEMPLATE\_NAME with your actual credentials.

#!/usr/bin/env python3
# whatsapp-sender.py

import sys
import json
import requests

# --- Configuration ---
# IMPORTANT: Store these securely, e.g., as environment variables or using a secrets manager.
# Avoid hardcoding them directly in the script for production environments.
PHONE_NUMBER_ID = 'YOUR_PHONE_NUMBER_ID'
ACCESS_TOKEN = 'YOUR_PERMANENT_ACCESS_TOKEN'
TEMPLATE_NAME = 'zabbix_alert_v1' # The name of your approved template
API_VERSION = 'v18.0'

# --- Script Logic ---
def send_whatsapp_message(recipient_number, subject, message):
    """
    Sends a formatted Zabbix alert to the WhatsApp Business API using a template.
    """
    api_url = f"https://graph.facebook.com/{API_VERSION}/{PHONE_NUMBER_ID}/messages"

    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json",
    }

    # The message from Zabbix often contains multiple lines. We need to parse it.
    # Example Zabbix message format:
    # Problem severity: High
    # Host: Web Server 01
    # Problem start time: 14:30:00
    # Original problem: High CPU utilization

    # Simple parsing logic. You can make this more robust.
    lines = message.splitlines()
    severity = lines[0].split(': ')[1] if len(lines) > 0 else 'N/A'
    host = lines[1].split(': ')[1] if len(lines) > 1 else 'N/A'
    start_time = lines[2].split(': ')[1] if len(lines) > 2 else 'N/A'
    details = '\n'.join(lines[4:]) if len(lines) > 4 else 'No details provided.'

    payload = {
        "messaging_product": "whatsapp",
        "to": recipient_number,
        "type": "template",
        "template": {
            "name": TEMPLATE_NAME,
            "language": {
                "code": "en_US"
            },
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {"type": "text", "text": subject},
                        {"type": "text", "text": severity},
                        {"type": "text", "text": host},
                        {"type": "text", "text": start_time},
                        {"type": "text", "text": details}
                    ]
                }
            ]
        }
    }

    try:
        response = requests.post(api_url, headers=headers, data=json.dumps(payload))
        response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
        print(f"Successfully sent message to {recipient_number}. Response: {response.json()}")
    except requests.exceptions.RequestException as e:
        print(f"Error sending message: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    if len(sys.argv) != 4:
        print("Usage: python3 whatsapp-sender.py [recipient_number] [subject] [message]", file=sys.stderr)
        sys.exit(1)

    recipient = sys.argv[1]
    alert_subject = sys.argv[2]
    alert_message = sys.argv[3]

    send_whatsapp_message(recipient, alert_subject, alert_message)

After saving the script, make it executable by the Zabbix user:

# Bash commands
chown zabbix:zabbix /usr/lib/zabbix/alertscripts/whatsapp-sender.py
chmod +x /usr/lib/zabbix/alertscripts/whatsapp-sender.py

Step 3: Configure the Media Type in Zabbix

Now, let’s teach Zabbix how to use this script.

In the Zabbix UI, navigate to Administration > Media types.
Click the Create media type button.
Fill out the form:
- Name: WhatsApp Business API
- Type: Script
- Script name: whatsapp-sender.py
- Script parameters: Add three parameters in this order:
  1. {ALERT.SENDTO}
  2. {ALERT.SUBJECT}
  3. {ALERT.MESSAGE}
Under the “Message templates” tab, you can define the format of the message that will be passed to your script. Create a new message template for “Problem” notifications.
Set the message content to use Zabbix macros that match the parsing logic in our Python script:

Problem severity: {TRIGGER.SEVERITY}
Host: {HOST.NAME}
Problem start time: {EVENT.TIME} on {EVENT.DATE}
Original problem: {TRIGGER.NAME}

{TRIGGER.DESCRIPTION}

Click “Add” to save the new media type. You can use the “Test” feature on this page to send a test message and verify that the script, credentials, and API access are all working correctly.

Step 4: Assign the Media Type to a User and Create an Action

The final step is to link this new notification method to a user and an action.

Go to Administration > Users and select the user you want to receive WhatsApp alerts.
Go to the Media tab and click “Add”.
In the popup:
- Type: Select “WhatsApp Business API”.
- Send to: Enter the user’s phone number in international format, without any +, spaces, or hyphens (e.g., 15551234567 for a US number).
- When active: Configure the schedule for when alerts should be sent.
- Enable the media and click “Add”.
Update the user profile.
Finally, navigate to Configuration > Actions > Trigger actions. Create a new action or modify an existing one. In the Operations tab, add a new operation to “Send message” to the desired user or user group using the “WhatsApp Business API” media type.

With this action enabled, Zabbix will now automatically execute your Python script and send a formatted WhatsApp message whenever a trigger condition is met.

Common Pitfalls

Incorrect File Permissions: A common issue is that the zabbix user does not have permission to execute the Python script. Always double-check ownership (chown) and permissions (chmod +x) on your script file. Check the Zabbix server logs for “Permission denied” errors.
API Rate Limiting and Template Rejection: Meta imposes rate limits on the number of messages you can send. A “flapping” trigger in Zabbix could cause a high volume of alerts and get you temporarily blocked. Configure your Zabbix actions with appropriate step durations and conditions. Furthermore, ensure your message template is approved and matches the structure expected by your script exactly.

Conclusion

You have successfully integrated Zabbix with the WhatsApp Business API, creating a powerful, high-visibility alerting channel for your critical infrastructure. This setup ensures that your team is notified promptly about issues that matter, enabling faster incident resolution and improving overall system reliability. You can further enhance this integration by creating different message templates for different alert severities or by adding more sophisticated parsing logic to your notification script.