Level Up Your Home Assistant Notifications with Telegram

Notifications are a crucial part of any smart home setup. They keep you informed about what's happening when you're not actively monitoring your dashboard – a door opening, a motion detection, a package arrival, or a system status update. While Home Assistant offers various notification methods, integrating with a popular messaging service like Telegram provides significant advantages, including instant delivery, rich media support, group messaging capabilities, and cross-platform access.

Why Telegram for Home Assistant Notifications?

Telegram stands out for several reasons:

• Reliability: Messages are generally delivered instantly.
• Rich Content: Send text, photos, locations, and even files.
• Interactive Messages: Use inline keyboards to create actionable buttons directly within the notification.
• Group Support: Send alerts to multiple family members or designated groups simultaneously.
• Cross-Platform: Access your notifications on mobile (iOS, Android), desktop (Windows, macOS, Linux), and web browsers.
• Free & Secure: Telegram is free to use and known for its strong encryption.

Prerequisites

Before you begin, ensure you have:

• A running instance of Home Assistant.
• The Telegram app installed on your device(s).
• A Telegram account.

Step 1: Create a Telegram Bot

Home Assistant communicates with Telegram via a bot. Creating one is straightforward:

1. Open Telegram and search for the user @BotFather (the official bot to create other bots).
2. Start a chat with @BotFather.
3. Send the command /newbot.
4. @BotFather will ask for a name for your bot (e.g., "My Home Assistant Alerts"). Choose a descriptive name.
5. Next, choose a username for your bot. It must end with "bot" (e.g., "my_hass_alerts_bot"). Ensure it's unique.
6. If successful, @BotFather will provide you with an API Token. This is a long string of characters (e.g., 123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklm). Keep this token safe and secret! You will need it for Home Assistant configuration.

Step 2: Get Your Chat ID(s)

Home Assistant needs to know where to send the messages. This is done using a Chat ID.

To get your personal Chat ID:

1. Search for your newly created bot in Telegram and start a chat with it. Send any message (e.g., "Hello"). This initiates a conversation that the bot can detect.
2. Open your web browser and navigate to https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates, replacing <YOUR_BOT_TOKEN> with the token you got from @BotFather.
3. Look for the JSON output. Find the section related to your message. The chat object will contain an id field. This is your personal Chat ID (e.g., 123456789). It's usually a positive integer.

To get a Group Chat ID:

1. Create a new group in Telegram and add your newly created bot to it.
2. Send any message in the group.
3. As with the personal Chat ID, navigate to https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates.
4. Look for the update corresponding to the message sent in the group. The chat object's id will be the Group Chat ID. Group IDs are typically large negative numbers (e.g., -1234567890).

Note down the Chat ID(s) you wish to send notifications to.

Step 3: Configure Home Assistant

Now, add the Telegram Bot integration to your Home Assistant configuration. Edit your configuration.yaml file.

telegram_bot:
  - platform: polling
    api_key: YOUR_BOT_TOKEN
    allowed_chat_ids:
      - YOUR_PERSONAL_CHAT_ID
      - YOUR_GROUP_CHAT_ID # Optional: Add other IDs as needed

notify:
  - name: telegram_notifications
    platform: telegram
    chat_id: YOUR_PERSONAL_CHAT_ID # Or a group ID, or define multiple notify services

Replace YOUR_BOT_TOKEN, YOUR_PERSONAL_CHAT_ID, and YOUR_GROUP_CHAT_ID with the values you obtained in the previous steps.

• platform: polling is the most common method for receiving commands back from Telegram (e.g., button presses). You can also use webhook for more advanced setups, but polling is simpler to start.
• allowed_chat_ids is a crucial security measure. Only Telegram users from these specific Chat IDs can send commands to your bot. Make sure to list all IDs you want to potentially send commands from. For simply sending notifications, you only need the IDs listed under the notify platform, but it's good practice to populate allowed_chat_ids if you ever plan to use interactive features.
• The notify section defines a notification service you can call from automations or scripts. You can define multiple notify services with different names and chat_ids if you want to send specific notifications to different people or groups.

Step 4: Restart Home Assistant

After modifying configuration.yaml, save the file and restart Home Assistant for the changes to take effect.

Go to Developer Tools -> YAML and click "Check Configuration" first to catch any errors before restarting.

Step 5: Send Your First Notification

Let's test the setup. Go to Developer Tools -> Services in Home Assistant.

• Select the service notify.telegram_notifications (or whatever name you gave your notify service).
• In the Service Data field (YAML mode), enter the following:

message: "Hello from Home Assistant!"

• Click "Call Service".

You should receive a message in your Telegram chat from your bot!

Integrating Telegram Notifications into Automations

Now you can use this service in your automations:

automation:
  - alias: 'Notify when front door opens'
    trigger:
      - platform: state
        entity_id: binary_sensor.front_door
        to: 'on'
    action:
      - service: notify.telegram_notifications
        data:
          message: "The front door just opened!"
      # Example sending a photo from a camera entity
      - service: notify.telegram_notifications
        data:
          message: "Here's a snapshot:"
          data:
            photo:
              - entity_id: camera.front_door_camera
                caption: "Front door view"

Advanced Telegram Notification Features

The Telegram integration supports many advanced features via the data field in your service calls:

• Sending Photos: Use photo: with a list of entity_id (for camera entities) or url (for publicly accessible images).
• Sending Locations: Use location: with latitude and longitude.
• Inline Keyboards: Add interactive buttons using inline_keyboard:. For example, a button to turn a light on or off directly from the notification.
• Custom Keyboards: Define a custom reply keyboard that appears in the chat.
• Templating: Use Jinja2 templates within the message or caption to include dynamic information (sensor states, time, etc.).

Consult the official Home Assistant documentation for the Telegram Bot integration for detailed examples of these advanced features.

Best Practices for Managing Notifications

• Prioritize: Not every event needs a notification. Only notify for important or actionable events (security alerts, critical status changes, user-initiated requests).
• Context is Key: Make your messages informative. Include the device name, state change, and any relevant sensor data. Use templating!
• Avoid Spamming: Implement cooldowns or conditions in your automations to prevent receiving dozens of messages for rapidly changing states (e.g., motion sensor triggering repeatedly).
• Use Groups Wisely: Send critical alerts to a family group, while less critical updates might go only to your personal chat.
• Test Thoroughly: Always test your notification automations to ensure they trigger correctly and the message content is accurate.
• Secure Your Bot Token: Treat your bot token like a password. Never share it or expose it publicly.

Conclusion

Integrating Telegram with Home Assistant provides a powerful and flexible way to enhance your smart home notifications. From simple text alerts to rich media and interactive controls, Telegram helps you stay connected and informed, adding a layer of convenience and reliability to your automated home.

Set up your Telegram bot today and start exploring the possibilities!