Voltar para o blog

Notificações push no Home Assistant com rest_command: vazamento, máquina de lavar, porta

Notificações push no Home Assistant com rest_command: vazamento, máquina de lavar, porta

O app Home Assistant Companion lida bem com notificações para quem usa o Home Assistant. A coisa complica quando quem precisa saber de um vazamento no porão é o seu parceiro, que nunca instalou o app, um dos seus pais ou o vizinho que tem a sua cópia da chave. Criar uma conta no Home Assistant só para essa pessoa receber uma notificação push é dar mais acesso do que ela precisa.

Também existe o problema do barulho. "Máquina de lavar terminou" e "água no chão do banheiro" não deveriam soar iguais, e se seus alertas de servidor já passam por outro app, você acaba com dois feeds para checar.

Este guia usa o rest_command do Home Assistant para enviar notificações push pelo Pocket Alert. Não precisa de add-on nem de integração personalizada, e cobre três automações: um vazamento de água em nível crítico, uma máquina de lavar que terminou em nível baixo e uma porta aberta quando ninguém está em casa.

O que você precisa

  • Home Assistant com acesso ao configuration.yaml (editor de arquivos ou add-on Studio Code Server, ou SSH).
  • Uma conta no Pocket Alert, uma chave de API em Chaves de API e o app no celular que deve receber os alertas, iPhone ou Android. O plano gratuito cobre 50 mensagens por dia em um dispositivo.

O rest_command

Coloque a chave em secrets.yaml, na mesma pasta do configuration.yaml:

pocketalert_token: "YOUR_API_KEY"

Depois adicione um comando no 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 }}

Reinicie o Home Assistant. Agora você tem uma ação chamada rest_command.pocketalert, e tudo o que você passar em data vira uma variável de template: title, message, um level opcional e um botão opcional.

Por que montar o JSON com to_json em vez de escrever à mão? Um nome de sensor com aspas quebraria uma string escrita manualmente, e o to_json faz o escape para você. A API do Pocket Alert aceita apenas JSON, e é por isso que content_type está definido: sem ele, a requisição sai sem o tipo de conteúdo JSON.

Teste pelo Ferramentas do desenvolvedor → Ações: escolha rest_command.pocketalert, mude para o modo YAML e execute:

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

A notificação deve chegar em um ou dois segundos.

Três automações

Adicione estas no editor de automações (Editar em YAML) ou no automations.yaml. Troque os IDs das entidades pelos seus.

Vazamento de água: crítico

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 é o nível para coisas que não podem esperar até de manhã. No iPhone ele toca com volume próprio, passando pela chave de silencioso e pelo Não perturbe; no Android usa um canal separado que ignora o Não perturbe e ocupa a tela. Crítico faz parte dos planos pagos; no plano gratuito, a mesma mensagem chega como high, que ainda passa pelo Foco, mas não pela chave de silencioso.

Máquina de lavar terminou: baixo

Não existe um sensor de "máquina terminou", mas uma tomada inteligente com medição de energia informa isso: quando o consumo fica abaixo de alguns watts por alguns minutos, o ciclo acabou.

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 chega em silêncio, sem som e sem interromper. Ela fica na lista quando você olha o celular, o que combina com a urgência de roupa molhada. Ajuste below e for para a sua máquina: algumas pausam por um ou dois minutos no meio do ciclo.

Porta aberta com ninguém em casa: alto

O estado de zone.home é o número de pessoas na zona, então "0" significa que todo mundo saiu.

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 é marcado como sensível ao tempo no iPhone, então passa pelo Foco e pelo resumo agendado. A linha da mensagem é um template: os valores em data são renderizados antes de chegar ao comando.

Um botão que fecha a válvula de água

Um alerta de vazamento é mais útil quando você consegue agir sobre ele. As notificações do Pocket Alert podem ter até três botões de ação, e um botão http envia a requisição a partir do próprio celular. O Pocket Alert não faz proxy disso. Isso significa que o botão pode chamar um webhook do Home Assistant que não está exposto à internet, desde que o celular consiga alcançá-lo.

Primeiro, uma automação que fecha a válvula quando o webhook é chamado:

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 a sua válvula aparecer como um switch, use switch.turn_off. Deixe o ID do webhook longo e aleatório: webhooks do Home Assistant não têm outra autenticação além de conhecer o ID.

Depois adicione o botão na automação de vazamento:

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"

O rest_command acima transforma button_url em uma ação http com método POST. Ao tocar no botão, o celular envia a requisição em segundo plano, sem abrir o app.

Qual URL usar:

  • Só em casa: o endereço pelo qual o celular acessa o Home Assistant na sua Wi-Fi. local_only: true mantém o webhook fechado para a internet. Prefira um endereço https:// se tiver um na sua rede.
  • De qualquer lugar: um vazamento geralmente acontece quando você está fora. A documentação do Home Assistant informa que webhooks com local_only ainda funcionam pelos webhooks do Home Assistant Cloud (Nabu Casa), então essa URL da nuvem é a opção mais fácil. Uma VPN no celular, como Tailscale ou WireGuard, também funciona com o endereço da rede local.

O próprio Home Assistant recomenda não colocar ações destrutivas ou perigosas atrás de um webhook, como destrancar uma porta. Fechar a válvula de água é o sentido seguro; abri-la não é, então mantenha isso fora dos botões do celular. Um segundo toque envia uma segunda requisição, o que não tem problema aqui, pois fechar uma válvula já fechada não faz nada.

Duas coisas para saber sobre os botões. Eles são um recurso dos planos pagos e são removidos das mensagens no plano gratuito; o alerta em si continua chegando. E tanto o iOS quanto o Android mostram o seu próprio rótulo na própria notificação, mesmo com o app do Pocket Alert fechado (versão 2.0.1 ou superior). Os botões também ficam salvos com a mensagem no app, então você ainda pode tocar neles depois que o aviso desaparece.

Alertas para pessoas sem Home Assistant

Quem recebe a notificação precisa apenas do app do Pocket Alert. Há duas formas de configurar:

  • Conta própria. A pessoa cria uma conta gratuita, gera uma chave de API e a envia para você. Adicione um segundo comando, pocketalert_family, com a chave dela no secrets.yaml, e chame os dois comandos na automação de vazamento. Os alertas do seu servidor continuam na sua conta; ela vê apenas o que você enviar.
  • Um segundo dispositivo na sua conta. Os planos pagos incluem vários dispositivos. Adicione o celular dela e faça uma cópia do comando com "device_id": "THEIR_DEVICE_ID" adicionado ao dicionário body, para que apenas os alertas da casa cheguem a ele.

De qualquer forma, ela recebe o alerta de vazamento com o mesmo nível e botão, sem precisar de uma conta no seu Home Assistant.

Um app para a casa e para todo o resto

A mesma chave de API funciona para tarefas cron, backups, verificações de uptime e CI. Se você tem um homelab, os alertas de Proxmox, NAS e backup caem no mesmo feed do sensor de vazamento, cada um com seu nível, e o app pode filtrar o feed por nível, então os dois que importavam são fáceis de achar entre quarenta. Para outros sensores (placas ESP32, um Raspberry Pi, Node-RED), veja alertas de IoT e sensores.

Para dispositivos que só conseguem enviar um webhook JSON, existe uma opção sem código: crie um webhook no console e monte a mensagem a partir do payload. Veja Webhook para push.

RESTful Notifications como ação notify

Se você prefere ações notify.*, a plataforma RESTful Notifications do Home Assistant também pode enviar para o 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 envia um corpo JSON, title_param_name associa o título da notificação ao nosso campo title, e data adiciona campos fixos. Chame com action: notify.pocketalert e title mais message. O nível é fixo por notificador, então crie um para cada nível se precisar de vários, ou use o rest_command, que também cuida dos botões.

Se nada chegar

  • Verifique o log. O rest_command registra um aviso com o código de status quando a requisição falha. 401 significa que a chave no secrets.yaml está errada; 400 geralmente significa que o payload não é um JSON válido.
  • Reinicie na primeira vez. O primeiro bloco rest_command precisa de um reinício do Home Assistant antes que a ação apareça; edições posteriores são carregadas com a ação rest_command.reload.
  • Execute a ação manualmente pelas Ferramentas do desenvolvedor. Se funcionar, o problema está no gatilho ou na condição da automação; verifique o histórico dela.
  • O botão não faz nada: abra o host da URL do webhook no navegador do celular. Se o celular não consegue alcançar o Home Assistant nesse endereço, o botão também não consegue.
  • Veja a cota de hoje. O plano gratuito para em 50 mensagens por dia, e um sensor muito falante pode esgotar isso. Um for: no gatilho ajuda.

Perguntas frequentes

Preciso do app Home Assistant Companion?

Não. A notificação vem do Pocket Alert, então o celular só precisa do app do Pocket Alert. Você pode manter o Companion para os sensores e o rastreamento de localização.

Isso funciona com o Home Assistant Cloud?

Sim. O rest_command chama a API do Pocket Alert diretamente a partir do seu Home Assistant, então não depende do Nabu Casa. O Home Assistant Cloud só ajuda com o botão da válvula quando você está fora de casa.

O alerta de vazamento pode me acordar à noite?

No nível critical, sim: ele toca pela chave de silencioso no iPhone e passa pelo Não perturbe no Android. Esse nível exige um plano pago; no plano gratuito ele chega como high.

Minha chave de API fica exposta?

Ela fica no secrets.yaml e é enviada no cabeçalho Token por HTTPS. Use uma chave separada para o Home Assistant, assim você pode revogá-la sem mexer nos seus outros scripts.

Crie uma conta gratuita, adicione um rest_command e deixe a casa avisar quando precisar de você.

Compartilhe este artigo