Skip to main content

Telegram integration


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.


  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

    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
      - platform: polling
        api_key: YOUR_API_KEY
          - 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
      - 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
        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: ""
      - platform: event
        event_type: telegram_command
          command: /testme
    condition: []
      - service: telegram_bot.send_message
          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.