Update docs for telegram bot for new config flow (#39341)

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
hanwg 2025-06-03 14:25:26 +08:00 committed by GitHub
parent 2d62b1eb54
commit bf5a1cdff4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 135 additions and 192 deletions

View File

@ -5,16 +5,112 @@ ha_category:
- Hub
ha_release: 0.42
ha_iot_class: Cloud Push
ha_config_flow: true
ha_domain: telegram_bot
ha_integration_type: integration
ha_quality_scale: legacy
---
Use Telegram on your mobile or desktop device to send and receive messages or commands to/from your Home Assistant.
This integration creates notification actions to send, edit or receive messages from a [Telegram Bot account](https://core.telegram.org/bots).
This integration creates notification actions to send, or edit previously sent, messages from a [Telegram Bot account](https://core.telegram.org/bots) configured either with the [polling](/integrations/telegram_polling) platform or with the [webhooks](/integrations/telegram_webhooks) one, and trigger events when receiving messages.
## Introduction - Telegram bot platforms
If you don't need to receive messages, you can use the [broadcast](/integrations/telegram_broadcast) platform instead.
Platforms are Telegram bot implementations for managing communications with Telegram for sending and receiving messages.
When setting up this integration, you should specify the platform which fits your environment and use case.
### Broadcast
Telegram implementation to support **sending messages only**. Your Home Assistant instance does not have to be exposed to the internet and there is no polling to receive messages or commands sent to the bot.
### Polling
Telegram chatbot polling implementation.
Your Home Assistant instance does not have to be exposed to the internet.
### Webhooks
Telegram chatbot webhooks implementation as described in the Telegram [documentation](https://core.telegram.org/bots/webhooks).
This implementation allows Telegram to push updates directly to your server and requires your Home Assistant instance to be exposed to the internet.
## Prerequisites
### Create Telegram bot
Create your Telegram bot and [retrieve the API key](/integrations/telegram). The `api_key` will be used for adding the bot to Home Assistant during integration setup.
### Allow Telegram to connect to your Home Assistant (Webhooks platform only)
If you plan to use the `Webhooks` platform, you will need to allow Telegram to connect to your Home Assistant using one of the following methods:
#### Home Assistant Cloud
If you have a Home Assistant Cloud subscription, you can [enable remote access](https://support.nabucasa.com/hc/en-us/articles/26474279202973-Enabling-remote-access-to-Home-Assistant#to-activate-remote-control-from-outside-your-network) to your Home Assistant.
#### Reverse proxy
If your Home Assistant is behind a publicly accessible reverse proxy (for example NGINX, Caddy, Traefik) with HTTPS enabled, do the following:
1. Go to {% my network title="**Settings** > **System** > **Network**" %} and configure *Home Assistant URL*.
2. Configure the [HTTP integration](/integrations/http) to allow Home Assistant to accept connections from your reverse proxy:
- Set `use_x_forwarded_for` to `true`.
- Add the IP address of the reverse proxy to `trusted_proxies`.
#### Direct
If your Home Assistant is publicly accessible, do the following:
1. Go to {% my network title="**Settings** > **System** > **Network**" %} and configure *Home Assistant URL*.
2. Configure the [HTTP integration](/integrations/http) to enable HTTPS on your Home Assistant by configuring the following variables:
- `server_host`
- `server_port`
- `ssl_certificate`
- `ssl_key`
{% include integrations/config_flow.md %}
{% configuration_basic %}
Platform:
description: The Telegram bot type, either `Broadcast`, `Polling` or `Webhooks`.
API key:
description: The API token of your bot.
Proxy URL:
description: Proxy URL if working behind one, optionally including username and password. (`socks5://username:password@proxy_ip:proxy_port`).
{% endconfiguration_basic %}
### Webhooks configuration
If you have selected the `Webhooks` Telegram bot type, the integration setup will continue with the webhooks configuration step.
{% configuration_basic %}
URL:
description: Allow to overwrite the external URL from the Home Assistant [configuration](/integrations/homeassistant/#editing-the-general-settings-in-yaml) for different setups (`https://<public_url>:<port>`).
Trusted networks:
description: Telegram server access ACL as list.
{% endconfiguration_basic %}
{% include integrations/option_flow.md %}
The integration can be configured to use a default parse mode for messages.
{% configuration_basic %}
Parse mode:
description: Default parser for messages if not explicit in message data, either `markdown` (legacy), `markdownv2` or `html`. Refer to Telegram's [formatting options](https://core.telegram.org/bots/api#formatting-options) for more information.
{% endconfiguration_basic %}
## Allowlisting chat IDs via Subentries
A Telegram chat ID is a unique numerical identifier for an individual user (positive) or a chat group (negative).
You must allowlist the chat ID for the Telegram bot before it can send/receive messages for that chat.
To allowlist the chat ID, [retrieve the chat ID](/integrations/telegram#methods-to-retrieve-a-chat_id) and create a subentry:
1. Go to **{% my integrations title="Settings > Devices & services" %}**.
2. Select the Telegram bot integration.
3. Next to the entry, select the three-dot {% icon "mdi:dots-vertical" %} menu. Then, select **Add allowed chat ID**.
{% configuration_basic %}
Chat ID:
description: ID representing the user or group chat to which messages can be sent.
{% endconfiguration_basic %}
## Notification actions
@ -28,6 +124,7 @@ Send a notification.
| Data attribute | Optional | Description |
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to send the message. Required if you have multiple Telegram bots.|
| `message` | no | Message body of the notification. |
| `title` | yes | Optional title for your notification. Will be composed as '%title\n%message'. |
| `target` | yes | An array of pre-authorized chat_ids or user_ids to send the notification to. Defaults to the first allowed chat_id. |
@ -40,7 +137,7 @@ Send a notification.
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data or external URL (https-only). Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Google link", "https://google.com"]]]` |
| `message_tag` | yes | Tag for sent message. In `telegram_sent` event data: {% raw %}`{{trigger.event.data.message_tag}}`{% endraw %} |
| `reply_to_message_id` | yes | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %} |
| `message_thread_id` | yes | Send the message to a specific topic or thread.
| `message_thread_id` | yes | Send the message to a specific topic or thread.|
### Action `telegram_bot.send_photo`
@ -48,6 +145,7 @@ Send a photo.
| Data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to send the photo. Required if you have multiple Telegram bots.|
| `url` | no | Remote path to an image. |
| `file` | no | Local path to an image. |
| `caption` | yes | The title of the image. |
@ -65,7 +163,7 @@ Send a photo.
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data or external URL (https-only). Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Google link", "https://google.com"]]]` |
| `message_tag` | yes | Tag for sent message. In `telegram_sent` event data: {% raw %}`{{trigger.event.data.message_tag}}`{% endraw %} |
| `reply_to_message_id` | yes | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %} |
| `message_thread_id` | yes | Send the message to a specific topic or thread.
| `message_thread_id` | yes | Send the message to a specific topic or thread.|
### Action `telegram_bot.send_video`
@ -73,6 +171,7 @@ Send a video.
| Data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to send the video. Required if you have multiple Telegram bots.|
| `url` | no | Remote path to a video. |
| `file` | no | Local path to a video. |
| `caption` | yes | The title of the video. |
@ -89,7 +188,7 @@ Send a video.
| `keyboard` | yes | List of rows of commands, comma-separated, to make a custom keyboard. `[]` to reset to no custom keyboard. Example: `["/command1, /command2", "/command3"]` |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data or external URL (https-only). Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Google link", "https://google.com"]]]` |
| `reply_to_message_id` | yes | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %} |
| `message_thread_id` | yes | Send the message to a specific topic or thread.
| `message_thread_id` | yes | Send the message to a specific topic or thread.|
### Action `telegram_bot.send_animation`
@ -97,6 +196,7 @@ Send an animation.
| Data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to send the animation. Required if you have multiple Telegram bots.|
| `url` | no | Remote path to a GIF or H.264/MPEG-4 AVC video without sound. |
| `file` | no | Local path to a GIF or H.264/MPEG-4 AVC video without sound. |
| `caption` | yes | The title of the animation. |
@ -114,7 +214,7 @@ Send an animation.
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data or external URL (https-only). Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Google link", "https://google.com"]]]` |
| `message_tag` | yes | Tag for sent message. In `telegram_sent` event data: {% raw %}`{{trigger.event.data.message_tag}}`{% endraw %} |
| `reply_to_message_id` | yes | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %} |
| `message_thread_id` | yes | Send the message to a specific topic or thread.
| `message_thread_id` | yes | Send the message to a specific topic or thread.|
### Action `telegram_bot.send_voice`
@ -122,6 +222,7 @@ Send a voice message.
| Data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to send the voice message. Required if you have multiple Telegram bots.|
| `url` | no | Remote path to a voice message. |
| `file` | no | Local path to a voice message. |
| `caption` | yes | The title of the voice message. |
@ -138,7 +239,7 @@ Send a voice message.
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data or external URL (https-only). Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Google link", "https://google.com"]]]` |
| `message_tag` | yes | Tag for sent message. In `telegram_sent` event data: {% raw %}`{{trigger.event.data.message_tag}}`{% endraw %} |
| `reply_to_message_id` | yes | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %} |
| `message_thread_id` | yes | Send the message to a specific topic or thread.
| `message_thread_id` | yes | Send the message to a specific topic or thread.|
### Action `telegram_bot.send_sticker`
@ -146,6 +247,7 @@ Send a sticker.
| Data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to send the sticker. Required if you have multiple Telegram bots.|
| `url` | no | Remote path to a static .webp or animated .tgs sticker. |
| `file` | no | Local path to a static .webp or animated .tgs sticker. |
| `sticker_id` | no | ID of a sticker that exists on telegram servers. The ID can be found by sending a sticker to your bot and querying the telegram-api method [getUpdates](https://core.telegram.org/bots/api#getting-updates) or by using the [@idstickerbot](https://t.me/idstickerbot) |
@ -162,7 +264,7 @@ Send a sticker.
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data or external URL (https-only). Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Google link", "https://google.com"]]]` |
| `message_tag` | yes | Tag for sent message. In `telegram_sent` event data: {% raw %}`{{trigger.event.data.message_tag}}`{% endraw %} |
| `reply_to_message_id` | yes | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %} |
| `message_thread_id` | yes | Send the message to a specific topic or thread.
| `message_thread_id` | yes | Send the message to a specific topic or thread.|
### Action `telegram_bot.send_document`
@ -170,6 +272,7 @@ Send a document.
| Data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to send the document. Required if you have multiple Telegram bots.|
| `url` | no | Remote path to a document. |
| `file` | no | Local path to a document. |
| `caption` | yes | The title of the document. |
@ -187,7 +290,7 @@ Send a document.
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data or external URL (https-only). Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Google link", "https://google.com"]]]` |
| `message_tag` | yes | Tag for sent message. In `telegram_sent` event data: {% raw %}`{{trigger.event.data.message_tag}}`{% endraw %} |
| `reply_to_message_id` | yes | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %} |
| `message_thread_id` | yes | Send the message to a specific topic or thread.
| `message_thread_id` | yes | Send the message to a specific topic or thread.|
### Action `telegram_bot.send_location`
@ -195,6 +298,7 @@ Send a location.
| Data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to send the location. Required if you have multiple Telegram bots.|
| `latitude` | no | The latitude to send. |
| `longitude` | no | The longitude to send. |
| `target` | yes | An array of pre-authorized chat_ids or user_ids to send the notification to. Defaults to the first allowed `chat_id`. |
@ -205,7 +309,7 @@ Send a location.
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data or external URL (https-only). Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Google link", "https://google.com"]]]` |
| `message_tag` | yes | Tag for sent message. In `telegram_sent` event data: {% raw %}`{{trigger.event.data.message_tag}}`{% endraw %} |
| `reply_to_message_id` | yes | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %} |
| `message_thread_id` | yes | Send the message to a specific topic or thread.
| `message_thread_id` | yes | Send the message to a specific topic or thread.|
### Action `telegram_bot.send_poll`
@ -213,6 +317,7 @@ Send a poll.
| Data attribute | Optional | Description |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `config_entry_id` | yes | The config entry representing the Telegram bot to send the poll. Required if you have multiple Telegram bots.|
| `question` | no | Poll question, 1-300 characters. |
| `options` | no | List of answer options, 2-10 strings 1-100 characters each. |
| `target` | yes | An array of pre-authorized chat_ids or user_ids to send the notification to. Defaults to the first allowed `chat_id`. |
@ -222,7 +327,7 @@ Send a poll.
| `disable_notification` | yes | True/false for send the message silently. iOS users and web users will not receive a notification, Android users will receive a notification with no sound. Defaults to False. |
| `timeout` | yes | Timeout for sending voice in seconds. Will help with timeout errors (poor internet connection, etc) |
| `reply_to_message_id` | yes | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %} |
| `message_thread_id` | yes | Send the message to a specific topic or thread.
| `message_thread_id` | yes | Send the message to a specific topic or thread.|
### Action `telegram_bot.edit_message`
@ -230,6 +335,7 @@ Edit a previously sent message in a conversation.
| Data attribute | Optional | Description |
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to edit the message. Required if you have multiple Telegram bots.|
| `message_id` | no | Id of the message to edit. When answering a callback from a pressed button, the id of the origin message is in: {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}. You can use `"last"` to refer to the last message sent to `chat_id`. |
| `chat_id` | no | The chat_id where to edit the message. |
| `message` | no | Message body of the notification. |
@ -244,6 +350,7 @@ Edit the caption of a previously sent message.
| Data attribute | Optional | Description |
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to edit the caption. Required if you have multiple Telegram bots.|
| `message_id` | no | Id of the message to edit. When answering a callback from a pressed button, the id of the origin message is in: {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}. You can use `"last"` to refer to the last message sent to `chat_id`. |
| `chat_id` | no | The chat_id where to edit the caption. |
| `caption` | no | Message body of the notification. |
@ -256,6 +363,7 @@ Edit the inline keyboard of a previously sent message.
| Data attribute | Optional | Description |
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to edit the inline keyboard. Required if you have multiple Telegram bots.|
| `message_id` | no | Id of the message to edit. When answering a callback from a pressed button, the id of the origin message is in: {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}. You can use `"last"` to refer to the last message sent to `chat_id`. |
| `chat_id` | no | The chat_id where to edit the reply_markup. |
| `disable_web_page_preview` | yes | True/false for disable link previews for links in the message. |
@ -267,6 +375,7 @@ Respond to a callback query originated by clicking on an online keyboard button.
| Data attribute | Optional | Description |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to answer the callback query. Required if you have multiple Telegram bots.|
| `message` | no | Unformatted text message body of the notification. |
| `callback_query_id` | no | Unique id of the callback response. In the `telegram_callback` event data: {% raw %}`{{ trigger.event.data.id }}`{% endraw %} |
| `show_alert` | yes | True/false for show a permanent notification. Defaults to False. |
@ -277,6 +386,7 @@ Delete a previously sent message in a conversation.
| Data attribute | Optional | Description |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to delete the message. Required if you have multiple Telegram bots.|
| `message_id` | no | Id of the message to delete. When answering a callback from a pressed button, the id of the origin message is in: {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}. You can use `"last"` to refer to the last message sent to `chat_id`. |
| `chat_id` | no | The chat_id where to delete the message. |
@ -286,6 +396,7 @@ Remove the bot from the chat group where it was added.
| Data attribute | Optional | Description |
| ---------------------- | -------- | ----------------------------------------- |
| `config_entry_id` | yes | The config entry representing the Telegram bot to leave the chat. Required if you have multiple Telegram bots.|
| `chat_id` | no | The chat_id from where to remove the bot. |
## Telegram notification platform
@ -645,3 +756,9 @@ sequence:
```
{% endraw %}
## Removing the integration
This integration follows standard integration removal. No extra steps are required.
{% include integrations/remove_device_service.md %}

View File

@ -1,48 +0,0 @@
---
title: "Telegram broadcast"
description: "Telegram support to send messages only"
ha_category:
- Notifications
ha_release: 0.48
ha_domain: telegram_bot
---
Telegram implementation to support **sending messages only**. Your Home Assistant instance does not have to be exposed to the internet and there is no polling to receive messages or commands sent to the bot.
Information on how to send a message via the `telegram_bot.send_message` action can be found [here](/integrations/telegram_bot/#action-telegram_botsend_message).
## Configuration
To integrate this into Home Assistant, add the following section to your {% term "`configuration.yaml`" %} file:
```yaml
# Example configuration.yaml entry
telegram_bot:
- platform: broadcast
api_key: YOUR_API_KEY
allowed_chat_ids:
- 123456789 # example id of a user
- -987654321 # example id of a group, starts with a -
```
{% configuration %}
allowed_chat_ids:
description: A list of ids representing the users and group chats to which messages can be send. Default the message will be send to the first alllowed chat_id. By using the `target` action data attribute the message can be send to other chat_ids from the list.
required: true
type: list
api_key:
description: The API token of your bot.
required: true
type: string
parse_mode:
description: Default parser for messages if not explicit in message data, either `html` or `markdown`.
required: false
type: string
default: "`markdown`"
proxy_url:
description: Proxy URL if working behind one, optionally including username and password. (`socks5://username:password@proxy_ip:proxy_port`).
required: false
type: string
{% endconfiguration %}
To get your `chat_id` and `api_key` follow the instructions [here](/integrations/telegram).

View File

@ -1,50 +0,0 @@
---
title: "Telegram polling"
description: "Telegram polling support"
ha_category:
- Notifications
ha_release: 0.42
ha_iot_class: Cloud Polling
ha_domain: telegram_bot
---
Telegram chatbot polling implementation.
This is one of two bot implementations supported by Telegram. Your Home Assistant instance does not have to be exposed to the internet.
The other implementation method is [Telegram webhooks](/integrations/telegram_webhooks/), described by Telegram as the preferred implementation but requires your Home Assistant instance to be exposed to the internet.
## Configuration
To integrate this into Home Assistant, add the following section to your {% term "`configuration.yaml`" %} file:
```yaml
# Example configuration.yaml entry
telegram_bot:
- platform: polling
api_key: YOUR_API_KEY
allowed_chat_ids:
- 123456789 # example id of a user
- -987654321 # example id of a group, starts with a -
```
{% configuration %}
allowed_chat_ids:
description: A list of ids representing the users and group chats that are authorized to interact with the bot.
required: true
type: list
api_key:
description: The API token of your bot.
required: true
type: string
parse_mode:
description: Default parser for messages if not explicit in message data, either `html` or `markdown`.
required: false
type: string
default: "`markdown`"
proxy_url:
description: Proxy URL if working behind one, optionally including username and password. (`socks5://username:password@proxy_ip:proxy_port`).
required: false
type: string
{% endconfiguration %}
To get your `chat_id` and `api_key` follow the instructions [here](/integrations/telegram).

View File

@ -1,79 +0,0 @@
---
title: "Telegram webhooks"
description: "Telegram webhooks support"
ha_category:
- Notifications
ha_release: 0.42
ha_iot_class: Cloud Push
ha_domain: telegram_bot
---
Telegram chatbot webhooks implementation as described in the Telegram [documentation](https://core.telegram.org/bots/webhooks).
By default this integration sets your bot's webhook URL automatically to `https://<external_url>/api/telegram_webhooks` with the external_url of your Home Assistant [configuration](/integrations/homeassistant/#external_url) using Telegrams `setWebhook` method.
This is one of two bot implementations supported by Telegram. Described by Telegram as the preferred implementation but requires your Home Assistant instance to be exposed to the internet.
The other implementation method is [Telegram polling](/integrations/telegram_polling/), for which your Home Assistant instance does not have to be exposed to the internet.
## Configuration
To integrate this into Home Assistant, add the following section to your {% term "`configuration.yaml`" %} file:
```yaml
# Example configuration.yaml entry
telegram_bot:
- platform: webhooks
api_key: YOUR_API_KEY
allowed_chat_ids:
- 123456789 # example id of a user
- -987654321 # example id of a group, starts with a -
```
{% configuration %}
allowed_chat_ids:
description: A list of ids representing the users and group chats that are authorized to interact with the bot.
required: true
type: list
api_key:
description: The API token of your bot.
required: true
type: string
parse_mode:
description: Default parser for messages if not explicit in message data, either `html` or `markdown`.
required: false
default: "`markdown`"
type: string
proxy_url:
description: Proxy URL if working behind one, optionally including username and password. (`socks5://username:password@proxy_ip:proxy_port`).
required: false
type: string
url:
description: Allow to overwrite the external URL from the Home Assistant [configuration](/integrations/homeassistant/#editing-the-general-settings-in-yaml) for different setups (`https://<public_url>:<port>`).
required: false
type: string
trusted_networks:
description: Telegram server access ACL as list.
required: false
type: string
default: 149.154.160.0/20, 91.108.4.0/22
{% endconfiguration %}
To get your `chat_id` and `api_key` follow the instructions [here](/integrations/telegram). As well as authorizing the chat, if you have added your bot to a group you will also need to authorize any user that will be interacting with the webhook. When an unauthorized user tries to interact with the webhook Home Assistant will raise an error ("Incoming message is not allowed"), you can easily obtain the users id by looking in the "from" section of this error message.
## Full configuration example
The configuration sample below shows how an entry can look like:
```yaml
# Example configuration.yaml entry
telegram_bot:
- platform: webhooks
api_key: YOUR_API_KEY
parse_mode: html
trusted_networks:
- 149.154.160.0/20
- 91.108.4.0/22
allowed_chat_ids:
- 123456789 # example id of a user
- -987654321 # example id of a group, starts with a -
```

View File

@ -152,9 +152,9 @@ layout: null
/components/switch.mysensors /integrations/mysensors#switch
/components/switch.rest /integrations/switch.rest
/components/switch.template /integrations/switch.template
/components/telegram_bot.broadcast /integrations/telegram_broadcast
/components/telegram_bot.polling /integrations/telegram_polling
/components/telegram_bot.webhooks /integrations/telegram_webhooks
/components/telegram_bot.broadcast /integrations/telegram_bot
/components/telegram_bot.polling /integrations/telegram_bot
/components/telegram_bot.webhooks /integrations/telegram_bot
/components/vacuum.mqtt /integrations/vacuum.mqtt
/components/vacuum.template /integrations/vacuum.template
/integrations/binary_sensor.group /integrations/group
@ -207,6 +207,9 @@ layout: null
/integrations/switch.xiaomi_aqara/ /integrations/xiaomi_aqara/#switches
/integrations/switch.pca /integrations/elv/
/integrations/switch.xiaomi_miio /integrations/xiaomi_miio/#xiaomi-smart-wifi-socket-and-smart-power-strip
/integrations/telegram_broadcast /integrations/telegram_bot
/integrations/telegram_polling /integrations/telegram_bot
/integrations/telegram_webhooks /integrations/telegram_bot
/integrations/vacuum.xiaomi_miio /integrations/xiaomi_miio/#xiaomi-mi-robot-vacuum
/components/air_pollutants.* /integrations/:splat