Telegram
The telegram platform uses Telegram to deliver notifications from Home Assistant to your Telegram application(s).
Setup
The requirements are:
- You need a Telegram bot. Please follow those instructions to create one and get the token for your bot. Keep in mind that bots are not allowed to contact users. You need to make the first contact with your user. Meaning that you need to send a message to the bot from your user.
- You need to configure a Telegram bot in Home Assistant and define there your API key and the allowed chat ids to interact with.
- The
chat_idof an allowed user or group to which the bot is added.
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
Configuration
To enable Telegram notifications in your installation, add the following to your configuration.yaml file:
# 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
...
action:
service: notify.NOTIFIER_NAME
data:
title: "*Send a message*"
message: "That's an example that _sends_ a *formatted* message with a custom inline keyboard."
data:
inline_keyboard:
- 'Task 1:/command1, Task 2:/command2'
- 'Task 3:/command3, Task 4:/command4'
Photo support
...
action:
service: notify.NOTIFIER_NAME
data:
title: Send an images
message: "That's an example that sends an image."
data:
photo:
- url: http://192.168.1.28/camera.jpg
username: admin
password: secret
- file: /tmp/picture.jpg
caption: Picture Title xy
- url: http://somebla.ie/video.png
caption: i.e., for a Title
Configuration Variables
A remote path to an image. Either this or the file configuration option is required.
A local path to an image. Either this or the url configuration option is required.
Set to false to skip the validation of the server’s SSL certificate.
Since Home Assistant version 0.48 you have to whitelist the source folder of the file you want to include in the notification.
configuration.yaml
...
homeassistant:
allowlist_external_dirs:
- /tmp
- /home/kenji/data
Video support
...
action:
service: notify.NOTIFIER_NAME
data:
title: Send a video
message: "That's an example that sends a video."
data:
video:
- url: http://192.168.1.28/camera.mp4
username: admin
password: secret
- file: /tmp/video.mp4
caption: Video Title xy
- url: http://somebla.ie/video.mp4
caption: i.e., for a Title
Configuration Variables
A remote path to a video. Either this or the file configuration option is required.
A local path to a video. Either this or the url configuration option is required.
Set to false to skip the validation of the server’s SSL certificate.
Document support
...
action:
service: notify.NOTIFIER_NAME
data:
title: Send a document
message: "That's an example that sends a document and a custom keyboard."
data:
document:
file: /tmp/whatever.odf
caption: Document Title xy
keyboard:
- '/command1, /command2'
- '/command3, /command4'
Configuration Variables
A remote path to a document. Either this or the file configuration option is required.
A local path to a document. Either this or the url configuration option is required.
Set to false to skip the validation of the server’s SSL certificate.
Location support
...
action:
service: notify.NOTIFIER_NAME
data:
title: Send location
message: Location updated.
data:
location:
latitude: 32.87336
longitude: 117.22743
Extra data attributes support
...
action:
service: notify.NOTIFIER_NAME
data:
title: "*Send a message*"
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
Configuration Variables
True/false to send the message silently. iOS users and web users will not receive a notification. Android users will receive a notification with no sound.