Power Up Your Alerts: Integrating Telegram with Home Assistant for Rich Notifications and Control

Why Use Telegram for Home Assistant Notifications?

When it comes to getting alerts from your smart home, standard push notifications are helpful, but Telegram offers a significant upgrade. Telegram is a popular, free messaging platform known for its reliability, speed, and rich feature set, including support for bots, inline keyboards, and media sharing. Integrating it with Home Assistant allows for:

• Rich Notifications: Send detailed text messages, images, videos, and documents directly to your phone or group chats.
• Interactive Alerts: Use inline keyboards to create actionable notifications, allowing you to respond to alerts (e.g., disarm alarm, open gate, snooze reminder) without opening the Home Assistant app.
• Two-Way Communication: Not only receive messages, but also send commands to Home Assistant via your Telegram chat.
• Reliability: Telegram's infrastructure is generally robust, providing dependable delivery of critical alerts.
• Group Notifications: Easily send alerts to multiple family members or specific groups.

Compared to simpler notification services, Telegram provides a powerful, flexible, and cost-free method for keeping tabs on and interacting with your smart home.

Prerequisites

Before you begin, ensure you have:

• A running Home Assistant instance.
• A Telegram account on your mobile device or desktop.

Step-by-Step Setup

1. Create a Telegram Bot

The first step is to create a dedicated Telegram Bot that Home Assistant will use to send messages and receive commands.

1. Open Telegram and search for the user @BotFather. This is the official bot from Telegram for creating and managing bots.
2. Start a chat with BotFather and type /newbot.
3. BotFather will ask for a name for your bot. Choose a descriptive name (e.g., "My Home Assistant Bot").
4. Next, BotFather will ask for a username. This must be unique and end with "bot" (e.g., "MyHASmartHome_bot").
5. If successful, BotFather will provide you with a token. This is your bot's API key (looks like a long string of letters and numbers separated by a colon). Keep this token secret! You will need it for Home Assistant configuration. Copy this token.

2. Find Your Chat ID

Home Assistant needs to know where to send messages. This is done using your personal Chat ID or a group's Chat ID. You can find your Chat ID in several ways:

1. Start a chat with your newly created bot. Send it any message (e.g., "hello").
2. Open a web browser and navigate to: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates (Replace <YOUR_BOT_TOKEN> with the token you got from BotFather).
3. Look for the chat object in the JSON response. Your Chat ID will be the value associated with the id field (it's a number, often negative for group chats). It should look something like "chat":{"id":123456789,...}. The number 123456789 is your Chat ID.

If you want to send messages to a group, add your bot to the group first, send a message in the group, and then use the getUpdates method again. The Chat ID you find will be the group's ID.

3. Configure Home Assistant

The Telegram integration requires configuration via your configuration.yaml file.

Add the following to your configuration.yaml:

telegram_bot:
  - platform: webhooks
    api_key: YOUR_BOT_TOKEN
    allowed_chat_ids:
      - YOUR_CHAT_ID_1
      - YOUR_CHAT_ID_2

notify:
  - name: telegram_notifications
    platform: telegram
    chat_id: YOUR_CHAT_ID_1 # Use the primary chat ID you want to send notifications to

• Replace YOUR_BOT_TOKEN with the token you obtained from BotFather.
• Replace YOUR_CHAT_ID_1 and YOUR_CHAT_ID_2 with the Chat IDs you want your bot to interact with. It's a security best practice to list only trusted Chat IDs.
• The platform: webhooks configuration for telegram_bot is recommended as it's more efficient than polling. This requires your Home Assistant instance to be accessible from the internet (e.g., via Home Assistant Cloud or a reverse proxy with valid SSL). If your instance is not externally accessible, you might need to use platform: polling, though webhooks are preferred.
• The notify section sets up a notification service specifically for Telegram. Give it a unique name (e.g., telegram_notifications). Set the chat_id to the default recipient Chat ID for this service. You can override this in individual automation actions.

Save the configuration.yaml file and restart Home Assistant (or use the "Restart" server control option after checking configuration is valid).

Using Telegram for Notifications

Once configured, you can use the notify.telegram_notifications service in your automations to send messages.

Example: Simple Text Notification

automation:
  - alias: Send Door Open Alert via Telegram
    trigger:
      platform: state
      entity_id: binary_sensor.door_contact
      to: 'on'
    action:
      service: notify.telegram_notifications
      data:
        message: "The front door has been opened!"

Example: Sending an Image

You can send photos, for instance, from a security camera when motion is detected.

automation:
  - alias: Send Motion Detected Image via Telegram
    trigger:
      platform: state
      entity_id: binary_sensor.motion_sensor_backyard
      to: 'on'
    action:
      service: notify.telegram_notifications
      data:
        message: "Motion detected in the backyard!"
        data:
          photo:
            - file: /config/www/camera_snapshots/backyard_latest.jpg # Path accessible by Home Assistant
              caption: "Backyard Motion"

Note: The file path needs to be accessible by the Home Assistant user. Often, the /config/www/ directory is used for files intended for the web server or accessible by integrations. You'll need to configure your camera integration or another automation to save snapshots to this location.

Advanced Interaction: Inline Keyboards and Receiving Commands

Interactive Notifications (Inline Keyboards)

Telegram supports inline keyboards attached directly to messages. These buttons trigger callbacks that Home Assistant can receive and act upon.

Example: Ask to Disarm Alarm

automation:
  - alias: Ask to Disarm Alarm on Presence
    trigger:
      platform: state
      entity_id: person.me
      to: 'home'
    condition:
      condition: state
      entity_id: alarm_control_panel.home_alarm
      state: 'armed_away'
    action:
      service: notify.telegram_notifications
      data:
        message: "Welcome home. Disarm the alarm?"
        data:
          inline_keyboard:
            - "Disarm:/disarm_alarm"
            - "Ignore:/ignore_presence_disarm"

When a user clicks "Disarm", the Telegram bot integration receives the callback data /disarm_alarm. You can then trigger other automations based on this received command.

Receiving Commands (Polling or Webhooks)

To receive messages or button callbacks, the telegram_bot component needs to be configured (as shown in the setup section). The received messages and callbacks fire events in Home Assistant. You can trigger automations based on these events.

The event name is telegram_callback for inline keyboard presses and telegram_command for messages starting with /.

Example: Automation Triggered by Inline Keyboard Callback

automation:
  - alias: Handle Disarm Alarm Command from Telegram
    trigger:
      platform: event
      event_type: telegram_callback
      event_data:
        data: '/disarm_alarm'
    action:
      service: alarm_control_panel.alarm_disarm
      target:
        entity_id: alarm_control_panel.home_alarm

Example: Automation Triggered by a Text Command

automation:
  - alias: Control Light via Telegram Command
    trigger:
      platform: event
      event_type: telegram_command
      event_data:
        command: '/turn_on_living_room_light'
    action:
      service: light.turn_on
      target:
        entity_id: light.living_room_main

The user would type /turn_on_living_room_light in the chat with the bot to trigger this automation.

Best Practices for a Reliable System

• Secure Your Bot Token: Treat your bot token like a password. Do not share it or expose it in public logs or repositories.
• Use allowed_chat_ids: Always specify the allowed_chat_ids in your telegram_bot configuration. This prevents unauthorized users who might somehow find your bot from controlling your home or receiving sensitive information.
• Manage Notification Volume: Avoid sending excessive notifications. Think about which events truly warrant an alert. Use conditions in your automations to filter less important events or group notifications (e.g., a single notification for "multiple windows left open" rather than one for each window).
• Context is Key: When sending notifications, provide enough context (e.g., entity name, state change details) so you know what's happening without needing to open Home Assistant.
• Test Thoroughly: Test your notifications and interactive commands to ensure they trigger correctly and perform the intended actions.
• Consider Telegram Limits: Telegram has API rate limits. For a typical smart home setup, you're unlikely to hit these limits with standard alerts, but be mindful if you're designing complex systems sending messages very frequently.
• Use Webhooks if Possible: If your Home Assistant instance is externally accessible and secured (with SSL), the webhook method for telegram_bot is generally more efficient and responsive than polling.

Conclusion

Integrating Telegram with Home Assistant significantly enhances your smart home's communication capabilities. Moving beyond simple text alerts, you gain the ability to send rich media, create interactive workflows directly within your chat, and even control devices by sending commands. By following the setup steps and best practices outlined above, you can build a more responsive, informative, and reliable smart home ecosystem powered by Telegram.