Zabbix alerts by SMS and voice call, through your own hardware

Zabbix ships notification channels for email, and for roughly every chat and ticketing product with an API. What it does not ship is a way to reach a human when the network is the thing that is broken. Every one of those channels is a webhook, and a webhook needs an uplink. If the outage is upstream, Zabbix will detect the problem perfectly, raise it perfectly, and fail to tell anybody.

A hardware SMS gateway fixes that by leaving the building over a SIM instead. This is how to wire one into Zabbix as a media type, including the two shipped defaults that are almost certainly wrong for your device.

What you need first

• Zabbix 7.0 or newer.
• An SMSEagle with REST API v2 reachable from the Zabbix server or proxy. This is an agentless webhook - no external script, nothing to install on the Zabbix host.
• An API token scoped to send, which is a different token from any you use for monitoring the device.

Step 1: an API token that can only send

In the SMSEagle UI open Users, pick or create a dedicated user, and click Access to API. Select APIv2 and generate a token. Then, under Manage allowed API methods, enable only what the channel you are using actually needs:

Scopes from the initMAX media type README.

Step 2: find your voice ID, because the default is wrong

This is the single most likely thing to waste your evening, so do it before you touch Zabbix. The voice_id parameter selects which text-to-speech voice makes the call, and the IDs are specific to your device - they depend on which voice models are installed on it. There is no universal mapping.

In the SMSEagle UI go to Calls → TTS Voice models and read the number in the ID column for the voice you want. Online voices live under Calls → TTS Online voice models and are numbered separately.

Step 3: import and configure the media types

Download mediatype-SMSEagle-by-initMAX.yaml and import it under Alerts → Media types. You get two: SMSEagle SMS and SMSEagle Voice.

On each, set the parameters that have no sensible default:

Parameter names, defaults and the URL rule from the published media type and its README. encoding, modem_no, oid, date, send_after, send_before, duration and test are advanced and are best left alone.

Two of these are worth dwelling on. The url rule catches people who paste the API endpoint they were just using in a browser - append the path yourself and every send fails with an unhelpful error. And tts_adv,sms is the setting most people actually want for voice: a phone call wakes someone up, and the accompanying SMS leaves the event details and acknowledgement instructions on their screen for when they are conscious enough to read them.

Step 4: assign media to users

Under Users → Users → Media, add the media type and set the recipient. The Send to field accepts more than a phone number, which is not obvious and is the tidier way to run it:

Comma-separate for multiple recipients. Pointing Zabbix at a Phonebook group rather than a list of numbers means the on-call rota is maintained in one place on the gateway, and rotating who gets woken does not require a Zabbix change and a Zabbix admin.

Then reference the media type in your Trigger actions as usual. It behaves like any other Zabbix media type from there.

Testing, and the error you will hit

Use the Test button on the media type rather than waiting for a real problem. The first attempt commonly fails with:

Sending failed: required parameters not set: Recipient

This is not a configuration fault. The test dialog has its own recipient field, and it is separate from the user media you configured in step 4 - the test does not know which user you meant. Fill in a number in the dialog and send again.

Where this sits in a real escalation

It is worth being honest about scope. This is not a replacement for email or chat notifications - it is the path that works when those do not, and it costs real money per message. The sensible shape is a tiered action: chat and email for everything, SMS for high severity, a voice call for the small set of problems that genuinely justify waking someone, with the call carrying tts_adv,sms so the details survive the call.

The other half of the loop is the reply direction - acknowledging the problem from the same phone that just rang, without opening a laptop. That needs a little more setup on the gateway and is covered separately.

Watch the walkthrough

Fifteen minutes, including the part where the voice call actually comes through - which is more convincing than any amount of prose about text-to-speech.

Related