mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-23 01:06:52 +00:00
Add send_sticker and update the existing content (#4996)
* Add send_sticker and update the existing content
* ✏️ Minor fixes
This commit is contained in:
parent
62985bd21e
commit
6f63554f8c
@ -19,10 +19,12 @@ This component creates notification services to send, or edit previously sent, m
|
||||
|
||||
If you don't need to receive messages, you can use the [broadcast](/components/telegram_bot.broadcast/) platform instead.
|
||||
|
||||
### {% linkable_title Notification services %}
|
||||
Available services: `send_message`, `send_photo`, `send_document`, `send_location`, `edit_message`, `edit_replymarkup`, `edit_caption`, `answer_callback_query`.
|
||||
## {% linkable_title Notification services %}
|
||||
|
||||
Available services: `send_message`, `send_photo`, `send_document`, `send_location`, `send_sticker`, `edit_message`, `edit_replymarkup`, `edit_caption` and `answer_callback_query`.
|
||||
|
||||
### {% linkable_title Service `telegram_bot.send_message` %}
|
||||
|
||||
#### {% linkable_title Service `telegram_bot/send_message` %}
|
||||
Send a notification.
|
||||
|
||||
| Service data attribute | Optional | Description |
|
||||
@ -36,7 +38,8 @@ Send a notification.
|
||||
| `keyboard` | yes | List of rows of commands, comma-separated, to make a 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. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
|
||||
|
||||
#### {% linkable_title Service `telegram_bot/send_photo` %}
|
||||
### {% linkable_title Service `telegram_bot.send_photo` and `telegram_bot.send_sticker` %}
|
||||
|
||||
Send a photo.
|
||||
|
||||
| Service data attribute | Optional | Description |
|
||||
@ -44,16 +47,16 @@ Send a photo.
|
||||
| `url` | no | Remote path to an image. |
|
||||
| `file` | no | Local path to an image. |
|
||||
| `caption` | yes | The title of the image. |
|
||||
| `username` | yes | Username for a URL which require HTTP basic authentication. |
|
||||
| `password` | yes | Password for a URL which require HTTP basic authentication. |
|
||||
| `username` | yes | Username for a URL which requires HTTP basic authentication. |
|
||||
| `password` | yes | Password for a URL which requires HTTP basic authentication. |
|
||||
| `authentication` | yes | Define which authentication method to use. Set to `digest` to use HTTP digest authentication. Defaults to `basic`. |
|
||||
| `target` | yes | An array of pre-authorized chat_ids or user_ids to send the notification to. Defaults to the first allowed chat_id. |
|
||||
| `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. |
|
||||
| `keyboard` | yes | List of rows of commands, comma-separated, to make a 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. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
|
||||
|
||||
### {% linkable_title Service `telegram_bot.send_video` %}
|
||||
|
||||
#### {% linkable_title Service `telegram_bot/send_video` %}
|
||||
Send a video.
|
||||
|
||||
| Service data attribute | Optional | Description |
|
||||
@ -69,7 +72,8 @@ Send a video.
|
||||
| `keyboard` | yes | List of rows of commands, comma-separated, to make a 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. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
|
||||
|
||||
#### {% linkable_title Service `telegram_bot/send_document` %}
|
||||
### {% linkable_title Service `telegram_bot.send_document` %}
|
||||
|
||||
Send a document.
|
||||
|
||||
| Service data attribute | Optional | Description |
|
||||
@ -77,15 +81,16 @@ Send a document.
|
||||
| `url` | no | Remote path to a document. |
|
||||
| `file` | no | Local path to a document. |
|
||||
| `caption` | yes | The title of the document. |
|
||||
| `username` | yes | Username for a URL which require HTTP basic authentication. |
|
||||
| `password` | yes | Password for a URL which require HTTP basic authentication. |
|
||||
| `username` | yes | Username for a URL which requires HTTP basic authentication. |
|
||||
| `password` | yes | Password for a URL which requires HTTP basic authentication. |
|
||||
| `authentication` | yes | Define which authentication method to use. Set to `digest` to use HTTP digest authentication. Defaults to `basic`. |
|
||||
| `target` | yes | An array of pre-authorized chat_ids or user_ids to send the notification to. Defaults to the first allowed chat_id. |
|
||||
| `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. |
|
||||
| `keyboard` | yes | List of rows of commands, comma-separated, to make a 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. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
|
||||
|
||||
#### {% linkable_title Service `telegram_bot/send_location` %}
|
||||
### {% linkable_title Service `telegram_bot.send_location` %}
|
||||
|
||||
Send a location.
|
||||
|
||||
| Service data attribute | Optional | Description |
|
||||
@ -97,7 +102,8 @@ Send a location.
|
||||
| `keyboard` | yes | List of rows of commands, comma-separated, to make a 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. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
|
||||
|
||||
#### {% linkable_title Service `telegram_bot/edit_message` %}
|
||||
### {% linkable_title Service `telegram_bot.edit_message` %}
|
||||
|
||||
Edit a previously sent message in a conversation.
|
||||
|
||||
| Service data attribute | Optional | Description |
|
||||
@ -110,7 +116,8 @@ Edit a previously sent message in a conversation.
|
||||
| `disable_web_page_preview`| yes | True/false for disable link previews for links in the message. |
|
||||
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
|
||||
|
||||
#### {% linkable_title Service `telegram_bot/edit_caption` %}
|
||||
### {% linkable_title Service `telegram_bot.edit_caption` %}
|
||||
|
||||
Edit the caption of a previously sent message.
|
||||
|
||||
| Service data attribute | Optional | Description |
|
||||
@ -121,8 +128,9 @@ Edit the caption of a previously sent message.
|
||||
| `disable_web_page_preview`| yes | True/false for disable link previews for links in the message. |
|
||||
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
|
||||
|
||||
#### {% linkable_title Service `telegram_bot/edit_replymarkup` %}
|
||||
Edit the inline keyboard of a previusly sent message.
|
||||
### {% linkable_title Service `telegram_bot.edit_replymarkup` %}
|
||||
|
||||
Edit the inline keyboard of a previously sent message.
|
||||
|
||||
| Service data attribute | Optional | Description |
|
||||
|---------------------------|----------|--------------------------------------------------|
|
||||
@ -131,7 +139,8 @@ Edit the inline keyboard of a previusly sent message.
|
||||
| `disable_web_page_preview`| yes | True/false for disable link previews for links in the message. |
|
||||
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
|
||||
|
||||
#### {% linkable_title Service `telegram_bot/answer_callback_query` %}
|
||||
### {% linkable_title Service `telegram_bot.answer_callback_query` %}
|
||||
|
||||
Respond to a callback query originated by clicking on an online keyboard button. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert.
|
||||
|
||||
| Service data attribute | Optional | Description |
|
||||
@ -140,7 +149,7 @@ Respond to a callback query originated by clicking on an online keyboard button.
|
||||
| `callback_query_id` | no | Unique id of the callback response. In the `telegram_callback` event data: `{{ trigger.event.data.id }}` |
|
||||
| `show_alert` | yes | True/false for show a permanent notification. Defaults to False. |
|
||||
|
||||
#### {% linkable_title Service `telegram_bot/delete_message` %}
|
||||
### {% linkable_title Service `telegram_bot.delete_message` %}
|
||||
Delete a previously sent message in a conversation.
|
||||
|
||||
| Service data attribute | Optional | Description |
|
||||
@ -148,12 +157,12 @@ Delete a previously sent message in a conversation.
|
||||
| `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: `{{ trigger.event.data.message.message_id }}`. 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. |
|
||||
|
||||
### {% linkable_title `Telegram` notification platform %}
|
||||
## {% linkable_title `telegram` notification platform %}
|
||||
|
||||
|
||||
The [Telegram notification platform](/components/notify.telegram/) requires the `telegram_bot` component to work with, and it's designed to generate a customized shortcut (`notify.USERNAME`) to send notifications (messages, photos, documents and locations) to a particular `chat_id` with the old syntax, allowing backward compatibility.
|
||||
The [`telegram` notification platform](/components/notify.telegram/) requires the `telegram_bot` component to work with, and it's designed to generate a customized shortcut (`notify.USERNAME`) to send notifications (messages, photos, documents and locations) to a particular `chat_id` with the old syntax, allowing backward compatibility.
|
||||
|
||||
The required yaml configuration now reduces to:
|
||||
|
||||
```yaml
|
||||
notify:
|
||||
- name: NOTIFIER_NAME
|
||||
@ -161,8 +170,7 @@ notify:
|
||||
chat_id: USER_CHAT_ID
|
||||
```
|
||||
|
||||
### {% linkable_title Event triggering %}
|
||||
|
||||
## {% linkable_title Event triggering %}
|
||||
|
||||
A command looks like `/thecommand`, or `/othercommand with some args`.
|
||||
|
||||
@ -189,7 +197,7 @@ chat_id: "<origin chat id>"
|
||||
chat: "<chat info>"
|
||||
```
|
||||
|
||||
if the message is sent from a [press from an inline button](https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating), for example, a callback query is received, and Home Assistant will fire a `telegram_callback` event with:
|
||||
If the message is sent from a [press from an inline button](https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating), for example, a callback query is received, and Home Assistant will fire a `telegram_callback` event with:
|
||||
|
||||
```yaml
|
||||
data: "<data associated to action callback>"
|
||||
@ -204,7 +212,6 @@ chat_id: "<origin chat id>"
|
||||
|
||||
### {% linkable_title Configuration samples %}
|
||||
|
||||
|
||||
Simple ping pong example.
|
||||
|
||||
```yaml
|
||||
@ -221,7 +228,7 @@ action:
|
||||
message: 'pong'
|
||||
```
|
||||
|
||||
Example that show keyboard interaction with `notify.telegram`
|
||||
An example that shows keyboard interaction with `notify.telegram`
|
||||
|
||||
```yaml
|
||||
trigger:
|
||||
@ -256,8 +263,9 @@ action:
|
||||
entity_id: switch.vision_zm1601eu5_battery_operated_siren_switch_9_0
|
||||
```
|
||||
|
||||
An example to show the use of event_data in the action:
|
||||
An example to show the use of event_data in action:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- alias: 'Kitchen Telegram Speak'
|
||||
trigger:
|
||||
@ -269,17 +277,21 @@ An example to show the use of event_data in the action:
|
||||
- service: notify.kitchen_echo
|
||||
data_template:
|
||||
message: >
|
||||
Message from {% raw %}{{ trigger.event.data["from_first"] }}. {% for state in trigger.event.data["args"] %} {{ state }} {% endfor %}{% endraw %}
|
||||
Message from {{ trigger.event.data["from_first"] }}. {% for state in trigger.event.data["args"] %} {{ state }} {% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Sample automations with callback queries and inline keyboards %}
|
||||
|
||||
Quick example to show some of the callback capabilities of inline keyboards with a dumb automation consisting in a simple repeater of normal text that presents an inline keyboard with 3 buttons: 'EDIT', 'NO' and 'REMOVE BUTTON':
|
||||
A quick example to show some of the callback capabilities of inline keyboards with a dumb automation consisting in a simple repeater of normal text that presents an inline keyboard with 3 buttons: 'EDIT', 'NO' and 'REMOVE BUTTON':
|
||||
|
||||
- Pressing 'EDIT' changes the sent message.
|
||||
- Pressing 'NO' only shows a brief notification (answering the callback query).
|
||||
- Pressing 'REMOVE BUTTON' changes the inline keyboard removing that button.
|
||||
|
||||
Text repeater:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- alias: 'Telegram bot that repeats text'
|
||||
hide_entity: true
|
||||
@ -290,15 +302,18 @@ Text repeater:
|
||||
- service: telegram_bot.send_message
|
||||
data_template:
|
||||
title: '*Dumb automation*'
|
||||
target: {% raw %}'{{ trigger.event.data.user_id }}'{% endraw %}
|
||||
message: 'You said: {% raw %}{{ trigger.event.data.text }}{% endraw %}'
|
||||
target: '{{ trigger.event.data.user_id }}'
|
||||
message: 'You said: {{ trigger.event.data.text }}'
|
||||
disable_notification: true
|
||||
inline_keyboard:
|
||||
- "Edit message:/edit_msg, Don't:/do_nothing"
|
||||
- "Remove this button:/remove button"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Message editor:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- alias: 'Telegram bot that edits the last sent message'
|
||||
hide_entity: true
|
||||
@ -315,19 +330,22 @@ Message editor:
|
||||
show_alert: true
|
||||
- service: telegram_bot.edit_message
|
||||
data_template:
|
||||
message_id: {% raw %}'{{ trigger.event.data.message.message_id }}'{% endraw %}
|
||||
chat_id: {% raw %}'{{ trigger.event.data.chat_id }}'{% endraw %}
|
||||
message_id: '{{ trigger.event.data.message.message_id }}'
|
||||
chat_id: '{{ trigger.event.data.chat_id }}'
|
||||
title: '*Message edit*'
|
||||
inline_keyboard:
|
||||
- "Edit message:/edit_msg, Don't:/do_nothing"
|
||||
- "Remove this button:/remove button"
|
||||
message: >
|
||||
{% raw %}Callback received from {% raw %}{{ trigger.event.data.from_first }}{% endraw %}.
|
||||
Message id: {% raw %}{{ trigger.event.data.message.message_id }}{% endraw %}.
|
||||
Data: {% raw %}{{ trigger.event.data.data }}{% endraw %}
|
||||
Callback received from {{ trigger.event.data.from_first }}.
|
||||
Message id: {{ trigger.event.data.message.message_id }}.
|
||||
Data: {{ trigger.event.data.data }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Keyboard editor:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- alias: 'Telegram bot that edits the keyboard'
|
||||
hide_entity: true
|
||||
@ -339,17 +357,20 @@ Keyboard editor:
|
||||
action:
|
||||
- service: telegram_bot.answer_callback_query
|
||||
data_template:
|
||||
callback_query_id: {% raw %}'{{ trigger.event.data.id }}'{% endraw %}
|
||||
callback_query_id: '{{ trigger.event.data.id }}'
|
||||
message: 'Callback received for editing the inline keyboard!'
|
||||
- service: telegram_bot.edit_replymarkup
|
||||
data_template:
|
||||
message_id: 'last'
|
||||
chat_id: {% raw %}'{{ trigger.event.data.chat_id }}'{% endraw %}
|
||||
chat_id: '{{ trigger.event.data.chat_id }}'
|
||||
inline_keyboard:
|
||||
- "Edit message:/edit_msg, Don't:/do_nothing"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Only acknowledges the 'NO' answer:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- alias: 'Telegram bot that simply acknowledges'
|
||||
hide_entity: true
|
||||
@ -361,9 +382,10 @@ Only acknowledges the 'NO' answer:
|
||||
action:
|
||||
- service: telegram_bot.answer_callback_query
|
||||
data_template:
|
||||
callback_query_id: {% raw %}'{{ trigger.event.data.id }}'{% endraw %}
|
||||
callback_query_id: '{{ trigger.event.data.id }}'
|
||||
message: 'OK, you said no!'
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
For a more complex usage of the `telegram_bot` capabilities, using [AppDaemon](/docs/ecosystem/appdaemon/tutorial/) is advised.
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user