Jak propojit Home Assistant a Telegram

Článek popisuje, jak propojit Home Assistant s aplikací Telegram. Ukazuji, jak vytvořit chatovacího robota, který pravidelně odesílá informace o naší domácnosti a odpovídá na jednoduchá dotazy.

Jiné aplikace pro zasílání zpráv

Možná návod začínám trochu netradičně, ale myslím si, že je to na místě. Pokud Telegram zatím nepoužíváte, určitě ho nemá smysl instalovat, jen kvůli zasílání zpráv z Home Assistenta. Podívejte se do seznamu integrací, určitě zde najdete platformu, kterou již používáte. Může to být třeba Apple Push Notification Service, Discord, Facebook Messenger, Signal messenger, Slack nebo jen upozornění přes Home Assistant aplikaci.

Bezpečnost

Platforma Telegram aktuálně zažívá příliv nových uživatelů, kteří sem přecházejí z WhatsApp, protože se někde dočetli, že je Telegram bezpečnější. To není až tak úplně pravda. Ačkoli Telegram podporuje end-to-end šifrovanou komunikaci v individuálních chatech mezi lidmi, už ji bohužel nepodporuje ve skupinových chatech, ani v chatovacích robotech.

Komunikace mezi vámi, Telegramem a Home Assistantem tedy není end-to-end šifrovaná, ale probíhá pomocí zjednodušeného API, přes HTTPS protokol (jako když si prohlížíte internetové stránky). Servery Telegramu používají vlastní šifrovací protokol, u kterého existuje podezření na možné zranitelnosti.

Pokud se rozhodnete svůj Home Assistant propojit s Telegramem, určitě na tuto „hrozbu“ nezapomeňte. Nedoporučuji pomocí Telegram chatbotu ovládat kritické prvky domácnosti, jako je bezpečnostní systém nebo přes něj posílat snímky z bezpečnostních kamer.

Krok 1 – Vytvoření telegramového chatovacího robota

/start

Tím spustíme komunikaci s robotem. BotFather nám odpoví seznamem příkazů, kterými s ním můžeme komunikovat. Příkaz můžeme přepsat jako zprávu, ale jednodušší je na příkaz kliknout. Funguje totiž jako odkaz.

Nového robota tedy vytvoříme příkazem /newbot

/newbot

Odpověď od robota BotFather je jednoznačná. Máme si robota nějak pojmenovat. Jednoduše odepíšeme jméno robota. Toto jméno můžeme v budoucnu změnit pomocí příkazu /setname

Jméno našeho nového robota

Nyní musíme zvolit uživatelské jméno, pod kterým robota najdeme. Uživatelské jméno musí být unikátní a musí končit písmeny „bot“. Toto jméno už změnit nepůjde, ale můžeme robota smazat a vytvořit jiného. Pokud jsme trefili uživatelské jméno, které již existuje, BotFather nám to napíše.

Pokud je vše v pořádku, máme hotovo, náš chatovací robot je vytvořen a my se dozvíme autorizační token (řetězec znaků, který slouží k ovládání našeho robota). Kdokoliv, kdo tento řetězec znaků zná, může komunikovat s naším robotem. Takže opatrně.

Já: jmeno_robota_bot
BotFather: Done! Congratulations on your new bot. You will find it at t.me/jmeno_robota_bot. You can now add a description, about section and profile picture for your bot, see /help for a list of commands. By the way, when you've finished creating your cool bot, ping our Bot Support if you want a better username for it. Just make sure the bot is fully operational before you do this.

Use this token to access the HTTP API:
0123456789:ABC-def1234qwert_123-97W2v1qwjl12
Keep your token secure and store it safely, it can be used by anyone to control your bot.

For a description of the Bot API, see this page: https://core.telegram.org/bots/api

Jakmile vytvoříme robota a získáme autorizační token, můžeme s naším robotem začít komunikovat.

Krok 2 – získání chat_id

Získání chat_id, je další důležitá část nastavení. Pomocí chat_id určíme okruh uživatelů, kteří budou přijímat a odesílat zprávy do Home Assistanta. Moc nerozumím tomu, proč moje chat_id není vidět přímo v aplikaci a jeho získání je zbytečně komplikované.

Se získáním našeho chat_id nám opět pomůže robot (ale existují i jiné způsoby). Robotů je velká spousta, já použil @myidbot.

Vyhledáme robota v seznamu uživatelů a klikneme na tlačítko start. Pak už jen zažádáme o naše chat_id pomocí příkazu /getid. Robot odpoví naším chat_id číslem.

Robota už dále nebudeme potřebovat a můžeme ho smazat.

Stejný postup použijeme i pro další uživatele, kteří budou našeho robota používat. Vždy potřebujeme zjistit jejich <chat_id>, protože ho budeme potřebovat v kroku 4.

Krok 3 – první test robota

Nejprve v aplikaci Telegram najdeme našeho robota a zahájíme s ním komunikaci. Robota najdeme podle názvu, který jsme mu přidělili v kroku 1 (název končí znaky „bot“. Já během vytváření stihl jméno robota zapomenout, ale nic se neděje, stačilo se podívat do komunikace s @BotFather.

Já: jmeno_robota_bot
BotFather: Done! Congratulations on your new bot. ...

Nebudeme se ničím zdržovat a jdeme si rovnou zkusit poslat zprávu. V okně internetového prohlížeče zadáme adresu ve formátu https://api.telegram.org/bot<token>/sendMessage? chat_id=<chat_id>&text=zkusebni zprava, kde <token> je náš autorizační token, který nám v kroku 1 zaslal @BotFather a <chat_id> je naše chat_id, které nám zaslal @myidbot v kroku 2. Na konci URL adresy je text, který nám od robota přijde. Celá zpráva tedy bude vypadat takto:

https://api.telegram.org/bot0123456789:ABC-def1234qwert_123-97W2v1qwjl12/sendMessage?chat_id=411111113&text=zkusebni zprava

V konverzaci s naším robotem by se měla objevit zpráva „zkusebni zprava“ a prohlížeč by měl zobrazit něco ve smyslu:

{"ok":true,"result":{"message_id":2,"from":{"id":123456789,"is_bot":true,"first_name":"Jméno našeho nového robota","username":"jmeno_robota_bot"},"chat":{"id":411111113,"first_name":"jméno","type":"private"},"date":1613762236,"text":"zkusebni zprava"}}

Pokud zkušební zpráva dorazila, Telegramový robot je vytvořený a my můžeme pokračovat krokem 4 – nastavení Home Assistantu.

Krok 4 – nastavení Home Assistantu – změny v souboru configuration.yaml

Jak je u Home Assistant běžné, originální dokumentaci získáme na stránce, věnující se integraci Telegramu. V této části návodu popisuji části a ukazuji příklady, které jsem nastavoval u sebe doma.

Integraci Telegramu vytvoříme tak, že do souboru /config/configuration.yaml doplníme následující řádky.

• API_KEY je náš autorizační <token> z kroku 1
• ALLOWED_CHAT_IDS jsou <chat_id> všech uživatelů z kroku 2, kterým chceme komunikaci mezi Home Assistantem a robotem povolit

Myslím, že je dobrý nápad tyto proměnné uložit pomocí !secret. V mém návodu jsem to pro jednoduchost neudělal. Předpokládám ale, že návod časem rozšířím. Pokud máte v plánu s někým sdílet svoji konfiguraci, doporučuji citlivé údaje uložit odděleně dle dokumentace od Home Assistant.

telegram_bot:
  - platform: polling
    api_key: 0123456789:ABC-def1234qwert_123-97W2v1qwjl12
    allowed_chat_ids:
      - 411111113
      - 711111116

Dále v souboru /config/configuration.yaml vytvoříme seznam uživatelů, kterým budeme posílat automatizované informační zprávy.

notify:
# seznam uživatelů
  - name: telegram_user_1
    platform: telegram
    chat_id: 411111113
  - name: telegram_user_2
    platform: telegram
    chat_id: 711111116
# skupina všech uživatelů
  - name: all_telegram
    platform: group 
    services:
      - service: telegram_user_1
      - service: telegram_user_2

Konfiguraci uložíme a restartujeme Home Assistant. Pokud jsme vše zadali správně, v Home Assistant menu Developer Tools, pod kartou services uvidíme 3 nové služby.

• notify.all_telegram
• notify.telegram_user_1
• notify.telegram_user_2

Můžeme se tedy jednu službu vyzkoušet a odeslat pomoci ní zprávu .

Doufám, že zpráva dorazila v pořádku a můžeme přistoupit na vytváření automatizací.

Krok 5 – nastavení Home Assistantu – Změny v souboru automations.yaml

Automatické odeslání informační zprávy můžeme klidně naklikat a nastavit v kartě automatizací, ale na tento návod by to bylo moc obrázků, tak rovnou vkládám kód.

Automatizace 1 – odeslání stavu senzoru

Následující kód odešle stav senzoru sensor.spotreba_vody. Spouštěč jsem nastavil na čas 22:00 kdy většinou chodíme spát, takže máme představu o množství spotřebované vody.

- alias: Telegram_bot - spotřeba vody
  hide_entity: true
  trigger:
  - at: '22:00'
    platform: time
  action:
    - service: notify.all_telegram
      data_template:
        message: "Dnešní spotřeba vody byla {{ states('sensor.spotreba_vody') }} litrů"

Automatizace 2 – odeslání stavu více senzorů a na více služeb najednou

Odeslání stavu více senzorů je prakticky stejné, jako první příklad. Protože jsem zatím nepostavil žádnou meteostanici, ani nevytvořil řádný wallpanel, na kterém by Home Assistant běžel, posílám si teplotu a vlhkost sklepa každý večer Telegramem. Pro zkoušku jsem zahrnul také upozornění pomocí mobilní aplikace Home Assistant.

- alias: Telegram_bot - sklep
  hide_entity: true
  trigger:
  - at: '20:00'
    platform: time
  action:
    - service: notify.all_telegram
      data_template:
        message: "Sklep: {{ states('sensor.teplota_ve_sklepe') }} °C, {{ states('sensor.vlhkost_ve_sklepe') }} %"
    - service: notify.notify
      data:
        message: "{{ states('sensor.teplota_ve_sklepe') }} °C, {{ states('sensor.vlhkost_ve_sklepe') }} %"
        title: "Sklep"

Následující obrázek ukazuje zprávy z Home Assistantu zaslaném Telgram robotem. Jedná se o výsledek předchozích dvou automatizací (kromě akce service: notify.notify).

Automatizace 3 – odpovídání na dotazy

Home Assistant mám nastavený tak, abych k němu mohl přistupovat pouze z vnitřní sítě. To znamená, že když jsem někde mimo domácí Wi-Fi, tak se nedozvím žádné informace o domácnosti. Chybějící přístup lze vyřešit pomocí dotazů, na které robot odpoví.

Pro ukázku jsem si vybral zjištění stavu televize. Když robotovi pošlu zprávu /tv, přijde některá z následujících odpovědí. Poslední odpověď přijde v případě chybné komunikace s televizí. Samozřejmě je nutné, aby existovala integrace media_player.tv.

• Televieze je on
• Televize je off
• Televize je unavailable

- alias: Odepiš stav televize
  hide_entity: true
  trigger:
    platform: event
    event_type: telegram_command
    event_data:
      command: '/tv'
  action:
    - service: telegram_bot.send_message
      data_template:
        target: '{{ trigger.event.data.user_id }}'
        message: "Televize je {{ states('media_player.tv') }}"

Automatizace 4 – vložená klávesnice se všemi příkazy

Abych si nemusel pamatovat všechny dotazy, robot může nabídnout všechny akce, které podporuje. Lze vytvořit například automatizaci, která zobrazí klávesnici se všemi funkcemi. Aby robot správně odpovídal na dotazy naší klávesnice, musíme ve spouštěči změnit event_type: z telegram_comand na telegram_callback a vytvořit další automatizaci.

# první automatizace odpoví na tlačítko /spotreba
- alias: 'Telegram bot - klávesnice - aktuální spotřeba vody'
  hide_entity: true
  trigger:
    platform: event
    event_type: telegram_callback
    event_data:
      command: '/spotreba'
  action:
    - service: telegram_bot.send_message
      data_template:
        target: '{{ trigger.event.data.user_id }}'
        message: "Aktuální spotřeba vody je {{ states('sensor.spotreba_vody') }} litrů"

# druhá automatizace odpoví na tlačítko /tv
- alias: 'Telegram bot - klávesnice - stav televize'
  hide_entity: true
  trigger:
    platform: event
    event_type: telegram_callback
    event_data:
      command: '/tv'
  action:
    - service: telegram_bot.send_message
      data_template:
        target: '{{ trigger.event.data.user_id }}'
        message: "Televize je {{ states('media_player.tv') }}"

# třetí automatizace po zadání dotazu /akce zobrazí klávesnici
- alias: 'Telegram bot - zobraz klávesnici'
  trigger:
    platform: event
    event_type: telegram_command
    event_data:
      command: '/akce'
  action:
    - service: telegram_bot.send_message
      data:
        title: "Podporované akce"
        target: "{{ trigger.event.data.user_id }}"
        disable_notification: true
        inline_keyboard:
          - "Stav televize:/tv, Spotřeba vody:/spotreba"
          - "Akce 3:/akce3"
          - "Akce 4:/akce4, Akce 5:/akce5"

Užijte si komunikaci s robotem a nezapomeňte na bezpečnost. Pokud by někdo dokázal číst zprávy z Telegramu, mohl by například podle spotřeby vody zjistit, že už několik dní není nikdo doma. Možná, že by ho i napadlo přesunout některé části naší skvělé a chytré domácnosti k sobě domů. A to by se nám moc nehodilo.