Telegram bot

Use Telegram on your mobile or desktop device to send and receive messages or commands to/from your Home Assistant. This integration creates notification actions to send, edit or receive messages from a Telegram Bot account.

Introduction - Telegram bot platforms

Platforms are Telegram bot implementations for managing communications with Telegram for sending and receiving messages. When setting up this integration, you should specify the platform which fits your environment and use case.

Broadcast

Telegram implementation to support sending messages only. Your Home Assistant instance does not have to be exposed to the internet and there is no polling to receive messages or commands sent to the bot.

Polling

Telegram chatbot polling implementation. Your Home Assistant instance does not have to be exposed to the internet.

Webhooks

Telegram chatbot webhooks implementation as described in the Telegram documentation. This implementation allows Telegram to push updates directly to your server and requires your Home Assistant instance to be exposed to the internet.

Prerequisites

Create Telegram bot

Create your Telegram bot and retrieve the API key. The api_key will be used for adding the bot to Home Assistant during integration setup.

Allow Telegram bot to access your Home Assistant files (Optional)

To enable Telegram bot to send local files, you must grant access to it by adding the file’s folder to allowlist_external_dirs.

Example configuration.yaml:

homeassistant:
  allowlist_external_dirs:
    - "/media"

Allow Telegram to connect to your Home Assistant (Webhooks platform only)

If you plan to use the Webhooks platform, you will need to allow Telegram to connect to your Home Assistant using one of the following methods:

Home Assistant Cloud

If you have a Home Assistant Cloud subscription, you can enable remote access to your Home Assistant.

Reverse proxy

If your Home Assistant is behind a publicly accessible reverse proxy (for example NGINX, Caddy, Traefik) with HTTPS enabled, do the following:

1. Go to Settings > System > Network and configure Home Assistant URL.
2. Configure the HTTP integration to allow Home Assistant to accept connections from your reverse proxy:
   • Set use_x_forwarded_for to true.
   • Add the IP address of the reverse proxy to trusted_proxies.

Example configuration.yaml:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.0.0/16

Direct

If your Home Assistant is publicly accessible, do the following:

1. Go to Settings > System > Network and configure Home Assistant URL.
2. Configure the HTTP integration to enable HTTPS on your Home Assistant by configuring the following variables:
   • server_host
   • server_port
   • ssl_certificate
   • ssl_key

Configuration

To add the Telegram bot integration to your Home Assistant instance, use this My button:

Webhooks configuration

If you have selected the Webhooks Telegram bot type, the integration setup will continue with the webhooks configuration step.

Options

Options for Telegram bot can be set via the user interface, by taking the following steps:

• Browse to your Home Assistant instance.
• Go to Settings > Devices & Services.
• If multiple instances of Telegram bot are configured, choose the instance you want to configure.
• Select the integration, then select Configure.

The integration can be configured to use a default parse mode for messages.

Allowlisting chat IDs via Subentries

A Telegram chat ID is a unique numerical identifier for an individual user (positive) or a chat group (negative). You must allowlist the chat ID for the Telegram bot before it can send/receive messages for that chat. To allowlist the chat ID, retrieve the chat ID and create a subentry:

1. Go to Settings > Devices & services.
2. Select the Telegram bot integration.
3. Next to the entry, select the three dots menu. Then, select Add allowed chat ID.

Notification actions

Available actions: send_message, send_photo, send_video, send_animation, send_voice, send_sticker, send_document, send_location, edit_message, edit_caption, edit_replymarkup, answer_callback_query, delete_message, leave_chat and set_message_reaction.

Actions that send contents (send_*) will return a list of message_id/chat_id for messages delivered (in a property called chats). This will populate Response Data that you can further utilize in your automations to edit/delete the message later based on the message_id. See the example later on this page for usage instructions.

Action telegram_bot.send_message

Send a notification.

Action telegram_bot.send_photo

Send a photo.

Action telegram_bot.send_video

Send a video.

Action telegram_bot.send_animation

Send an animation.

Action telegram_bot.send_voice

Send a voice message.

Action telegram_bot.send_sticker

Send a sticker.

Action telegram_bot.send_document

Send a document.

Action telegram_bot.send_location

Send a location.

Action telegram_bot.send_poll

Send a poll.

Action telegram_bot.edit_message

Edit a previously sent message in a conversation.

Action telegram_bot.edit_caption

Edit the caption of a previously sent message.

Action telegram_bot.edit_replymarkup

Edit the inline keyboard of a previously sent message.

Action 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.

Action telegram_bot.delete_message

Delete a previously sent message in a conversation.

Action telegram_bot.leave_chat

Remove the bot from the chat group where it was added.

Action telegram_bot.set_message_reaction

Sets the bot’s reaction for a given message.

Telegram notification platform

The telegram notification platform requires the telegram_bot integration 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 data attributes parse_mode, disable_notification, message_tag, disable_web_page_preview, and message_thread_id are also supported.

The required YAML configuration now reduces to:

notify:
  - platform: telegram
    name: NOTIFIER_NAME
    chat_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:

command: "/thecommand"
args: "<any other text following the command>"
from_first: "<first name of the sender>"
from_last: "<last name of the sender>"
user_id: "<id of the sender>"
chat_id: "<origin chat id>"
chat: "<chat info>"
date: "<message timestamp>"
message_thread_id: "<message thread 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:

text: "some text received"
from_first: "<first name of the sender>"
from_last: "<last name of the sender>"
user_id: "<id of the sender>"
chat_id: "<origin chat id>"
chat: "<chat info>"
date: "<message timestamp>"
message_thread_id: "<message thread id>"

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: "<data associated to action callback>"
message: <message origin of the action callback>
from_first: "<first name of the sender>"
from_last: "<last name of the sender>"
user_id: "<id of the sender>"
id: "<unique id of the callback>"
chat_instance: "<chat instance>"
chat_id: "<origin chat id>"

Configuration samples

Simple ping pong example.

alias: "Telegram bot that reply pong to ping"
triggers:
  - trigger: event
    event_type: telegram_command
    event_data:
      command: "/ping"
actions:
  - action: notify.notify
    data:
      message: "pong"

An example that shows keyboard interaction with notify.telegram

triggers:
  - trigger: event
    event_type: telegram_command
    event_data:
      command: "/start"
actions:
  - action: notify.telegram
    data:
      message: "commands"
      data:
        keyboard:
          - '/ping, /alarm'
          - '/siren'

and an automation to trigger a related command “/siren”.

triggers:
  - trigger: event
    event_type: telegram_command
    event_data:
      command: "/siren"
actions:
  - action: homeassistant.turn_on
    target:
      entity_id: switch.vision_zm1601eu5_battery_operated_siren_switch_9_0
  - delay:
      seconds: 10
  - action: homeassistant.turn_off
    target:
      entity_id: switch.vision_zm1601eu5_battery_operated_siren_switch_9_0

An example to show the use of event_data in action:

- alias: "Kitchen Telegram Speak"
  triggers:
    - trigger: event
      event_type: telegram_command
      event_data:
        command: "/speak"
  actions:
    - action: notify.kitchen_echo
      data:
        message: >
          Message from {{ trigger.event.data["from_first"] }}. {% for state in trigger.event.data["args"] %} {{ state }} {% endfor %}

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

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

- alias: "Telegram bot that repeats text"
  triggers:
    - trigger: event
      event_type: telegram_text
  actions:
    - action: telegram_bot.send_message
      data:
        title: "*Dumb automation*"
        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"

Message editor:

- alias: "Telegram bot that edits the last sent message"
  triggers:
    - trigger: event
      event_type: telegram_callback
      event_data:
        command: "/edit_msg"
  actions:
    - action: telegram_bot.answer_callback_query
      data:
        callback_query_id: "{{ trigger.event.data.id }}"
        message: "Editing the message!"
        show_alert: true
    - action: telegram_bot.edit_message
      data:
        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: >
          Callback received from {{ trigger.event.data.from_first }}.
          Message id: {{ trigger.event.data.message.message_id }}.
          Data: {{ trigger.event.data.data|replace("_", "\_") }}

Keyboard editor:

- alias: "Telegram bot that edits the keyboard"
  triggers:
    - trigger: event
      event_type: telegram_callback
      event_data:
        command: "/remove_button"
  actions:
    - action: telegram_bot.answer_callback_query
      data:
        callback_query_id: "{{ trigger.event.data.id }}"
        message: "Callback received for editing the inline keyboard!"
    - action: telegram_bot.edit_replymarkup
      data:
        message_id: "last"
        chat_id: "{{ trigger.event.data.chat_id }}"
        inline_keyboard:
          - "Edit message:/edit_msg, Don't:/do_nothing"

Only acknowledges the ‘NO’ answer:

- alias: "Telegram bot that simply acknowledges"
  triggers:
    - trigger: event
      event_type: telegram_callback
      event_data:
        command: "/do_nothing"
  actions:
    - action: telegram_bot.answer_callback_query
      data:
        callback_query_id: "{{ trigger.event.data.id }}"
        message: "OK, you said no!"

Telegram callbacks also support arguments and commands the same way as normal messages.

- alias: "Telegram bot repeats arguments on callback query"
  triggers:
    - trigger: event
      event_type: telegram_callback
      event_data:
        command: "/repeat"
  actions:
    - action: telegram_bot.answer_callback_query
      data:
        show_alert: true
        callback_query_id: "{{ trigger.event.data.id }}"
        message: "I repeat: {{trigger.event.data['args']}}"

In this case, having a callback with /repeat 1 2 3 will pop a notification saying I repeat: [1, 2, 3]

Receiving chat_id and message_id identifiers of sent messages by the telegram_bot.

- alias: 'Notifications about messages sent by Telegram bot'
  triggers:
    - trigger: event
      event_type: telegram_sent
      event_data:
        message_tag: "msg_start"
  actions:
    - action: input_number.set_value
      data_template:
        entity_id: input_number.chat_id
        value: "{{ trigger.event.data.chat_id }}"
    - action: input_number.set_value
      data_template:
        entity_id: input_number.message_id
        value: "{{ trigger.event.data.message_id }}"

Example: send_message with formatted Text

actions:
- action: notify.telegrambot
  data:
    title: Example Message
    message: 'Message with *BOLD*, _ITALIC_ and `MONOSPACE` Text'

Example: send_message with message tag

actions:
- action: notify.telegrambot
  data:
    title: Example Message
    message: "Message with tag"
    data:
      message_tag: "example_tag"

Example: send_message with disabled webpage preview

actions:
- action: notify.telegram
  data:
    message: >-
      <a href="https://www.home-assistant.io/">HA site</a>
    data:
      parse_mode: html
      disable_web_page_preview: true

Example: send_message to a topic within a group

actions:
- action: notify.telegram
  data:
    message: "Message to a topic"
    data:
      message_thread_id: 123

Example: automation to send a message and delete after a delay

alias: telegram send message and delete
sequence:
  - action: telegram_bot.send_message
    data:
      message: testing
    response_variable: response
  - delay:
      seconds: 5
  - repeat:
      sequence:
        - action: telegram_bot.delete_message
          data:
            message_id: "{{ repeat.item.message_id }}"
            chat_id: "{{ repeat.item.chat_id }}"
      for_each: "{{ response.chats }}"

Removing the integration

This integration follows standard integration removal. No extra steps are required.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three dots menu. Then, select Delete.