Torna al blog

Notifiche push da Home Assistant con rest_command: perdite, lavatrice, porta

Notifiche push da Home Assistant con rest_command: perdite, lavatrice, porta

L'app Home Assistant Companion gestisce bene le notifiche per chi usa Home Assistant. Diventa complicato quando la persona che dovrebbe sapere di una perdita in cantina è il tuo partner, che non l'ha mai installata, un genitore o il vicino che ha la tua copia delle chiavi. Dare loro un account Home Assistant solo per ricevere una notifica push significa concedere più accesso di quello che serve.

C'è poi il problema del rumore. "Lavatrice terminata" e "acqua sul pavimento del bagno" non dovrebbero suonare allo stesso modo, e se gli avvisi del server passano già da un'altra app, finisci per controllare due flussi diversi.

Questa guida usa rest_command di Home Assistant per inviare notifiche push tramite Pocket Alert. Non richiede add-on né integrazioni personalizzate e copre tre automazioni: una perdita d'acqua a livello critico, una lavatrice terminata a livello basso e una porta aperta quando non c'è nessuno in casa.

Cosa ti serve

  • Home Assistant con accesso a configuration.yaml (add-on File editor o Studio Code Server, oppure SSH).
  • Un account Pocket Alert, una chiave API da Chiavi API e l'app sul telefono che deve ricevere gli avvisi, iPhone o Android. Il piano gratuito copre 50 messaggi al giorno su un dispositivo.

Il rest_command

Inserisci la chiave in secrets.yaml, nella stessa cartella di configuration.yaml:

pocketalert_token: "YOUR_API_KEY"

Poi aggiungi un comando in configuration.yaml:

rest_command:
  pocketalert:
    url: https://api.pocketalert.app/v1/messages
    method: post
    content_type: application/json
    timeout: 10
    headers:
      Token: !secret pocketalert_token
    payload: >-
      {% set body = {"title": title, "message": message,
                     "level": level | default("default")} %}
      {% if button_url is defined %}
        {% set req = {"url": button_url, "method": "POST"} | to_json %}
        {% set body = dict(body, actions=[{"type": "http",
              "label": button_label | default("Run"), "value": req}]) %}
      {% endif %}
      {{ body | to_json }}

Riavvia Home Assistant. Ora hai un'azione chiamata rest_command.pocketalert, e tutto ciò che passi in data diventa una variabile del template: title, message, un level facoltativo e un pulsante facoltativo.

Perché costruire il JSON con to_json invece di scriverlo a mano? Un nome di sensore con una virgoletta romperebbe una stringa scritta a mano, mentre to_json la escapa automaticamente. L'API di Pocket Alert accetta solo JSON, ed è anche il motivo per cui è impostato content_type: senza, la richiesta partirebbe senza un content type JSON.

Provalo da Strumenti per sviluppatori → Azioni: scegli rest_command.pocketalert, passa alla modalità YAML ed esegui:

action: rest_command.pocketalert
data:
  title: "Hello from Home Assistant"
  message: "rest_command works"

La notifica push dovrebbe arrivare in uno o due secondi.

Tre automazioni

Aggiungile nell'editor delle automazioni (Modifica in YAML) oppure in automations.yaml. Sostituisci gli ID delle entità con i tuoi.

Perdita d'acqua: critico

alias: "Leak under the sink"
triggers:
  - trigger: state
    entity_id: binary_sensor.kitchen_leak
    to: "on"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Water leak: kitchen"
      message: "The sensor under the sink is wet. Check it now."
      level: critical

critical è il livello per le cose che non possono aspettare il mattino. Su iPhone suona con il proprio volume anche con l'interruttore silenzioso e Non disturbare attivi; su Android usa un canale separato che aggira Non disturbare e occupa lo schermo. Il livello critico fa parte dei piani a pagamento; nel piano gratuito lo stesso messaggio arriva come high, che passa comunque da Full immersion ma non dall'interruttore silenzioso.

Lavatrice terminata: basso

Non esiste un sensore "lavatrice terminata", ma una presa smart con misurazione della potenza ti dice quando il ciclo è finito: quando il consumo resta sotto pochi watt per alcuni minuti, il lavaggio è concluso.

alias: "Washer finished"
triggers:
  - trigger: numeric_state
    entity_id: sensor.washer_plug_power
    below: 5
    for: "00:03:00"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Washer finished"
      message: "Laundry is ready to hang."
      level: low

low arriva in silenzio, senza suono e senza interruzioni. Resta nell'elenco quando guardi il telefono, ed è proprio il giusto livello di urgenza per il bucato bagnato. Regola below e for in base alla tua macchina: alcune lavatrici si fermano per un minuto o due a metà ciclo.

Porta aperta con nessuno in casa: alto

Lo stato di zone.home è il numero di persone presenti nella zona, quindi "0" significa che sono tutti fuori.

alias: "Front door opened while away"
triggers:
  - trigger: state
    entity_id: binary_sensor.front_door
    to: "on"
conditions:
  - condition: state
    entity_id: zone.home
    state: "0"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Front door opened"
      message: "Opened at {{ now().strftime('%H:%M') }} and nobody is home."
      level: high

high è contrassegnato come sensibile al tempo su iPhone, quindi passa da Full immersion e dal riepilogo programmato. La riga del messaggio è un template: i valori in data vengono elaborati prima di raggiungere il comando.

Un pulsante che chiude la valvola dell'acqua

Un avviso di perdita è più utile quando puoi agire subito. Le notifiche di Pocket Alert possono contenere fino a tre pulsanti di azione, e un pulsante http invia una richiesta direttamente dal telefono. Pocket Alert non fa da proxy. Questo significa che il pulsante può chiamare un webhook di Home Assistant non esposto su internet, purché il telefono riesca a raggiungerlo.

Prima di tutto, un'automazione che chiude la valvola quando viene chiamato il suo webhook:

alias: "Close main water valve (from push)"
triggers:
  - trigger: webhook
    webhook_id: "close-valve-9f2c41d7a3b8e605"
    allowed_methods:
      - POST
    local_only: true
actions:
  - action: valve.close_valve
    target:
      entity_id: valve.main_water

Se la tua valvola compare come switch, usa switch.turn_off. Rendi lungo e casuale l'ID del webhook: i webhook di Home Assistant non hanno altra autenticazione oltre alla conoscenza dell'ID.

Poi aggiungi il pulsante all'automazione della perdita:

actions:
  - action: rest_command.pocketalert
    data:
      title: "Water leak: kitchen"
      message: "The sensor under the sink is wet."
      level: critical
      button_label: "Close water valve"
      button_url: "https://ha.example.com/api/webhook/close-valve-9f2c41d7a3b8e605"

Il rest_command sopra trasforma button_url in un'azione http con metodo POST. Quando tocchi il pulsante, il telefono invia la richiesta in background senza aprire l'app.

Quale URL usare:

  • Solo a casa: l'indirizzo con cui il telefono raggiunge Home Assistant sulla tua Wi-Fi. local_only: true tiene il webhook chiuso verso internet. Preferisci un indirizzo https:// se ne hai uno nella tua rete.
  • Da ovunque: una perdita di solito avviene quando sei fuori. La documentazione di Home Assistant indica che i webhook con local_only funzionano comunque tramite i webhook di Home Assistant Cloud (Nabu Casa), quindi quell'URL cloud è la soluzione più semplice. Anche una VPN sul telefono, come Tailscale o WireGuard, funziona con l'indirizzo LAN.

Il consiglio di Home Assistant stesso è di non mettere dietro a un webhook azioni distruttive o pericolose, come sbloccare una porta. Chiudere una valvola dell'acqua va nella direzione sicura; aprirla no, quindi tieni questa azione fuori dai pulsanti del telefono. Un secondo tocco invia una seconda richiesta, che qui è innocua perché chiudere una valvola già chiusa non fa nulla.

Due cose da sapere sui pulsanti. Sono una funzione dei piani a pagamento e vengono rimossi dai messaggi nel piano gratuito; l'avviso in sé arriva comunque. Inoltre sia iOS sia Android mostrano la tua etichetta direttamente sulla notifica, anche quando l'app Pocket Alert è chiusa (versione 2.0.1 o successiva). I pulsanti sono salvati insieme al messaggio nell'app, quindi puoi ancora toccarli quando il banner è sparito.

Avvisi per chi non ha Home Assistant

Chi riceve la notifica ha bisogno solo dell'app Pocket Alert. Ci sono due modi per configurarla:

  • Un account proprio. Si registrano gratuitamente, creano una chiave API e te la inviano. Aggiungi un secondo comando, pocketalert_family, con la loro chiave in secrets.yaml, e chiama entrambi i comandi nell'automazione della perdita. I tuoi avvisi del server restano nel tuo account; loro vedono solo quello che gli invii.
  • Un secondo dispositivo sul tuo account. I piani a pagamento includono più dispositivi. Aggiungi il loro telefono, poi crea una copia del comando con "device_id": "THEIR_DEVICE_ID" aggiunto al dizionario body, così solo gli avvisi di casa arrivano a quel dispositivo.

In entrambi i casi ricevono l'avviso di perdita con lo stesso livello e lo stesso pulsante, senza un account sul tuo Home Assistant.

Un'unica app per la casa e per tutto il resto

La stessa chiave API funziona per cron job, backup, controlli di uptime e CI. Se gestisci un homelab, gli avvisi di Proxmox, NAS e backup finiscono nello stesso flusso del sensore di perdita, ciascuno con il proprio livello, e l'app può filtrare il flusso per livello, così i due che contano sono facili da trovare tra quaranta. Per altri sensori (schede ESP32, un Raspberry Pi, Node-RED), vedi avvisi IoT e sensori.

Per i dispositivi che possono inviare solo un webhook JSON c'è un'opzione senza codice: crea un webhook nella console e costruisci il messaggio dal payload tramite template. Vedi Webhook to push.

RESTful Notifications come azione notify

Se preferisci le azioni notify.*, la piattaforma RESTful Notifications di Home Assistant può inviare notifiche anche a Pocket Alert:

notify:
  - name: pocketalert
    platform: rest
    resource: https://api.pocketalert.app/v1/messages
    method: POST_JSON
    title_param_name: title
    headers:
      Token: !secret pocketalert_token
    data:
      level: high

POST_JSON invia un corpo JSON, title_param_name associa il titolo della notifica al nostro campo title, e data aggiunge campi fissi. Richiamalo con action: notify.pocketalert e passa title più message. Il livello è fisso per ogni notifier, quindi crea un notifier per ogni livello se ne servono più d'uno, oppure usa rest_command, che gestisce anche i pulsanti.

Se non arriva nulla

  • Controlla il log. rest_command registra un avviso con il codice di stato quando la richiesta fallisce. 401 significa che la chiave in secrets.yaml è sbagliata; 400 di solito vuol dire che il payload non è JSON valido.
  • Riavvia la prima volta. Il primo blocco rest_command richiede un riavvio di Home Assistant prima che l'azione compaia; le modifiche successive si caricano con l'azione rest_command.reload.
  • Esegui l'azione a mano da Strumenti per sviluppatori. Se funziona, il problema è nel trigger o nella condizione dell'automazione; controllane la traccia.
  • Il pulsante non fa nulla: apri l'host dell'URL del webhook dal browser del telefono. Se il telefono non riesce a raggiungere Home Assistant a quell'indirizzo, neanche il pulsante ci riuscirà.
  • Controlla la quota di oggi. Il piano gratuito si ferma a 50 messaggi al giorno, e un sensore molto loquace può esaurirli. Un for: sul trigger aiuta.

FAQ

Ho bisogno dell'app Home Assistant Companion?

No. La notifica push arriva da Pocket Alert, quindi il telefono ha bisogno solo dell'app Pocket Alert. Puoi comunque tenere l'app Companion per i suoi sensori e il tracciamento della posizione.

Funziona con Home Assistant Cloud?

Sì. rest_command chiama direttamente l'API di Pocket Alert dal tuo Home Assistant, quindi non dipende da Nabu Casa. Home Assistant Cloud serve solo per il pulsante della valvola quando sei fuori casa.

L'avviso di perdita può svegliarmi di notte?

Con critical, sì: suona attraverso l'interruttore silenzioso su iPhone e attraverso Non disturbare su Android. Questo livello richiede un piano a pagamento; nel piano gratuito arriva come high.

La mia chiave API è esposta?

Sta in secrets.yaml e viene inviata nell'header Token tramite HTTPS. Usa una chiave separata per Home Assistant, così puoi revocarla senza toccare gli altri script.

Crea un account gratuito, aggiungi un rest_command e lascia che la casa ti avvisi quando ha bisogno di te.

Condividi questo articolo