Da dove nasce la scheda «Messaggi»
Un impianto che fa monitoraggio ha senso solo se ti avvisa. Volevo che ogni avviso potesse arrivare su tre strade: la notifica dell'app, WhatsApp e l'email, che nella catena di consegna sta per ultima. E volevo scegliere io, avviso per avviso, dove farlo arrivare, senza modificare file.
La scheda «Messaggi» del mio dashboard ha tre blocchi (WhatsApp, Email, Notifiche app), il menu per scegliere il canale di ogni avviso e i pulsanti di prova. Sotto c'è una catena di pacchetti YAML e di script. Ti racconto i pezzi nell'ordine in cui li ho costruiti.
WhatsApp: il gateway OpenWA
Per mandare e ricevere messaggi WhatsApp uso OpenWA, un gateway che gira in Docker e usa il motore whatsapp-web.js. Va detto subito: è un programma che si collega a WhatsApp Web, non un canale ufficiale. Il progetto stesso avverte che non è garantito di non essere bloccati, perché WhatsApp non consente bot o client non ufficiali. Per questo uso un numero dedicato, tengo un tetto ai messaggi e ho un sensore che segnala le restrizioni sull'account. Se ti serve un canale ufficiale, la strada è la WhatsApp Business Platform, che ha condizioni e costi suoi.
Lo script di installazione crea una rete Docker condivisa con Home Assistant, scrive il compose, avvia il contenitore, legge dai log la chiave API generata al primo avvio e la mette in secrets.yaml con un backup del file. La dashboard di OpenWA è raggiungibile solo dal mini PC, perché la porta è legata a 127.0.0.1.
name: openwa
services:
openwa:
image: ghcr.io/rmyndharis/openwa:latest
container_name: openwa
restart: unless-stopped
ports:
- "127.0.0.1:2785:2785" # dashboard e API solo dal mini PC
environment:
TZ: Europe/Rome
AUTO_START_SESSIONS: "true" # la sessione riparte da sola dopo un riavvio
SEND_PACING_ENABLED: "true" # limite giornaliero e riscaldamento anti-ban di OpenWA
SSRF_ALLOWED_HOSTS: "homeassistant" # i webhook possono raggiungere solo Home Assistant
volumes:
- openwa-data:/app/data # sessione WhatsApp, database, chiave API
shm_size: 512mb # Chromium
networks:
- srv-home
volumes:
openwa-data:
networks:
srv-home:
external: true
Alla prima esecuzione apri la dashboard di OpenWA dal mini PC, crei la sessione e scansioni il QR con il telefono del numero dedicato. Da quel momento la sessione riparte da sola.
Inviare: uno script con un tetto giornaliero
Da Home Assistant, ogni messaggio WhatsApp passa da un unico script, notifica. Usa un rest_command verso OpenWA e ha due difese contro gli eccessi.
- Un tetto di 30 messaggi al giorno, contati con un contatore che si azzera a mezzanotte. Oltre il tetto il messaggio non parte: compare come notifica dentro Home Assistant e viene contato tra i «bloccati dal limite».
- Una pausa casuale di 3-8 secondi tra un invio e l'altro, e una coda (
mode: queued) perché più avvisi contemporanei non partano tutti insieme.
rest_command:
openwa_send:
url: !secret openwa_send_url
method: post
headers:
X-API-Key: !secret openwa_api_key
content_type: "application/json"
payload: '{"chatId": "{{ chat_id }}", "text": {{ text | tojson }} }'
timeout: 20
script:
notifica:
alias: Notifica
mode: queued
max: 20
fields:
messaggio: { name: Messaggio, required: true, selector: { text: { multiline: true } } }
variables:
limite: 30
targets: !secret wa_chat_ids
sequence:
- repeat:
for_each: "{{ targets }}"
sequence:
- choose:
- conditions: "{{ states('counter.wa_inviati_oggi') | int(0) < limite }}"
sequence:
- action: rest_command.openwa_send
data: { chat_id: "{{ repeat.item }}", text: "{{ messaggio }}" }
response_variable: resp
continue_on_error: true
- action: counter.increment
target: { entity_id: counter.wa_inviati_oggi }
- delay: { seconds: "{{ range(3, 8) | random }}" }
default:
- action: counter.increment
target: { entity_id: counter.wa_soppressi_oggi }
Il codice qui sopra è una versione ridotta: quello vero controlla anche che la risposta di OpenWA sia un 200 o un 201 prima di contare il messaggio come inviato, e segnala l'errore con una notifica se non lo è.
Ricevere: comandi da WhatsApp
OpenWA registra un webhook verso Home Assistant per i messaggi ricevuti, ed è raggiungibile solo dentro la rete Docker. Il webhook ha un identificativo segreto lungo e casuale, generato dallo script e conservato in secrets.yaml. L'automazione lo usa come trigger webhook.
Il punto delicato è la fiducia: rispondere a chiunque scriva a quel numero sarebbe un errore. L'automazione accetta solo i mittenti autorizzati, che WhatsApp identifica con un proprio identificativo interno (chiamato LID) o con il numero, salvati in secrets.yaml. Uno sconosciuto non riceve nessuna risposta: in Home Assistant compare soltanto una notifica. L'automazione evita anche di elaborare due volte lo stesso messaggio.
Questi sono i comandi che ho abilitato:
aiuto: l'elenco dei comandi.stato: lo stato del mini PC.wifi: gli access point e i client attivi.client: l'elenco dei dispositivi connessi.messaggi: il contatore WhatsApp di oggi.spesa,listaetogli: la lista della spesa, di cui parlo nella guida su Google Keep.
Le risposte passano dallo script notifica, quindi contano nel tetto giornaliero come ogni altro messaggio. Un comando non riconosciuto riceve la risposta «Non ho capito», con il rimando ad aiuto.
Sapere se il gateway è vivo
Un gateway WhatsApp può scollegarsi senza far rumore. Ogni minuto Home Assistant interroga OpenWA con un sensore REST e ne ricava due sensori: gateway connesso e account con restrizioni. Se il gateway resta scollegato per tre minuti compare una notifica dentro Home Assistant, e quando torna su sparisce da sola. Se OpenWA segnala una restrizione sull'account, la notifica suggerisce di sospendere gli invii e controllare la sua dashboard.
rest:
- resource: http://openwa:2785/api/sessions
scan_interval: 60
timeout: 15
headers:
X-API-Key: !secret openwa_api_key
binary_sensor:
- name: WhatsApp gateway connesso
unique_id: wa_gateway_connesso
device_class: connectivity
value_template: "{{ value_json | selectattr('status', 'eq', 'ready') | list | count > 0 }}"
- name: WhatsApp account con restrizioni
unique_id: wa_account_restrizioni
device_class: problem
value_template: "{{ value_json | selectattr('restriction', 'defined') | rejectattr('restriction', 'none') | list | count > 0 }}"
Email: uno script che si collega a ogni invio
Per l'email ho provato prima il servizio smtp integrato di Home Assistant, poi l'ho sostituito. Quel servizio si collega al server una volta sola, all'avvio. Se in quel momento la connessione non riesce, il servizio non viene creato e resta assente fino al riavvio successivo.
Adesso un piccolo script, send_mail.py, si collega a ogni invio. Non dipende dall'avvio, riprova tre volte, riporta l'errore vero e si può provare anche da PowerShell. Legge la prima riga come oggetto e il resto come corpo, prende i dati SMTP da secrets.yaml (porta 465 significa SMTPS, ogni altra porta usa STARTTLS) e scrive lo stato in un file JSON e un registro, mai la password. Home Assistant lo richiama come servizio notify di tipo command_line.
Da questo lavoro escono tre sensori di stato: ultimo tentativo, ultimo invio riuscito e ultimo errore. Sono quelli che compaiono nel blocco «Email» della scheda.
Notifiche app
La terza strada è la notifica push dell'app Companion. Il servizio ha un nome del tipo notify.mobile_app_NOMETELEFONO, che ricavo da quello già presente nella configurazione. Un contatore conta le notifiche inviate oggi e ne ricorda l'ultima. Nel blocco «Notifiche app» ho anche i sensori del telefono, se l'app li ha creati (batteria, connessione e simili).
Lo script «avviso» e il menu dei canali
Tutti gli avvisi passano da un solo script, avviso. Riceve un titolo, un messaggio e il nome dell'evento, e per quell'evento legge la scelta fatta in un input_select. Le scelte sono otto: tutti i canali, WhatsApp + email, WhatsApp + app, email + app, solo WhatsApp, solo email, solo app, nessuno. In cima alla scheda ci sono un menu per ogni avviso e uno intitolato «Imposta tutti gli avvisi su», che applica una scelta a tutti in un colpo. Home Assistant ricorda le scelte anche dopo un riavvio.
L'ordine di consegna è pensato per i guasti:
- App ed email partono subito. L'email è l'ultimo passo, così un suo guasto non blocca gli altri canali.
- WhatsApp aspetta. Se il gateway non è connesso, lo script attende fino a cinque minuti che torni su, poi decide. Il messaggio passa comunque dal tetto giornaliero.
- «Nessuno» non manda nulla, ma scrive una riga nel registro (Logbook), per non perdere traccia dell'evento.
I quattordici avvisi che ho sotto questo menu sono: temperatura CPU alta, temperatura SSD alta, disco quasi pieno, RAM alta, access point offline, access point di nuovo online, controller Omada non raggiungibile, monitoraggio del mini PC muto, riavvio del mini PC, interruzione di rete, backup non riuscito, gateway WhatsApp scollegato, gateway di nuovo connesso, restrizioni sull'account WhatsApp. Gli ultimi tre partono da «Email + app», perché in quel momento WhatsApp non è affidabile. Tutti gli altri partono da «Tutti i canali». In seguito ho aggiunto lo stesso menu per gli avvisi di stampante, telecamere e robot.
input_select:
avviso_temp_cpu:
name: "Temperatura CPU alta"
icon: mdi:bell-cog
options:
- "Tutti i canali"
- "WhatsApp + email"
- "WhatsApp + app"
- "Email + app"
- "Solo WhatsApp"
- "Solo email"
- "Solo app"
- "Nessuno"
# dentro lo script "avviso":
# scelta: {{ states('input_select.avviso_' ~ evento) }}
# usa_app: {{ scelta in ['Tutti i canali', 'WhatsApp + app', 'Email + app', 'Solo app'] }}
# usa_mail: {{ scelta in ['Tutti i canali', 'WhatsApp + email', 'Email + app', 'Solo email'] }}
# usa_wa: {{ scelta in ['Tutti i canali', 'WhatsApp + email', 'WhatsApp + app', 'Solo WhatsApp'] }}
Provare tutto senza aspettare un guasto
Nella colonna di destra ci sono quattro pulsanti di prova: solo WhatsApp, solo email, solo notifica app e uno che li prova tutti e tre passando dallo stesso percorso degli avvisi veri.
Ora che gli avvisi funzionano, restano due domande: cosa succede se cade la rete, e cosa se cade il disco. Le risposte sono nelle guide sul monitor di rete e sui backup cifrati.