SMSTunnel for Zabbix

1. 1. Install the SMSTunnel app from Google Play on your Android phone and sign in.
2. 2. In your dashboard, open Apps → Add an app, pick Zabbix, name it (for example "Zabbix") and click Create the key.
3. 3. Copy the key right away: it's shown only once. You can stop or delete the app there anytime, and Zabbix can't send texts anymore.

Get the steps with your key in them

It opens Add an app with Zabbix picked. Once the key is made, the dashboard shows every step and command with the key already filled in, ready to copy.

Leave Can also read received texts off: Zabbix doesn't need it. The Zabbix server (not a Zabbix proxy) sends the alerts, so it needs to reach https://smstunnel.io on port 443, directly or through an HTTP proxy (see http_proxy below).

1. 1. Download media_smstunnel.yaml, or media_smstunnel_6.0.yaml for Zabbix 6.0.
2. 2. In Zabbix, go to Alerts → Media types (6.0: Administration → Media types) and click Import (top right).
3. 3. Choose the file and click Import. A media type named SMSTunnel appears in the list.

1. 1. Go to Administration → Macros (6.0: Administration → General → Macros).
2. 2. Add the macro {$SMSTUNNEL.API.KEY}, paste the key as its value, and set the type next to the value to Secret text.
3. 3. Click Update.

A secret macro is hidden in the frontend once saved and is not part of any export. If you keep secrets in HashiCorp Vault (or CyberArk, on Zabbix 6.2 and later), choose Vault secret instead and enter the secret's path.

1. 1. Back in Alerts → Media types (6.0: Administration → Media types), click Test in the SMSTunnel row.
2. 2. Replace {ALERT.SENDTO} in send_to with your own number, for example +14155550123.
3. 3. api_key reads {$SMSTUNNEL.API.KEY}: the Test window doesn't fill in macros, so paste the key there. What you type is used for this test only and is not saved.
4. 4. Click Test. You get Media type test successful and your phone sends: Test from Zabbix: SMSTunnel is set up, and your own phone sent this text.

If you click Test with the macro still in api_key, the answer reminds you of this. Real alerts do fill in the macro. You can also type a subject and message of your own instead of {ALERT.SUBJECT} and {ALERT.MESSAGE}.

1. 1. Go to Users → Users (6.0: Administration → Users) and open a user.
2. 2. On the Media tab click Add, choose Type: SMSTunnel and put the user's own number in Send to, in international format (+14155550123).
3. 3. Keep When active and Use if severity as you want them, click Add, then Update.

One number per media: for a second number, add a second SMSTunnel media. The user also needs at least read permission to the hosts whose problems they should hear about (through their user group).

1. 1. Go to Alerts → Actions → Trigger actions (6.0: Configuration → Actions → Trigger actions) and create an action (or edit one, such as Report problems to Zabbix administrators).
2. 2. On Operations, add an operation: Send to users or Send to user groups, Send only to: SMSTunnel.
3. 3. Add Recovery operations and Update operations (Notify all involved) if you want those texts too.
4. 4. Leave Custom message off to use the templates below. Click Add or Update, and check that the action is enabled.

When a problem starts, every user in the operation gets a text on their own number. See what was sent in Reports → Action log, or in the Actions column of Monitoring → Problems.

• The text is the subject, a line break, then the message. Lines such as Data: whose macro resolved to nothing are left out, and so are extra blank lines.
• Edit the templates on the media type's Message templates tab, or tick Custom message in an action operation.
• To put a link to the problem in the text, add a line like {$ZABBIX.URL}/tr_events.php?triggerid={TRIGGER.ID}&eventid={EVENT.ID} and define {$ZABBIX.URL} (a long link takes a good part of one SMS).
• Zabbix itself decides two things worth knowing: Notify all involved does not text the user who made the update, and {USER.FULLNAME} reads "Inaccessible user" to recipients who aren't allowed to see other users.

Look in Reports → Action log (column Info), or in Monitoring → Problems: click the problem's icon in the Actions column and point at the red i next to Failed. Every message starts with SMSTunnel:.

• no API key. Add the global macro {$SMSTUNNEL.API.KEY} …: add the macro in Administration → Macros (6.0: Administration → General → Macros); the name must match exactly. In the Test window, paste the key into api_key.
• the API key was not accepted (HTTP 401: Invalid or expired API key) …: the key is wrong or was deleted. Create a new one under Apps in your dashboard and update the macro. Alerts made before the fix keep the old key for their retries; new alerts use the new key.
• the text was refused (HTTP 403: … [PERMISSION_REQUIRED]): the key can't send texts. Create a key under Apps → Add an app. Other 403 messages explain a plan or account limit.
• "Send to" is not a phone number (…) or the text was not accepted (HTTP 400: Phone number must …): fix the user's Send to: one number in international format, e.g. +14155550123.
• "Send to" holds more than one number (…): use one SMSTunnel media per number on the user's Media tab.
• too many texts in a short time (HTTP 429 …): SMSTunnel allows about 30 texts a minute. Without "wait … s" in the message, the plan's limit for the day or month is reached, and retries won't help until it resets. Zabbix retries on its own; if it happens often, cut alert noise (trigger dependencies, longer escalation steps).
• the service could not take the text right now (HTTP 5xx …) or could not reach https://smstunnel.io (cannot get URL: …): retried on its own. If it keeps failing, check that the Zabbix server can reach smstunnel.io:443 (DNS, firewall, http_proxy).
• the certificate of https://smstunnel.io was not accepted (cannot get URL: SSL certificate problem: …): the Zabbix server has no CA bundle, or a TLS-inspecting proxy re-signs traffic. Install the ca-certificates package or add your proxy's CA to the system store. As a last resort, set the global macro {$HTTP.TLS.VERIFY:"SMSTunnel"} to peer or none. Retrying won't fix this one: each attempt fails until the certificate is accepted.
• the text is empty …: the action's custom message has no subject and no message.
• The alert says Sent but no text arrived: open the SMSTunnel app on the phone and check it is signed in and online. A text for an offline phone waits and goes out when the phone is back; the dashboard shows each text's status.
• Nothing in the action log: check that the action is enabled and its conditions match, that the user's SMSTunnel media is enabled for that severity and time, that the user can read the host, and that the media type is enabled.

For more detail, raise the alerter log level on the Zabbix server for a few minutes (zabbix_server -R log_level_increase=alerter) and look for lines starting with [ SMSTunnel ]. They never contain the key, and phone numbers are shortened. At that debug level Zabbix itself also writes each webhook's parameters to the log, the key included (In zbx_es_execute() param:), so lower it again afterwards (zabbix_server -R log_level_decrease=alerter) and don't share that log.

Import the new file the same way (media_smstunnel.yaml, or media_smstunnel_6.0.yaml on Zabbix 6.0), with Update existing ticked for media types. Your macros (key, phone ID, country code) stay as they are. The parameters and message templates are replaced with the new version's, so note any template you changed before you import.

When you upgrade Zabbix itself from 6.0 to 7.0 or later, the SMSTunnel media type comes along and keeps working. Import media_smstunnel.yaml afterwards (with Update existing) so that its messages name the new version's menus.

To remove it: delete the SMSTunnel media type, the {$SMSTUNNEL.*} macros, and the key under Apps in your dashboard.

• No modem on the Zabbix server. Zabbix's built-in SMS needs a GSM modem on a serial port of the server. SMSTunnel needs only HTTPS, so it works the same in a VM, in Docker or in the cloud.
• A number people know. Alerts come from your own number, so they stand out and people can reply or call back.
• Your own SIM and plan. Texts go out on the plan you already pay for.
• You stay in control. Delete the key under Apps and Zabbix can't send anymore. The key lives in a secret macro, hidden in Zabbix and left out of exports.

Which Zabbix versions?

Zabbix 6.0 LTS, 7.0 LTS and later (7.2, 7.4 and 8.0 LTS). Import media_smstunnel.yaml on 7.0 and later and media_smstunnel_6.0.yaml on 6.0; both hold the same media type. Tested end to end on 6.0.49, 7.0.32, 7.4.16 and 8.0.0. Certificates are checked on 6.0.47+, 7.0.28+, 7.4.12+ and 8.0.

Can several people get the alert?

Yes. Each user gets their own text on their own number; one SMSTunnel media per number.

What if my phone is offline?

The text waits in your account and goes out when the phone is back online. Zabbix shows the alert as sent.

What if SMSTunnel is busy or can't be reached?

Zabbix tries again: 5 attempts, 30 seconds apart. SMSTunnel allows about 30 texts a minute.

Where does Zabbix keep the key?

In a global macro of type Secret text (or a Vault secret): hidden in the frontend and left out of exports.

Does the Zabbix server need internet access?

It needs to reach https://smstunnel.io on port 443, directly or through an HTTP proxy. Zabbix proxies don't send alerts, so only the server needs it.

Can I send through a particular phone?

Yes: put the phone's ID (from Phones in your dashboard) in the macro {$SMSTUNNEL.DEVICE.ID}.

I upgraded Zabbix from 6.0 to 7.0. What now?

The media type comes along and keeps working. Import media_smstunnel.yaml with Update existing ticked so that its messages name 7.0's menus.