Telegram: add more detailed procedure (#27826)

Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
c0ffeeca7 2023-06-14 21:43:49 +02:00 committed by GitHub
parent 8fee1fa0a1
commit 48863bc00a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -11,15 +11,65 @@ ha_platforms:
ha_integration_type: integration
---
The `telegram` platform uses [Telegram](https://www.telegram.org) to deliver notifications from Home Assistant to your Telegram application(s).
The `telegram` integration uses [Telegram](https://www.telegram.org) to deliver notifications from Home Assistant to your Telegram application(s).
## Setup
## Setup example
The requirements are:
To create your first [Telegram bot](https://core.telegram.org/bots#how-do-i-create-a-bot), follow these steps:
- You need a [Telegram bot](https://core.telegram.org/bots). Please follow those [instructions](https://core.telegram.org/bots#how-do-i-create-a-bot) 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](/integrations/telegram_bot) and define there your API key and the allowed chat ids to interact with.
- The `chat_id` of an allowed user or group to which the bot is added.
* 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.
1. To get a chat ID, send any message to the [GetIDs bot](https://t.me/getidsbot).
* Then, enter `/start`.
* The bot will return your chat ID and the user name.
1. Create a [Telegram bot in Home Assistant](/integrations/telegram_bot):
* Paste this into your configuration file:
* Replace the `api_key` and the `allowed_chat_ids` with your data.
```yaml
# Telegram Bot
telegram_bot:
- platform: polling
api_key: "1117774004:EABQulCACdgkQOTN3hS_5HZwSwxDlekCixr"
allowed_chat_ids:
- 44441111
```
1. Create a notifier:
* Paste this into your configuration file:
* Replace the `name` and the `chat_id` with your data.
```yaml
# Notifier
notify:
- platform: telegram
name: "sarah"
chat_id: 44441111
```
1. From the conversation with BotFather, select the link to open a chat with your new bot.
1. In the chat with the new bot, enter `/start`.
1. Test the service:
* Go to [**Developer tools** > **Services** > **YAML mode**](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.turn_on).
* Paste this into the YAML file:
* Replace the `service` and the `message` with your data.
```yaml
service: notify.sarah
data:
message: "Yay! A message from Home Assistant."
```
* Select **Call service**. You should now get a message.
1. 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](https://t.me/getidsbot).