From 6f63554f8cba39e7887504c5563c622728e77668 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Fri, 23 Mar 2018 20:07:18 +0100 Subject: [PATCH] Add send_sticker and update the existing content (#4996) * Add send_sticker and update the existing content * :pencil2: Minor fixes --- source/_components/telegram_bot.markdown | 98 +++++++++++++++--------- 1 file changed, 60 insertions(+), 38 deletions(-) diff --git a/source/_components/telegram_bot.markdown b/source/_components/telegram_bot.markdown index 0c5ef3e5026..32397d0fbee 100644 --- a/source/_components/telegram_bot.markdown +++ b/source/_components/telegram_bot.markdown @@ -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: "" chat: "" ``` -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: "" @@ -204,7 +212,6 @@ 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.