Zabbix a WhatsApp – Integrace notifikací

Tento návod popisuje postup integrace Zabbixu s WhatsApp pro posílání notifikací pomocí webhooku WhatsApp Cloud API. Postup je aktuální pro Zabbix ve verzi 7.0 a WhatsApp Cloud API verze 22, která již podporuje pojmenované parametry pro šablony zpráv. Zaměřujeme se zde na řešení využívající bezplatnou verzi WhatsApp Cloud API, která má určitá omezení. Rovněž si vysvětlíme výhody placené a ověřené varianty, která nabízí vyšší limity, lepší podporu a další pokročilé funkce.

Meta Developer účet

• Pokud již máte Facebook účet, přejděte na developers.facebook.com a přihlaste se svým osobním Facebook účtem.
• Pokud Facebook účet nemáte, založte si jej na facebook.com pomocí e-mailu nebo telefonu.
• Následně na developers.facebook.com klikněte na „Get Started“, ověřte e-mail a telefon, a akceptujte podmínky pro vytvoření Meta Developer účtu.

Vytvoření aplikace s WhatsApp produktem

Klikněte My Apps

Dále klikněte na Create App

Vyplňte název aplikace (např. Whats-Zabbix).

Vyplňte kontaktní e-mail aplikace (existující e-mailová adresa).

Z use-case vybereme možnost „Ostatní“.

Pro přístup k části WhatsApp je potřeba zvolit typ aplikace „Firemní“.

Znovu vyplníme název aplikace a e-mail, portfolio prozatím necháme prázdné.

Po vytvoření kostry aplikace k ní přidáme produkt WhatsApp, o který nám jde.

Pravděpodobně pro nás neexistuje žádné vhodné portfolio, proto jej vytvoříme. Pokud však již vhodné portfolio existuje, můžete ho vybrat a tuto část přeskočit.

V kroku pro vytvoření portfolia vyplňte název firmy a účtu, dále pak vaše jméno a firemní e-mail. (Omlouváme se, ale nepodařilo se nám zajistit screenshot v anglické verzi.)

V dalším kroku už jen počkáte na potvrzení. Pokud je váš účet příliš nový, je možné, že budete muset počkat až jednu hodinu, než bude možné portfolio vytvořit.

Když se nyní znovu podíváme do naší aplikace, v části WhatsApp > API Setup se nám nově zobrazí naše portfolio, které potvrdíme.

Hned poté se nám objeví naše WhatsApp aplikace a její údaje.

Přidání čísel pro notifikace

Protože se jedná o free verzi aplikace, je nutné předem zadat čísla, na která budeme chtít zasílat notifikace (může jich být maximálně 5). Pokud bychom použili vlastní ověřené telefonní číslo, tento krok by nebyl nutný, ale aplikace by již nebyla zdarma.

Telefonní číslo vygenerované společností Meta slouží primárně pro testování, ale bez problémů jej můžeme použít i pro naše zamýšlené notifikace. Jediným omezením je nutnost každých 90 dní prodloužit používání tohoto čísla. Toto omezení se netýká vlastních ověřených telefonních čísel.

Zde si rovnou poznamenáme naše „Phone Number ID“, které budeme později potřebovat pro vytvoření „Media Template“ v Zabbixu.

Následně zadáte vaše telefonní číslo pro WhatsApp. Do aplikace WhatsApp na tomto čísle vám přijde zpráva s číselným ověřovacím kódem.

Po chvíli by vám do aplikace WhatsApp mělo přijít ověřovací číslo, které vyplníte do formuláře. Stejným způsobem postupujte i pro další případná telefonní čísla. Pozor, tato čísla je nutné zadat ještě před jejich použitím pro zasílání notifikací ze Zabbixu.

Odeslání první testovací zprávy

Pro odeslání naší první testovací zprávy už máme připraveno vše důležité a můžeme využít přímo aplikační formulář pro testování. Pro tento první test nám však ještě chybí zásadní věc – přístupový token.

Tento token si můžeme vygenerovat přímo zde, ale pozor: token má platnost pouze 1 hodinu. Proto jej nepoužívejte jako trvalý token pro Zabbix!

Nejprve klikneme na tlačítko „Generate access token“.

V nově otevřeném pop-up okně potvrdíme přihlášení pod naším uživatelským účtem.

Na další stránce potvrdíme udělení přístupu pro naši aplikaci.

Odsouhlasíme souhrn oprávnění.

Počkáme na dokončení operace a poté okno zavřeme.

Po spárování uživatelského účtu se nám konečně vygeneruje token.

• První řádek obsahuje náš token (znovu připomínáme, že jeho platnost je pouze 1 hodina!).
• Naše odchozí (testovací) telefonní číslo
• Telefonní číslo, na které budeme odesílat testovací notifikaci
• Tlačítko pro odeslání naší testovací notifikace

Po kontrole všech polí můžete kliknout na tlačítko „Send message“. Během několika okamžiků by vám měla přijít testovací zpráva.

Úprava meta šablony „hello_world“

Na stejné stránce, kde jste přidávali telefonní čísla, najdete níže v bodě č. 5 modře uvedený odkaz „see the Overview page“. Tento odkaz si otevřete v novém okně – jedná se o nejjednodušší způsob, jak se rychle dostat k nastavení šablon zpráv.

Šablony nastavujeme z jednoduchého důvodu – WhatsApp Cloud API neumožňuje zasílat libovolné zprávy na neověřená telefonní čísla. Pomocí šablon proto využíváme workaround, kdy předem určíme, jak bude zpráva vypadat.

Pro neověřená (testovací) telefonní čísla máme k dispozici pouze jednu předdefinovanou šablonu, konkrétně „hello_world“. Pokud bychom použili vlastní ověřené telefonní číslo, můžeme si vytvořit šablony vlastní – například různé varianty dle závažnosti s barevnou hlavičkou či speciální šablonu pro zprávy informující o vyřešení problému.

Zde klikneme na „Manage templates“.

Klikneme na naši šablonu „hello_world“.

Klikneme na tlačítko „Edit template“.

V první sekci zkontrolujeme ale neměníme jazyk šablony („Select language“).

Dále budeme vyplňovat sekce „Header“, „Body“ a „Footer“.

Pozor: Zde buďte velmi opatrní – šablonu lze upravit pouze jednou za 24 hodin! Použijte náš přiložený příklad („example“) a případně upravte jen doménu svého Zabbixu.

Přepněte typ proměnné („Variable“) na „Name“.

Obsah pro sekci „Header“:

{{event_status}}

Obsah pro sekci „Body“:

*Problem name:* {{event_name}}
*Problem started* at {{event_time}} on {{event_date}}
*Host:* {{host_name}}
*Severity:* {{event_severity}}
*Operational data:* {{item_lastvalue}}
*Original problem ID:* {{event_id}}

Do příkladu pro obsah vložte naše vzorová data:

• {{event_name}} Windows: Operating system description has changed
• {{event_time}} 10:57:12
• {{event_date}} 28.4.2025
• {{host_name}} DC1
• {{event_severity}} Information
• {{item_lastvalue}} version123
• {{event_id}} 123

Obsah pro sekci „Footer“:

WhatsAPP notification developed by initMAX s.r.o.

Naši šablonu rovnou rozšíříme o odkaz na zobrazení problému podle jeho jména a další odkaz na zobrazení posledních naměřených hodnot.

Do prvního odkazu vložíme název „Visit problem page“. Do URL vložíme náš odkaz bez posledního parametru – ten tam automaticky doplní META.

Pozor: URL adresu si upravte podle své vlastní!

https://www.initmax.cz/zabbix/zabbix.php?action=problem.view&filter_set=1&name=

• Priklad URL pro overeni: https://www.initmax.cz/zabbix/zabbix.php?action=problem.view&filter_set=1&name=problem

Do druhého odkazu vložíme název „Check latest data“. Do URL vložíme náš odkaz bez posledního parametru – ten tam automaticky doplní META.

Pozor: URL adresu si upravte podle své vlastní!

https://www.initmax.cz/zabbix/history.php?action=showgraph&itemids%5B%5D=

• Priklad URL pro overeni: https://www.initmax.cz/zabbix/history.php?action=showgraph&itemids%5B%5D=12344

V pravém rohu obrazovky můžete vidět náhled předgenerované zprávy. Vše si pečlivě zkontrolujte!

Posledním krokem je uložení šablon. Po jejich uložení je po dobu následujících 24 hodin nebudete moci upravovat! Proto je velmi důležité vše zkontrolovat a udělat správně hned napoprvé.

Generování dlouhodobého systémového tokenu

Na straně Meta providera máme nyní vše připravené a ověřené. Nyní je čas přesunout se do Zabbixu. Protože ale pro naše notifikace potřebujeme token, který ideálně neexpiruje, pustíme se ještě do jeho vygenerování.

Toto nastavení provedeme na stránce https://business.facebook.com/, kde se přesuneme do sekce:

Settings → Users → System Users

Zde klikneme na tlačítko „+ Add“.

Zde vytvoříme uživatele. V našem případě můžete zvolit název například „Zabbix-WhatsApp“. Pro jeho systémovou roli stačí zvolit úroveň „Employee“ – nedávejte mu administrátorská oprávnění!

Po vytvoření uživatele mu musíme přidělit příslušná oprávnění k aplikaci.

Oprávnění nastavíme pomocí tlačítka se třemi tečkami („…“).

V části „Apps“ vybereme naši aplikaci a nastavíme maximální dostupná oprávnění (při testování s nižší úrovní oprávnění se nám nepodařilo aplikaci úspěšně provozovat).

Totéž platí i pro sekci „WhatsApp accounts“.

V dalším okně počkáme na potvrzení a následně jej zavřeme tlačítkem „Done“.

Po nastavení uživatelských oprávnění k aplikacím můžeme nakonec kliknout na „Generate token“.

V prvním kroku vybereme naši WhatsApp aplikaci.

V dalším kroku nastavíme platnost tokenu („Token expiration“). Pro bezpečný a bezproblémový provoz zvolíme možnost „Never“ (token tedy nikdy neexpiruje).

V sekci opravneni tokenu pro apliaci zvolime jen tyto 2 opravneni

• whatsapp_business_messaging
• whatsapp_business_management

V posledním kroku se nám zobrazí náš vygenerovaný token. Tento token si pečlivě uložte, protože později jej nebude možné znovu zobrazit – pouze vygenerovat nový.

Tento token budeme potřebovat jako druhou a zároveň poslední položku pro nastavení media typu v Zabbixu.

Import YAML média typu do Zabbixu

Připravili jsme pro vás šablonu pro WhatsApp. Tuto šablonu naleznete zde:
https://git.initmax.cz/initMAX-Public/zabbix-templates

Následně staženou šablonu importujte do Zabbixu:

Alerts → Media types → Import

Vyberte staženou šablonu a klikněte na „Import“.

Po úspěšném importu se vám zobrazí hláška „Imported successfully“. Následně klikněte na naši šablonu, kde dokončíme její nastavení.

Zde je potřeba vyplnit dva parametry:

• access_token: Zde vložte váš permanentní token, který jste získali v předchozím kroku v kapitole „Generování dlouhodobého systémového tokenu“.
• phone_number_id: Zde vložte číselné ID uvedené v kapitole „Přidání čísel pro notifikace“ – toto ID najdete hned pod vaším testovacím číslem.

Následně nastavení uložíme. Poté můžeme naši notifikaci rovnou otestovat přímo v Zabbixu pomocí tlačítka „Test“.

Testování notifikace v Zabbixu

Využijeme testovací tlačítko, které je přímo dostupné u našeho média.

Ve formuláři vyplníme naše telefonní číslo. Toto číslo se musí shodovat s číslem, které jsme přidali v sekci „Přidání čísel pro notifikace“. Následně klikneme na tlačítko „Test“.

Výstup by měl vrátit zprávu „Media type test successful.“ a ve spodní části „Response: OK“.

Příklad přijaté testovací notifikace se vzorovými daty. Na screenshotu vidíme nevyplněná vestavěná makra Zabbixu (např. {EVENT.NAME}, {HOST.NAME}), což je v pořádku, protože se jedná o testovací zprávu. Při reálném použití budou tato pole správně vyplněna.

Použití u uživatelů

Nezapomeňte jako poslední krok přidat nový media typ vašim uživatelům. V rámci free režimu je doporučeno přidávat média ručně. Je sice možné použít i JIT (Just-in-time provisioning), ale protože je v tomto režimu limit maximálně 5 telefonních čísel a zároveň musíte čísla ručně registrovat a ověřovat, doporučujeme tuto konfiguraci provádět manuálně.

Příklad nastavení vidíte zde. Nezapomeňte telefonní čísla vždy zadávat v úplném formátu včetně mezinárodní předvolby (např. +420…).

Rozdíly mezi Free Sandboxem a Produkční verzí WhatsApp Cloud API

⚠️ Co se stane po 90 dnech s testovacím číslem?

U testovacího čísla, které získáte od společnosti Meta, platí omezení, že každých 90 dní je nutné jeho platnost prodloužit.

• Pokud číslo včas neprodloužíte:
  • Nebudete moci posílat ani přijímat zprávy.
  • Bude nutné číslo opětovně aktivovat (prodloužit) přímo v nastavení Meta Developer účtu.
• Doporučení:
  • Pravidelně kontrolujte stav čísla.
  • Ideálně přejděte na vlastní produkční číslo, abyste se vyhnuli nutnosti pravidelných obnov.