mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-24 09:46:59 +00:00
Update docs for telegram bot for new config flow (#39341)
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
hanwg
GitHub
parent
2d62b1eb54
commit
bf5a1cdff4
@ -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 %}
|
||||
|
||||
@ -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).
|
||||
@ -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).
|
||||
@ -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 -
|
||||
```
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user