The Telegram integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] uses Telegram to deliver notifications from Home Assistant to your Telegram application(s).

Setup example

To create your first Telegram bot, follow these steps:

• Bots are not allowed to contact users. You need to make the first contact from the user for which you want to set up the bot.

1. Tell Telegram to create a bot for you:

   • In Telegram, open a chat with @BotFather and enter /newbot.
   • Follow the instructions on screen and give your bot a name.
   • BotFather will give you a link to your new bot and an HTTP API token.
     • Store the token somewhere safe.

2. To get a chat ID, send any message to the GetIDs bot.

   • Then, enter /start.
   • The bot will return your chat ID and the username.

3. Create a Telegram bot in Home Assistant.

4. Create a notifier:

   • Paste this into your configuration file:

   • Replace the name and the chat_id with your data.

     # Notifier
     notify:
      - platform: telegram
      name: "sarah"
      chat_id: 44441111
     

   • Restart Home Assistant.

5. From the conversation with BotFather, select the link to open a chat with your new bot.

6. In the chat with the new bot, enter /start.

7. Test the action:

   • Go to Settings > Developer tools > Actions > YAML mode.

   • Paste this into the YAML file:

   • Replace the service and the message with your data.

     action: notify.sarah
     data:
      message: "Yay!AmessagefromHomeAssistant."
     

   • Select Perform action. You should now get a message.

8. You can do more with this. Check out the configuration descriptions and examples below.

Methods to retrieve a chat_id

Method 1: You can get your chat_id by sending any message to the GetIDs bot.

Method 2: To retrieve your chat_id you can visit https://api.telegram.org/bot<YOUR_API_TOKEN>/getUpdates or to use $ curl -X GET https://api.telegram.org/bot<YOUR_API_TOKEN>/getUpdates after you have sent the bot a message. Replace <YOUR_API_TOKEN> with your actual token.

The result set will include your chat ID as id in the chat section:

{"ok":true,"result":[{"update_id":254199982,"message":{"message_id":27,"from":{"id":123456789,"first_name":"YOUR_FIRST_NAME YOUR_NICK_NAME","last_name":"YOUR_LAST_NAME","username":"YOUR_NICK_NAME"},"chat":{"id":123456789,"first_name":"YOUR_FIRST_NAME YOUR_NICK_NAME","last_name":"YOUR_LAST_NAME","username":"YOUR_NICK_NAME","type":"private"},"date":1678292650,"text":"test"}}]}

Method 3: Another way to get your chat ID directly is described below. Start your Python interpreter from the command-line:

$ python3
>>> import telegram
>>> bot = telegram.Bot(token='YOUR_API_TOKEN')
>>> chat_id = bot.getUpdates()[-1].message.chat_id
>>> print(chat_id)
123456789

Method 4: You can also get the chat ID from the Home Assistant logs. If you have set up the bot already, you can send a message to your bot from an unauthorized ID and you will see an error entry in the log containing the ID.
👁 Open your Home Assistant instance and show your Home Assistant logs.

Configuration

To enable Telegram notifications in your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file. After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes. The integration is now shown on the integrations page under Settings > Devices & services. Its entities are listed on the integration card itself and on the Entities tab.

# 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

Refer to the platforms mentioned in the Telegram chatbot page for telegram_bot configuration.

To use notifications, please see the getting started with automation page.

Text message

...
actions:
 - action: notify.NOTIFIER_NAME
 data:
 title: "*Sendamessage*"
 message: "That'sanexamplethat_sends_a*formatted*messagewithacustominlinekeyboard."
 data:
 inline_keyboard:
 - 'Task1:/command1,Task2:/command2'
 - 'Task3:/command3,Task4:/command4'

Photo support

...
actions:
 - action: notify.NOTIFIER_NAME
 data:
 title: "Sendanimages"
 message: "That'sanexamplethatsendsanimage."
 data:
 photo:
 - url: http://192.168.1.28/camera.jpg
 username: "admin"
 password: "secret"
 - file: /tmp/picture.jpg
 caption: "PictureTitlexy"
 - url: http://somebla.ie/video.png
 caption: "Forexample,atitle"

configuration.yaml
...
homeassistant:
 allowlist_external_dirs:
 - /tmp
 - /home/kenji/data

Video support

...
actions:
 - action: notify.NOTIFIER_NAME
 data:
 title: "Sendavideo"
 message: "That'sanexamplethatsendsavideo."
 data:
 video:
 - url: http://192.168.1.28/camera.mp4
 username: "admin"
 password: "secret"
 - file: /tmp/video.mp4
 caption: "VideoTitlexy"
 - url: http://somebla.ie/video.mp4
 caption: "Forexample,atitle"

Document support

...
actions:
 - action: notify.NOTIFIER_NAME
 data:
 title: "Sendadocument"
 message: "That'sanexamplethatsendsadocumentandacustomkeyboard."
 data:
 document:
 file: /tmp/whatever.odf
 caption: "DocumentTitlexy"
 keyboard:
 - '/command1,/command2'
 - '/command3,/command4'

Location support

...

actions:
 - action: notify.NOTIFIER_NAME
 data:
 title: "Sendlocation"
 message: "Locationupdated."
 data:
 location:
 latitude: 32.87336
 longitude: 117.22743

Extra data attributes support

...
actions:
 - action: notify.NOTIFIER_NAME
 data:
 title: "*Sendamessage*"
 message: |-
 That's an example that sends a message with message_tag, disable_notification and disable_web_page_preview.
 <a href="https://www.home-assistant.io/">HA site</a>
 data:
 parse_mode: html
 message_tag: "example_tag"
 disable_notification: true
 disable_web_page_preview: true
 message_thread_id: 123