Skip to main content

Telegram integration

Documentation:
home-assistant.io/integrations/telegram/
home-assistant.io/integrations/telegram_bot/

 

With the Telegram integration Home Assistant can stablish a bidirectional communication channel with one or more chats, those chats can be people, groups or bots.

To get this working this is a quick summary of the steps:

  • Install Telegram in your computer or phone, create a new bot and gather the information of that bot.
  • Add some lines in the configuration.yaml of your Home Assistant server
  • Usea automations that get triggered when receiving commands sent from Telegram (written in the chat bot) or use automations to send messages (notifications) to Telegram destinations when anything happens in your phone.

Setup

  1. Install Telegram either in your phone or computer. If you don't have an account, create one.
  2. Search for "BotFather" and start a chat with it. Create a new bot using "/newbot". After asking you for a name and username for the bot, it will give you a link to start a new chat with your new bot and an HTTP API token (copy it and save it).
  3. Open the link to start a chat with the bot, and leave a message, any message.
  4. You need to know find the chat id of those chats to which you want to send notifications. You should also find the chat ID of the chat you opened with your bot, since that's the one you should use to send commands from Telegram to your HomeAssistant entity.
    Search for the user "Chat ID Bot", it will look like the one below

    image.png
    Start a chat with it.
    Now go to the chat with your bot, and right-click on the message you sent to your bot and choose Forward, forward it to "Chat ID Bot". When you do that, you will get an ID, copy it.


  5. Now go to your Home Assistant server, and to the configuration.yaml file, and copy this template:
    # Example configuration.yaml entry for the Telegram Bot
telegram_bot:
  - platform: polling
    api_key: YOUR_API_KEY
    allowed_chat_ids:
      - CHAT_ID_1 # example: 123456789 for the chat_id of a user
      - CHAT_ID_2 # example: -987654321 for the chat_id of a group
      - CHAT_ID_3

# Example configuration.yaml entry for the notifier
notify:
  - platform: telegram
    name: NOTIFIER_NAME
    chat_id: CHAT_ID_1

  # It is possible to add multiple notifiers by using another chat_id
  # the example belows shows an additional notifier which sends messages to the bot which is added to a group
  - platform: telegram
    name: NOTIFIER_NAME_OF_GROUP
    chat_id: CHAT_ID_2

    now you have to modify it:
    - Where it says "YOUR_API_KEY" please insert the API token you copied before
    - We have the ID that identifies the chat between you and your bot, so replace "Chat_ID_1" with that ID in "allowed_chats_ids". and also in the "chat_id" field of "notify" section.
    You can delete everything else for now.

  6. With that configuration we are ready to do a simple test that will check both receiving and sending.
  7. Create a new automation like this one:
    alias: Telegram test
description: ""
trigger:
  - platform: event
    event_type: telegram_command
    event_data:
      command: /testme
condition: []
action:
  - service: telegram_bot.send_message
    data:
      message: It worked!!
mode: single

    Here we are setting as a trigger the message "/testme" sent from Telegram to our bot. When Home Assistant receives that message it will then send a message back (since the bot chat ID is the one we added in the configuration.yaml) that will show almost inmediately in Telegram.

Back to top