Telegram Bot: Respond to Telegram Command by executing an action

[marc-romu (Marc Roca)]

About this blueprint

Type of blueprint: AUTOMATION

What does it do?

This blueprint listens to a Telegram Command and executes a sequence of actions if listened.

Configuration

Requirements

• Telegram Bot integration

Input fields

• Command : REQUIRED command to listen for. Must start with ‘/’. Example: /start

• Bot: Bot username. It is used when there is more than one bot in a group chat. Example: my_bot_username_bot

• Sequence: What should happen when receiving this command.

Available variables for templating

Event data received from telegram are parsed as variables so that they are easily used in templates. These variables can be used within this automation:

• telegram_args: List of words sent after command. You can get each word by its index: telegram_args[0], telegram_args[1], etc.

• telegram_args_as_text: Single plain text string from arguments’ list. Useful if you need full text, not single words.

• telegram_chat_id: Chat id.

• telegram_sender_first_name: Sender’s first name.

• telegram_sender_last_name: Sender’s last name.

• telegram_sender_full_name: Sender’s full name, as first_name + " " + last_name

• telegram_sender_user_id: Sender’s user id.

Template example

Use format {{ variable_name }} to indicate that it is a template, as usual in Home Assistant.

Example: Hi {{ telegram_sender_first_name }}! You said {{ telegram_args_as_text }} after the command.

Related blueprints

• Telegram Bot: Respond to Telegram Command with a text message

• Telegram Bot: Store a text message into an input_text entity

• Telegram Bot: Execute an action after receiving a text message

Other blueprints

• GitHub repo with all my blueprints

How to get this blueprint?

Click the badge to import this Blueprint (needs Home Assistant Core 2021.3 or higher):

Or you can also:

• Copy-paste the content from this link to a new file inside your configuration’s blueprint folder.

Changelog

• 2022-09-03: Telegram API was updated and variables telegram_sender_first_name, telegram_sender_last_name, telegram_sender_full_name and telegram_sender_user_id are now available always.
• 2022-05-18: BREAKING CHANGE Variables telegram_sender_first_name, telegram_sender_last_name, telegram_sender_full_name and telegram_sender_user_id are now only available if you call a command (when you type /command in a telegram text message). If you click an inline keyboard button, these variables will not work. “Reply in private” function will only work with commands too.
• 2022-01-17: BREAKING CHANGE Replaced “Command @ Bot Username” field with a more simple “Bot” username field. Now it is not necessary to write down the command twice because it uses trigger_variables to concatenate command and bot username. Also added trigger ID.
• 2021-10-28: Add field “Command @ Bot Username” to ensure compatibility in group chats and Chat ID variable. Improved description.
• 2021-10-11: Parse telegram arguments and other event data received by Home Assistant and allow to use them as variables in templates. Also updated blueprint’s description.
• 2021-05-09: First version

[abasel (Andre)]

Hi, I installed your blueprint and created the below automation. When I run it the words “TTS Test” are broadcast on the speaker. When I however type “/say something” into telegram, nothing happens. My telegram integration works as I have Node-red flow that reacts to commands from telegram. I am however wanting to move away from Node-red and do everything via these automatons.

Once I get this working I would like to know how do to change things so that whatever is typed after my command, becomes the message.

telegram_bot:
  - platform: polling
    api_key: !secret telegram_api_key
    allowed_chat_ids:
      - !secret telegram_chat_id1

notify:
  - platform: telegram
    name: hcourt
    chat_id: !secret telegram_chat_id1

[marc-romu (Marc Roca)]

Nice feature request! I just updated the blueprint definition to get event data from Telegram and set them as variables so that they are useable in templates. I also updated description for better explaining.

Furthermore, I realized that arguments from telegram commands are received as a list of single words, so I added a variable called telegram_args_as_text that transforms the list back to a string of plain text.

Now, for example, if you type /say How are you?, arguments are stored in these two variables:

• telegram_args gets 'How', 'are', 'you?'
• telegram_args_as_text gets How are you?

[abasel (Andre)]

Thanks for this, unfortunately, I must have a config issue. I can send notifications to Telegram but Hass does not appear to see any /commands. When I type in "/talk Hi " nothing happens.

If I install Node-Red and use the Telegram nodes there then it all works so I think I have the correct API keys and IDs but can’t get it read Telegram commands when not using Node-Red (used the same config details that I used when connecting via Node-Red.

Also tried

But the display still does not change to cast mode i.e. I do not appear to be reading the commands that are being typed in.

[marc-romu (Marc Roca)]

Use {{ telegram_args_as_text }} in message field. Without {{ }} will not be replaced with the variable. I think that TTS service doesn’t allow templates in user interface mode, so it will automatically change to YAML mode, but no problem.

To debug your configuration, you can follow these steps:

1. Create another automation with this blueprint: Telegram Bot: Respond to Telegram Command with a text message
2. Listen to the same command. In your case: /talk
3. Set the message filed as You said: {{ telegram_args_as_text }}

With this configuration, Telegram Bot should respond to your message with the arguments.

Then, try to send a message to your bot like /talk How are you?. You should receive back a message saying: You said: How are you?.

Both blueprints use the same internal configuration, so if this one works, the other one should work. If it doesn’t, maybe you have some configuration issue with the action. You could try to debug it using developer tools tab in your Home Assistant instance.

I hope it helps!

[abasel (Andre)]

Thanks again I will give the debugging tools a go.

[marc-romu (Marc Roca)]

BLUEPRINT UPDATE

“Command @ Bot Username” field has been replaced with a more simple “Bot” username field. Now, it is not necessary to write down the command twice because it uses trigger_variables to concatenate command and bot username.

Bot username is used when there is more than one bot in a group chat.

It is a new field, so it is necessary to set it up if you update the blueprint.

[marc-romu (Marc Roca)]

BLUEPRINT UPDATE

It seems that telegram bot API has changed, and some information is now not working. I just updated the blueprint to avoid using data that is causing the error.

This means that variables telegram_sender_first_name, telegram_sender_last_name, telegram_sender_full_name and telegram_sender_user_id are now only available if you call a command (when you type /command in a telegram text message). If you click an inline keyboard button, these variables will not work. “Reply in private” function will only work with commands too.

[ralhei (Ralph)]

Cool blueprint. I really like to try it out, but when I click on the blue “import blueprint” button, I’m correctly redirected to my homeassistant UI, but after clicking on the ‘preview blueprint’ button, it tells me the following: No valid blueprint found in the topic. Blueprint syntax blocks need to be marked as YAML or no syntax.
I’m running homeassistant version 2022.5.5, so this should be recent enough, if I’m not wrong.
I’m pretty new to homeassistant so any help is very welcome. Thanks a lot.

[marc-romu (Marc Roca)]

Thanks for reporting! The link was wrong. I’ve already corrected it and now should work.

[ralhei (Ralph)]

Cool - now it worked like a charm. I really like it.

[marc-romu (Marc Roca)]

BLUEPRINT UPDATE: GOOD NEWS

The telegram bot API has updated and variables telegram_sender_first_name, telegram_sender_last_name, telegram_sender_full_name and telegram_sender_user_id are back available always, with no errors!

To benefit from these updates, redownload the blueprint code!

[abasel (Andre)]

@marc-romu

{{ telegram_args_as_text }}

Hi this is still working well with Google TTS but when I try using Picotts TTS, it does not work. I can get it to work with fixed text but not using the parameters i.e. {{ telegram_args_as_text }}

I am happy to use Google for now but thought I would just let you know.

[abasel (Andre)]

One more question. I tried the following in the message body but it shows the \n and not a new line

/say - Broadcasts message to Google Speakers\n/Garage - Toggles garage door\n/smartplug - Toggles smart plug```

[Sir_Goodenough ((SG) WhatAreWeFixing.Today)]

You mentioned on the top of the post that there is a minimum required version of HA to use this.
You may want to consider adding this to prevent issues with people not reading that…

Blueprint schema

Nice job on the Documentation, BTW. I might clone some of that. Mine tend to be , chaotic … at times.

[marc-romu (Marc Roca)]

Hi @abasel,

The {{ telegram_args_as_text }} is simply taking every single word after the command into a string. For example, /say How are you? returns How are you?. It doesn’t recognize new line breaks, so if you type \n it returns the same \n, not a new line.

You say that it works with Google TTS but not with Pico TTS. I do not have Pico TTS to try it, but as long as this TTS can read text strings, it should work as well. You can check whether there is some issue with quotation marks or typing in your code. Sometimes there are slight differences between platforms that make them break if we copy-paste the same code.

[marc-romu (Marc Roca)]

Hi @Sir_Goodenough,

I’ll include it. Thanks! And feel free to clone everything you want. That’s why it is open source .

[Kabelkatze (Sebastian)]

I have successfully set up the above blueprint. I use it so that I can fill my shopping list via my Telegrambot. This also works, but I would like to remove the following characters from the entry.
Here is the config of the blueprint:

Füge ich nun mit meinem Telegrambot ein Item zur Liste hinzu, macht er das zwar. Aber nur mit diesen Klammern [’’] Diese möchte ich aber entfernen. Wie mache ich das?

[marc-romu (Marc Roca)]

Hi @Kabelkatze,

The {{ telegram_args }} is a list of all the words sent after the command. A list means that every word is considered a separate element. That’s why they are wrapped in ['']. If you want all them as a single text string, you could try to use the {{ telegram_args_as_text }} parameter instead.

I hope it helps!