jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-27 03:07:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add send_sticker and update the existing content (#4996)

Browse Source 
* Add send_sticker and update the existing content

* ✏️ Minor fixes
This commit is contained in:
Fabian Affolter 2018-03-23 20:07:18 +01:00 committed by Franck Nijhof
parent 62985bd21e
commit 6f63554f8c
1 changed files with 60 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
source/_components/telegram_bot.markdown
View File

@ -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. If you don't need to receive messages, you can use the [broadcast](/components/telegram_bot.broadcast/) platform instead.
### {% linkable_title Notification services %} ## {% linkable_title Notification services %}
Available services: `send_message`, `send_photo`, `send_document`, `send_location`, `edit_message`, `edit_replymarkup`, `edit_caption`, `answer_callback_query`.
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. Send a notification.
| Service data attribute | Optional | Description | | 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"]` | | `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"]]]` | | `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. Send a photo.
| Service data attribute | Optional | Description | | Service data attribute | Optional | Description |
@ -44,16 +47,16 @@ Send a photo.
| `url` | no | Remote path to an image. | | `url` | no | Remote path to an image. |
| `file` | no | Local path to an image. | | `file` | no | Local path to an image. |
| `caption` | yes | The title of the image. | | `caption` | yes | The title of the image. |
| `username` | yes | Username 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 require 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`. | | `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. | | `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. | | `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"]` | | `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"]]]` | | `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. Send a video.
| Service data attribute | Optional | Description | | 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"]` | | `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"]]]` | | `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. Send a document.
| Service data attribute | Optional | Description | | Service data attribute | Optional | Description |
@ -77,15 +81,16 @@ Send a document.
| `url` | no | Remote path to a document. | | `url` | no | Remote path to a document. |
| `file` | no | Local path to a document. | | `file` | no | Local path to a document. |
| `caption` | yes | The title of the document. | | `caption` | yes | The title of the document. |
| `username` | yes | Username 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 require 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`. | | `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. | | `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. | | `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"]` | | `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"]]]` | | `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. Send a location.
| Service data attribute | Optional | Description | | 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"]` | | `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"]]]` | | `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. Edit a previously sent message in a conversation.
| Service data attribute | Optional | Description | | 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. | | `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"]]]` | | `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. Edit the caption of a previously sent message.
| Service data attribute | Optional | Description | | 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. | | `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"]]]` | | `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` %} ### {% linkable_title Service `telegram_bot.edit_replymarkup` %}
Edit the inline keyboard of a previusly sent message.
Edit the inline keyboard of a previously sent message.
| Service data attribute | Optional | Description | | 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. | | `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"]]]` | | `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. 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 | | 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 }}` | | `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. | | `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. Delete a previously sent message in a conversation.
| Service data attribute | Optional | Description | | 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`. | | `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. | | `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: The required yaml configuration now reduces to:
```yaml ```yaml
notify: notify:
- name: NOTIFIER_NAME - name: NOTIFIER_NAME
@ -161,8 +170,7 @@ notify:
chat_id: USER_CHAT_ID chat_id: USER_CHAT_ID
``` ```
### {% linkable_title Event triggering %} ## {% linkable_title Event triggering %}
A command looks like `/thecommand`, or `/othercommand with some args`. A command looks like `/thecommand`, or `/othercommand with some args`.
@ -189,7 +197,7 @@ chat_id: "<origin chat id>"
chat: "<chat info>" 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 ```yaml
data: "<data associated to action callback>" data: "<data associated to action callback>"
@ -204,7 +212,6 @@ chat_id: "<origin chat id>"
### {% linkable_title Configuration samples %} ### {% linkable_title Configuration samples %}
Simple ping pong example. Simple ping pong example.
```yaml ```yaml
@ -221,7 +228,7 @@ action:
message: 'pong' message: 'pong'
``` ```
Example that show keyboard interaction with `notify.telegram` An example that shows keyboard interaction with `notify.telegram`
```yaml ```yaml
trigger: trigger:
@ -256,8 +263,9 @@ action:
entity_id: switch.vision_zm1601eu5_battery_operated_siren_switch_9_0 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 ```yaml
- alias: 'Kitchen Telegram Speak' - alias: 'Kitchen Telegram Speak'
trigger: trigger:
@ -269,17 +277,21 @@ An example to show the use of event_data in the action:
- service: notify.kitchen_echo - service: notify.kitchen_echo
data_template: data_template:
message: > 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 %} ### {% 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 'EDIT' changes the sent message.
- Pressing 'NO' only shows a brief notification (answering the callback query). - Pressing 'NO' only shows a brief notification (answering the callback query).
- Pressing 'REMOVE BUTTON' changes the inline keyboard removing that button. - Pressing 'REMOVE BUTTON' changes the inline keyboard removing that button.
Text repeater: Text repeater:
{% raw %}
```yaml ```yaml
- alias: 'Telegram bot that repeats text' - alias: 'Telegram bot that repeats text'
hide_entity: true hide_entity: true
@ -290,15 +302,18 @@ Text repeater:
- service: telegram_bot.send_message - service: telegram_bot.send_message
data_template: data_template:
title: '*Dumb automation*' title: '*Dumb automation*'
target: {% raw %}'{{ trigger.event.data.user_id }}'{% endraw %} target: '{{ trigger.event.data.user_id }}'
message: 'You said: {% raw %}{{ trigger.event.data.text }}{% endraw %}' message: 'You said: {{ trigger.event.data.text }}'
disable_notification: true disable_notification: true
inline_keyboard: inline_keyboard:
- "Edit message:/edit_msg, Don't:/do_nothing" - "Edit message:/edit_msg, Don't:/do_nothing"
- "Remove this button:/remove button" - "Remove this button:/remove button"
``` ```
{% endraw %}
Message editor: Message editor:
{% raw %}
```yaml ```yaml
- alias: 'Telegram bot that edits the last sent message' - alias: 'Telegram bot that edits the last sent message'
hide_entity: true hide_entity: true
@ -315,19 +330,22 @@ Message editor:
show_alert: true show_alert: true
- service: telegram_bot.edit_message - service: telegram_bot.edit_message
data_template: data_template:
message_id: {% raw %}'{{ trigger.event.data.message.message_id }}'{% endraw %} message_id: '{{ trigger.event.data.message.message_id }}'
chat_id: {% raw %}'{{ trigger.event.data.chat_id }}'{% endraw %} chat_id: '{{ trigger.event.data.chat_id }}'
title: '*Message edit*' title: '*Message edit*'
inline_keyboard: inline_keyboard:
- "Edit message:/edit_msg, Don't:/do_nothing" - "Edit message:/edit_msg, Don't:/do_nothing"
- "Remove this button:/remove button" - "Remove this button:/remove button"
message: > message: >
{% raw %}Callback received from {% raw %}{{ trigger.event.data.from_first }}{% endraw %}. Callback received from {{ trigger.event.data.from_first }}.
Message id: {% raw %}{{ trigger.event.data.message.message_id }}{% endraw %}. Message id: {{ trigger.event.data.message.message_id }}.
Data: {% raw %}{{ trigger.event.data.data }}{% endraw %} Data: {{ trigger.event.data.data }}
``` ```
{% endraw %}
Keyboard editor: Keyboard editor:
{% raw %}
```yaml ```yaml
- alias: 'Telegram bot that edits the keyboard' - alias: 'Telegram bot that edits the keyboard'
hide_entity: true hide_entity: true
@ -339,17 +357,20 @@ Keyboard editor:
action: action:
- service: telegram_bot.answer_callback_query - service: telegram_bot.answer_callback_query
data_template: 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!' message: 'Callback received for editing the inline keyboard!'
- service: telegram_bot.edit_replymarkup - service: telegram_bot.edit_replymarkup
data_template: data_template:
message_id: 'last' message_id: 'last'
chat_id: {% raw %}'{{ trigger.event.data.chat_id }}'{% endraw %} chat_id: '{{ trigger.event.data.chat_id }}'
inline_keyboard: inline_keyboard:
- "Edit message:/edit_msg, Don't:/do_nothing" - "Edit message:/edit_msg, Don't:/do_nothing"
``` ```
{% endraw %}
Only acknowledges the 'NO' answer: Only acknowledges the 'NO' answer:
{% raw %}
```yaml ```yaml
- alias: 'Telegram bot that simply acknowledges' - alias: 'Telegram bot that simply acknowledges'
hide_entity: true hide_entity: true
@ -361,9 +382,10 @@ Only acknowledges the 'NO' answer:
action: action:
- service: telegram_bot.answer_callback_query - service: telegram_bot.answer_callback_query
data_template: data_template:
callback_query_id: {% raw %}'{{ trigger.event.data.id }}'{% endraw %} callback_query_id: '{{ trigger.event.data.id }}'
message: 'OK, you said no!' message: 'OK, you said no!'
``` ```
{% endraw %}
For a more complex usage of the `telegram_bot` capabilities, using [AppDaemon](/docs/ecosystem/appdaemon/tutorial/) is advised. For a more complex usage of the `telegram_bot` capabilities, using [AppDaemon](/docs/ecosystem/appdaemon/tutorial/) is advised.