Telegram chatbot

Use Telegram on your mobile or desktop device to send and receive messages or commands to/from your Home Assistant.

This component creates notification services to send, or edit previously sent, messages from a Telegram Bot account configured either with the polling method or with the webhooks one, and trigger events when receiving messages.

If you don’t need to receive messages, you can use the broadcast platform instead.

Service telegram_bot.edit_message

Edit a previously sent message in a conversation.

Service data attribute

Optional

Description

message_id

no

Id of the message to edit. 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 edit the message.

message

no

Message body of the notification.

title

yes

Optional title for your notification. Will be composed as ‘%title\n%message’.

Service telegram_bot.edit_caption

Edit the caption of a previously sent message.

Service data attribute

Optional

Description

message_id

no

Id of the message to edit. 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.

Service telegram_bot.edit_replymarkup

Edit the inline keyboard of a previously sent message.

Service data attribute

Optional

Description

message_id

no

Id of the message to edit. 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.

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

message

no

Unformatted text message body of the notification.

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.

Service telegram_bot.delete_message

Delete a previously sent message in a conversation.

Service data attribute

Optional

Description

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.

telegram notification platform

The telegram notification platform 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:

notify:-name:NOTIFIER_NAMEplatform:telegramchat_id:USER_CHAT_ID

Event triggering

A command looks like /thecommand or /othercommand with some args.

When received by Home Assistant it will fire a telegram_command event on the event bus with the following event_data:

If the message is sent from a press from an inline button, for example, a callback query is received, and Home Assistant will fire a telegram_callback event with:

data:"<dataassociatedtoactioncallback>"message:<message origin of the action callback>from_first:"<firstnameofthesender>"from_last:"<lastnameofthesender>"user_id:"<idofthesender>"id:"<uniqueidofthecallback>"chat_instance:"<chatinstance>"chat_id:"<originchatid>"

Sample automations with callback queries and inline keyboards

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’: