diff --git a/source/_components/notify.smtp.markdown b/source/_components/notify.smtp.markdown index aa65fb720331..06b783da2682 100644 --- a/source/_components/notify.smtp.markdown +++ b/source/_components/notify.smtp.markdown @@ -37,6 +37,7 @@ Configuration variables: - **password** (*Optional*): Password for the SMTP server that belongs to the given username. If the password contains a colon it need to be wrapped in apostrophes. - **recipient** (*Required*): Recipient of the notification. - **starttls** (*Optional*): Enables STARTTLS, eg. True or False. Defaults to False. +- **product_name** (*Optional*): Sets a 'product name' for the emails headers (*From* = *Custom name *, *X-Mailer* = *Custom name*). - **debug** (*Optional*): Enables Debug, eg. True or False. Defaults to False. A sample configuration entry for Google Mail. @@ -54,6 +55,7 @@ notify: username: john@gmail.com password: thePassword recipient: james@gmail.com + product_name: My Home ``` Keep in mind that Google has some extra layers of protection which need special attention (Hint: 'Less secure apps'). @@ -79,6 +81,73 @@ To use the SMTP notification, refer to it in an automation or script like in thi The optional `images` field adds in-line image attachments to the email. This sends a text/HTML multi-part message instead of the plain text default. +The optional `html` field makes a custom text/HTML multi-part message, allowing total freedom for sending rich html emails. In them, if you need to attach images, you can pass both arguments (`html` and `images`), the attachments will be joined with the basename of the images, so they can be included in the html page with `src="cid:image_name.ext"`. + +```yaml + burglar: + alias: Burglar Alarm + sequence: + - service: shell_command.snapshot + - delay: + seconds: 1 + - service: notify.NOTIFIER_NAME + data_template: + message: 'Intruder alert at apartment!!' + data: + images: + - /home/pi/snapshot1.jpg + - /home/pi/snapshot2.jpg + html: > + + + + + + + Intruder alert + + + + + +
+
+

Intruder alert at apartment!!

+
+
+
+
+
+ snapshot1 +
+
+ snapshot2 +
+
+
+
+ + + + + +``` +Obviously, this kind of complex html email reporting is done much more conveniently using Jinja2 templating from an [AppDaemon app](https://home-assistant.io/docs/ecosystem/appdaemon/tutorial/), for example. + This platform is fragile and not able to catch all exceptions in a smart way because of the large number of possible configuration combinations. A combination that will work properly is port 587 and STARTTLS. It's recommended to enable STARTTLS, if possible. diff --git a/source/_components/notify.telegram.markdown b/source/_components/notify.telegram.markdown index 6145e24ee0f8..72989998a568 100644 --- a/source/_components/notify.telegram.markdown +++ b/source/_components/notify.telegram.markdown @@ -18,7 +18,7 @@ The `telegram` platform uses [Telegram](https://web.telegram.org) to delivery no The requirements are: - You need a [Telegram bot](https://core.telegram.org/bots). Please follow those [instructions](https://core.telegram.org/bots#6-botfather) to create one and get the token for your bot. Keep in mind that bots are not allowed to contact users. You need to make the first contact with your user. Meaning that you need to send a message to the bot from your user. -- The `chat_id` of an user. +- The `chat_id` of an user, or a list of `user_id`s for sending messages to multiple users. To retrieve your `chat_id`, contact any of the Telegram bots created for this purpose (@myidbot, @get_id_bot) @@ -51,16 +51,39 @@ notify: platform: telegram api_key: ABCDEFGHJKLMNOPQRSTUVXYZ chat_id: YOUR_CHAT_ID + +# With more than one authorized target: +notify: + - name: NOTIFIER_NAME + platform: telegram + api_key: ABCDEFGHJKLMNOPQRSTUVXYZ + user_id: + User_name_1: CHAT_ID_USER_1 + User_name_2: CHAT_ID_USER_2 ``` Configuration variables: - **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`. - **api_key** (*Required*): The API token of your bot. -- **chat_id** (*Required*): The chat ID of your user. +- **chat_id** (*Optional*): The chat ID of your user. +- **user_id** (*Optional*): Multiple chat IDs for multiple users. +- **parse_mode** (*Optional*): Default parser for messages if not explicit in message data: 'html' or 'markdown'. Default is 'markdown'. To use notifications, please see the [getting started with automation page](/getting-started/automation/). +### {% linkable_title Common message data parameters %} + +- **message** (*Required*): Message text. +- **title** (*Optional*): Will be composed as '%title\n%message'. +- **parse_mode** (*Optional*): Parser for the message text: 'html' or 'markdown'. +- **timeout** (*Optional*): If this value is specified, use it as the definitive timeout (in seconds) for urlopen() operations. +- **disable_notification** (*Optional*): Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. +- **disable_web_page_preview** (*Optional*): Disables link previews for links in the message. +- **reply_to_message_id** (*Optional*): If the message is a reply, ID of the original message. +- **keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom keyboard. +- **inline_keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data. + ### {% linkable_title Photo support %} ```yaml @@ -86,6 +109,7 @@ action: - **username** (*Optional*): Username for a URL which require HTTP basic authentication. - **password** (*Optional*): Username for a URL which require HTTP basic authentication. + ### {% linkable_title Document support %} ```yaml @@ -127,3 +151,69 @@ action: - **latitude** (*Required*): The latitude to send. - **longitude** (*Required*): The longitude to send. +### {% linkable_title Answering callback queries %} + +To send a quick answer when receiving a [callback query event](/_components/telegram_bot.markdown/) sent from an inline keyboard. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert. + +```yaml +... +trigger: + platform: event + event_type: telegram_callback +action: +- service: notify.NOTIFIER_NAME + data: + message: "OK, I'm listening" + data: + callback_query: + callback_query_id: '{{ trigger.event.data.id }}' + show_alert: false +``` + +- **callback_query** (*Required*): + - **callback_query_id** (*Required*): Unique id of the callback response. + - **show_alert** (*Optional*): Show a permanent notification. + +### {% linkable_title Editing messages sent previously %} + +You can edit a message (`edit_message`) or a image caption (`edit_caption`) from a previusly sent message: + +```yaml +... +action: +- service: notify.NOTIFIER_NAME + data_template: + title: '*Message edit*' + message: 'This is the new text of the message' + data: + edit_message: + message_id: '{{ trigger.event.data.message.message_id }}' + disable_notification: true + inline_keyboard: + - '/edit,/NO' + - '/remove button' +... +``` + +- **edit_message** or **edit_caption** (*Required*): + - **message_id** or **inline_message_id** (*Required*): id of the message to be edited. + +or change the keyboard or the inline keyboard of the message of origin (`edit_replymarkup`): + +```yaml +... +action: +- service: notify.NOTIFIER_NAME + data: + message: '' + edit_replymarkup: + message_id: 'last' + disable_notification: true + inline_keyboard: + - '/edit,/NO' +... +``` + +- **edit_replymarkup** (*Required*): + - **message_id** or **inline_message_id** (*Required*): id of the message to be edited. +- **keyboard** or **inline_keyboard** (*Required*): New keyboard. diff --git a/source/_components/telegram_bot.markdown b/source/_components/telegram_bot.markdown index 8d51d6d9112f..12c5be26afe7 100644 --- a/source/_components/telegram_bot.markdown +++ b/source/_components/telegram_bot.markdown @@ -14,9 +14,9 @@ ha_release: 0.42 Use Telegram on your mobile device to send messages or commands to your Home Assistant. -A command looks like `/thecommand` +A command looks like `/thecommand`, or `/othercommand with some args`. -When received by hass it will fire a `telegram.command` event on the event bus with the following `event_data`: +When received by hass it will fire a `telegram_command` event on the event bus with the following `event_data`: ```yaml command: "/thecommand" @@ -26,6 +26,27 @@ from_last: "" user_id: "" ``` +Any other message not starting with `/` will be processed as simple text, firing a `telegram_text` event on the event bus with the following `event_data`: + +```yaml +text: "some text received" +from_first: "" +from_last: "" +user_id: "" +``` + +if the message is sent from a [press in a inline button](https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating), for example, a callback query is received, and hass will fire a `telegram_callback` event with: + +```yaml +data: "" +message: +from_first: "" +from_last: "" +user_id: "" +id: "" +chat_instance: "" +``` + ### {% linkable_title Configuration samples %} @@ -36,7 +57,7 @@ alias: 'telegram bot that reply pong to ping' hide_entity: true trigger: platform: event - event_type: telegram.command + event_type: telegram_command event_data: command: '/ping' action: @@ -50,7 +71,7 @@ Example that show keyboard interaction with `notify.telegram` ```yaml trigger: platform: event - event_type: telegram.command + event_type: telegram_command event_data: command: '/start' action: @@ -68,7 +89,7 @@ and an automation to trigger a related command "/siren". ```yaml trigger: platform: event - event_type: telegram.command + event_type: telegram_command event_data: command: '/siren' action: @@ -79,3 +100,118 @@ action: - service: homeassistant.turn_off entity_id: switch.vision_zm1601eu5_battery_operated_siren_switch_9_0 ``` + +### {% 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': +- Pressing 'EDIT' changes the sended message. +- Pressing 'NO' only shows a brief notification (answering the callback query). +- Pressing 'REMOVE BUTTON' changes the inline keyboard removing that button. + +Text repeater: +```yaml +- alias: 'telegram bot that repeats text' + hide_entity: true + trigger: + platform: event + event_type: telegram_text + action: + - service: notify.telegram + data_template: + title: '*Dumb automation*' + target: '{{ trigger.event.data.user_id }}' + message: 'You said: ``` {{ trigger.event.data.text }} ```' + data: + disable_notification: true + inline_keyboard: + - '/edit,/NO' + - '/remove button' +``` + +Message editor: +```yaml +- alias: 'telegram bot last sended msg edit' + hide_entity: true + trigger: + platform: event + event_type: telegram_callback + event_data: + data: '/edit' + action: + - service: notify.telegram + data_template: + target: '{{ trigger.event.data.user_id }}' + message: 'Editing the message!' + data: + callback_query: + callback_query_id: '{{ trigger.event.data.id }}' + show_alert: true + - service: notify.telegram + data_template: + title: '*Message edit*' + target: '{{ trigger.event.data.user_id }}' + message: > + Callback received from {{ trigger.event.data.from_first }}. + Message id: {{ trigger.event.data.message.message_id }}. + Data: ``` {{ trigger.event.data.data }} ``` + data: + edit_message: + message_id: '{{ trigger.event.data.message.message_id }}' + disable_notification: true + inline_keyboard: + - '/edit,/NO' + - '/remove button' +``` + +Keyboard editor: +```yaml +- alias: 'telegram bot keyboard edit' + hide_entity: true + trigger: + platform: event + event_type: telegram_callback + event_data: + data: '/remove button' + action: + - service: notify.telegram + data_template: + target: '{{ trigger.event.data.user_id }}' + message: 'Callback received for editing the inline keyboard!' + data: + callback_query: + callback_query_id: '{{ trigger.event.data.id }}' + show_alert: false + - service: notify.telegram + data_template: + target: '{{ trigger.event.data.user_id }}' + message: '' # this is needed for the general hass notify service + data: + edit_replymarkup: + message_id: 'last' + disable_notification: true + inline_keyboard: + - '/edit,/NO' + +``` + +Only acknowledges the 'NO' answer: +```yaml +- alias: 'telegram bot simply acknowledges' + hide_entity: true + trigger: + platform: event + event_type: telegram_callback + event_data: + data: '/NO' + action: + - service: notify.telegram + data_template: + target: '{{ trigger.event.data.user_id }}' + message: 'OK, you said no!' + data: + callback_query: + callback_query_id: '{{ trigger.event.data.id }}' + show_alert: false +``` + +For a more complex usage of the `telegram_bot` capabilities, using [AppDaemon](https://home-assistant.io/docs/ecosystem/appdaemon/tutorial/) is advised. \ No newline at end of file