Home Assistant Telegram Notifications: Complete Guide

Getting real-time alerts from your smart home straight to your phone is one of the most useful things Home Assistant can do. Telegram — the free, fast messaging app — pairs exceptionally well with Home Assistant because it offers a proper bot API, works reliably on UK mobile networks, and requires no paid subscription. Once set up, you can receive text alerts, images from your security cameras, and custom status messages without touching a cloud subscription.

This guide assumes you already have Home Assistant running. If you are just getting started, see our Home Assistant UK setup guide first, then come back here.

Step 1: Create a Telegram Bot via @BotFather

Every Telegram integration begins with a bot. Bots are lightweight automated accounts that can send and receive messages on your behalf. You create and manage them using @BotFather, Telegram's official bot management service.

1. Open Telegram and search for @BotFather (the verified one has a blue tick).
2. Start a chat and send the command /newbot.
3. Follow the prompts: choose a display name (e.g. My Home Assistant) and a username ending in bot (e.g. myhomeassistant_bot).
4. BotFather will reply with your bot token — a long string that looks like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Copy it and keep it private; anyone with this token can control your bot.

Your bot is now live. The next step is to find the chat ID that tells Home Assistant where to send messages.

Step 2: Find Your Telegram Chat ID

Send any message to your bot. Open a new chat with your bot (search for its username in Telegram) and send a test message such as hello. This creates the conversation that Home Assistant needs to target.

Once you have sent a message, retrieve your chat ID by visiting this URL in your browser — replace YOUR_BOT_TOKEN with the token from BotFather:

https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates

The response is a JSON object. Look for the chat field inside message; the id value (a positive or negative integer) is your chat ID. Note it down — you will need it in the next step.

Step 3: Configure Home Assistant

Home Assistant's Telegram integration is configured in configuration.yaml. You need two blocks: one to define the bot connection (telegram_bot) and one to expose a notification service (notify).

Open your configuration.yaml file (in the Home Assistant config directory) and add the following, replacing the placeholders with your actual values:

telegram_bot:
  - platform: polling
    api_key: YOUR_BOT_TOKEN
    allowed_chat_ids:
      - YOUR_CHAT_ID

notify:
  - name: telegram
    platform: telegram
    chat_id: YOUR_CHAT_ID

A few notes on this configuration:

• polling platform — Home Assistant periodically checks the Telegram API for new messages. This works behind NAT and does not require opening any ports on your router, making it suitable for most UK home setups.
• allowed_chat_ids — whitelists the chat IDs that can trigger your Home Assistant bot. Only messages from these IDs will be processed, which prevents strangers from sending commands to your home.
• notify name — the name value becomes the service you call in automations. With name: telegram, the service will be notify.telegram.

After saving, restart Home Assistant (Settings → System → Restart) or reload your configuration if you have split YAML files. Home Assistant will validate the configuration on restart; check the logs if the integration does not appear.

Step 4: Test the Notification

Before building automations, confirm the integration is working. Go to Developer Tools → Services in Home Assistant, select notify.telegram, and call it with this data:

message: "Hello from Home Assistant!"

If your configuration is correct, the message should arrive in your Telegram chat within a few seconds. If it does not arrive, check Home Assistant's logs (Settings → System → Logs) for any authentication errors.

Step 5: Build Automations with Telegram Notifications

Once the service is working, you can wire it into any Home Assistant automation. The most common use case is motion detection alerts. Here is an example automation that fires when a motion sensor at the front door is triggered:

alias: Front Door Motion Alert
trigger:
  - platform: state
    entity_id: binary_sensor.front_door_motion
    to: "on"
action:
  - service: notify.telegram
    data:
      message: "Motion detected at front door!"

You can add this directly in the Automations editor by switching to YAML mode, or paste it into your automations.yaml file. For more on building automations, see our Home Assistant automations guide.

Sending Photos from Camera Entities

Telegram supports sending images, which makes it ideal for security camera alerts. Use the data.photo parameter to attach a snapshot from a Home Assistant camera entity:

action:
  - service: notify.telegram
    data:
      message: "Doorbell pressed — here is a snapshot."
      data:
        photo:
          - url: "http://localhost:8123/api/camera_proxy/camera.front_door"
            caption: "Front door camera"

Replace camera.front_door with your actual camera entity ID. The url field must be accessible by Home Assistant itself; if you are using an internal URL, make sure it is reachable from the Home Assistant host. You may need to include your long-lived access token as a Bearer header if the camera endpoint requires authentication — check the Home Assistant Telegram integration docs for the verify_ssl and authentication options.

Doorbell Press with Photo

A practical example combining a doorbell trigger with a camera snapshot:

alias: Doorbell Photo Alert
trigger:
  - platform: state
    entity_id: binary_sensor.doorbell
    to: "on"
action:
  - service: notify.telegram
    data:
      message: "Someone is at the door!"
      data:
        photo:
          - url: "http://localhost:8123/api/camera_proxy/camera.doorbell_cam"
            caption: "Doorbell camera snapshot"

Step 6: Advanced Tips

Sending to Multiple Chat IDs

If you want notifications to reach multiple people (for example, yourself and a partner), add additional chat IDs to allowed_chat_ids and create separate notify entries — one per recipient. You can also use Telegram groups: add your bot to a group and use the group's chat ID (which will be a negative number).

Two-Way Control

The polling platform also allows you to receive commands from Telegram. You can configure telegram_bot event triggers in automations to act on incoming messages — for example, typing /alarm off in your chat to disarm your alarm. This is an advanced use case covered in the Home Assistant Telegram bot documentation.

Keeping Your Token Secure

Store your bot token in Home Assistant's Secrets file (secrets.yaml) rather than directly in configuration.yaml. Reference it as !secret telegram_bot_token. This prevents the token from appearing in configuration backups or logs.

Troubleshooting Common Issues

No message received. Check that you have sent at least one message to the bot before Home Assistant tries to reach it — Telegram requires the user to initiate the conversation first.

chat_id not found. Visit the getUpdates URL again after sending a new message to the bot; the conversation may have expired from the update queue if too much time passed.

Integration not loading. Validate your YAML syntax with the Home Assistant configuration check (Settings → System → Check Configuration) before restarting. A single indentation error can prevent the entire block from loading.

Photos not sending. The camera URL must be reachable from the Home Assistant host machine, not just your browser. Use http://localhost:8123 rather than your local hostname if you are running a supervised install.

Related: Home Assistant mobile app guide, automate notifications with Node-RED, and best Home Assistant add-ons.