Telegram bot for Home Assistant (built-in integration)

About

Telegram bot is a built-in integration that connects Home Assistant to a Telegram bot through the Telegram cloud. It adds notifier and event entities, and an incoming update from Telegram is raised as an event that automations can react to. A broad set of actions covers sending messages, photos, videos, documents, voice messages, stickers, polls, locations and media groups. Sent messages can later be edited or deleted, including their caption, media and inline keyboard, and callback queries from keyboard buttons can be answered. Other actions download files to a local path, show a draft message while text is still being generated, and remove the bot from a chat. Setup happens in the UI with the bot's API token, and options include a platform choice, a default parse mode and trusted networks for webhooks.

Automatic summary of Home Assistant's source code. Something wrong? Get in touch

Supports

Uses the vendor's cloud Needs an internet connection and an account with the vendor.
Set up in the UI Add it in Settings, Devices and services. Nothing to download.
Change settings later Its connection settings can change without removing it.
Gold quality Home Assistant's own rating of its code and setup experience.
Updated with Home Assistant Ships and updates with every Home Assistant release.

Setting it up

It is added under Settings, Devices and services, with Add integration.

Connect

API tokenThe API token of your bot.
PlatformTelegram bot implementation
API endpoint
Proxy URL

Webhooks network configuration

Trusted networksTelegram server access ACL as list. Default: 149.154.160.0/20, 91.108.4.0/22
URLAllow to overwrite the external URL from the Home Assistant configuration for different setups.

Re-authenticate Telegram bot

API keyThe API token of your bot.

Telegram bot setup

PlatformTelegram bot implementation
API endpoint
Proxy URL

After setup

Parse modeDefault parse mode for messages if not explicit in message data.

Texts from Home Assistant's source code, Apache License 2.0.

Entities

EventsUpdate event

Actions

Answer callback queryResponds 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.Fields: Callback query ID, Config entry ID, Message, Show alert
Delete messageDeletes a previously sent message.Fields: Chat ID, Config entry ID, Notify target, Message ID
Download fileDownload the file to a local path.Fields: Config entry ID, Directory path, File ID, File name
Edit captionEdits the caption of a previously sent message.Fields: Caption, Chat ID, Config entry ID, Notify target, Inline keyboard, Message ID
Edit messageEdits a previously sent message.Fields: Chat ID, Config entry ID, Disable web page preview, Notify target, Inline keyboard, Message, Message ID, Parse mode, Title
Edit message mediaEdits the media content of a previously sent message.Fields: Authentication method, Caption, Chat ID, Config entry ID, Notify target, File, Inline keyboard, Media type, Message ID, Password
Edit reply markupEdits the inline keyboard of a previously sent message.Fields: Chat ID, Config entry ID, Notify target, Inline keyboard, Message ID
Leave chatRemoves the bot from the chat.Fields: Chat ID, Config entry ID, Notify target
Send animationSends an animation.Fields: Authentication method, Caption, Chat ID, Config entry ID, Disable notification, Notify target, File, Inline keyboard, Keyboard, Message tag
Send chat actionSends a chat action.Fields: Chat action, Chat ID, Config entry ID, Notify target, Message thread ID
Send documentSends a document.Fields: Authentication method, Caption, Chat ID, Config entry ID, Disable notification, Notify target, File, Inline keyboard, Keyboard, Message tag
Send locationSends a location.Fields: Chat ID, Config entry ID, Disable notification, Notify target, Inline keyboard, Keyboard, Latitude, Longitude, Message tag, Message thread ID
Send media groupSends a group of photos, videos, documents or audios as an album. Documents and audio files can only be grouped in an album with messages of the same type.Fields: Chat ID, Config entry ID, Disable notification, Notify target, Media, Message thread ID, Parse mode, Protect content, Reply to message ID
Send messageSends a notification.Fields: Chat ID, Config entry ID, Disable notification, Disable web page preview, Notify target, Inline keyboard, Keyboard, Message, Message tag, Message thread ID
Send message draftShows a partial message (draft) in Telegram while the full message is still being generated.Fields: Chat ID, Config entry ID, Draft ID, Notify target, Message, Message thread ID, Parse mode
Send photoSends a photo.Fields: Authentication method, Caption, Chat ID, Config entry ID, Disable notification, Notify target, File, Inline keyboard, Keyboard, Message tag
Send pollSends a poll.Fields: Allow multiple answers, Chat ID, Config entry ID, Disable notification, Notify target, Is anonymous, Message thread ID, Open period, Options, Question
Send stickerSends a sticker.Fields: Authentication method, Chat ID, Config entry ID, Disable notification, Notify target, File, Inline keyboard, Keyboard, Message tag, Message thread ID
Send videoSends a video.Fields: Authentication method, Caption, Chat ID, Config entry ID, Disable notification, Notify target, File, Inline keyboard, Keyboard, Message tag
Send voiceSends a voice message.Fields: Authentication method, Caption, Chat ID, Config entry ID, Disable notification, Notify target, File, Inline keyboard, Keyboard, Message tag