{"id":15086075,"url":"https://github.com/lufton/ha_telegram_client","last_synced_at":"2025-09-07T05:38:39.129Z","repository":{"id":256464233,"uuid":"851571917","full_name":"lufton/ha_telegram_client","owner":"lufton","description":"HACS telegram client component","archived":false,"fork":false,"pushed_at":"2025-06-25T10:30:09.000Z","size":40,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-27T11:16:18.191Z","etag":null,"topics":["api","automation","bot","client","home-assistant","messenger","telegram"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lufton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-03T10:42:31.000Z","updated_at":"2025-06-25T10:28:15.000Z","dependencies_parsed_at":"2024-09-10T22:23:12.831Z","dependency_job_id":"2d0d3379-1f7b-4f98-b869-4ad56d005a21","html_url":"https://github.com/lufton/ha_telegram_client","commit_stats":{"total_commits":13,"total_committers":1,"mean_commits":13.0,"dds":0.0,"last_synced_commit":"eb519417958e73715d997ce1c87167760ab82f7b"},"previous_names":["lufton/ha_telegram_client"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/lufton/ha_telegram_client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lufton%2Fha_telegram_client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lufton%2Fha_telegram_client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lufton%2Fha_telegram_client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lufton%2Fha_telegram_client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lufton","download_url":"https://codeload.github.com/lufton/ha_telegram_client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lufton%2Fha_telegram_client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273998224,"owners_count":25204725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","automation","bot","client","home-assistant","messenger","telegram"],"created_at":"2024-09-25T07:30:22.017Z","updated_at":"2025-09-07T05:38:39.091Z","avatar_url":"https://github.com/lufton.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram client integration\nThe `telegram_client` integration uses [Telethon library](https://docs.telethon.dev/) to connect Home Assistant with your [Telegram](https://telegram.org/) account in order to send, edit and delete messages and also capture and propagate events to event bus.\n\n## Installation\n\n### Installation using HACS\n\nPreferable way to install this custom integration is to use [HACS](https://www.hacs.xyz/). Learn how to install HACS [here](https://www.hacs.xyz/docs/use/download/download).\nAfter you have successfully installed and configured HACS you can simply press this button to add this repository to HACS and proceed to `Telegram client` installation.\n\n[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=lufton\u0026repository=ha_telegram_client\u0026category=integration)\n\n### Manual installation\n\nIf you don't have or don't want to install HACS you can simple donwload [latest release](https://github.com/lufton/ha_telegram_client/releases/latest) `Source code (zip)` file. Unzip it, copy `custom_components/telegram_client` folder inside `custom_components` folder of your Home Assistant instance and restart it.\n\n## Two client types\n\nThis integration allows you to authorize either [as a user](#user-config-flow) or [as a bot](#bot-config-flow). Depending on your needs, you can pick which one is preferable to you. Each type of client has its own benefits and limitations. For example `User` can send messages to any other user (depends on privacy setting), whereas `Bot` can't. But `Bot` can send messages with keyboards, whereas `User` can't.\nBut don't worry, you can create several instances of Telegram client with different types and get benefits of both.\n\n## Obtaining Telegram `api_id` and `api_hash`\n\nTo register Telegram app you need to have active account.\n\n1. Navigate to [App configuration page](https://my.telegram.org/apps)\n2. Sign in\n3. Give your app a title and short name and save changes\n4. Copy `api_id` and `api_hash`, you will need them later\n\n## Obtaining Telegram bot `token` (for bot client)\n\n1. Start conversation with [BotFather](https://t.me/BotFather)\n2. Send a command `/newbot` or select from menu\n3. Enter your bot name\n4. Enter your bot username\n5. Copy `token`, you will need it later\n\n## User config flow\n\n1. Navigate to [Telegram client integrations page](https://my.home-assistant.io/redirect/config_flow_start?domain=telegram_client)\n2. Enter previously saved `api_id` and `api_hash`, select `User` as a **Client type**\n3. Press **Submit** button\n4. Enter the phone number of your account in international format (+XXXXXXXXXXXX)\n5. Press **Submit** button\n6. Enter the code you received from Telegram\n7. Press **Submit** button\n8. If your account is protected with 2FA, then enter your `password` and press **Submit** button\n\n## Bot config flow\n\n1. Navigate to [Telegram client integrations page](https://my.home-assistant.io/redirect/config_flow_start?domain=telegram_client)\n2. Enter previously saved `api_id` and `api_hash`, select `Bot` as a **Client type**\n3. Press **Submit** button\n4. Enter previously saved `token`\n5. Press **Submit** button\n\n## Options flow\n\nTelegram client integration supports options on events that are going to propagate to Home Assistant event bus via **Configure** button on [this page](https://my.home-assistant.io/redirect/integration/?domain=telegram_client). You can select which kinds of [events](#events) you want to be able to listen for.\nEach event has its own set of settings. Please refer to [Telethon events documentation page](https://docs.telethon.dev/en/stable/modules/events.html) for full explanation.\n\n## Services\n\n* [telegram_client.send_messages](#service-telegram_clientsend_messages) – Send message(s)\n* [telegram_client.edit_message](#service-telegram_clientedit_message) – Edit message\n* [telegram_client.delete_messages](#service-telegram_clientdelete_messages) – Delete message(s)\n\n### Service `telegram_client.send_messages`\n\nSend messages to user, group, channel or bot.\n| Service data attribute | Optional | Description                                                                                                                                                                                                                                                                                                                                                                        |\n| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `config_entry_id`      | no       | Config entry ID to run service on.\u003cbr/\u003e\u003cbr/\u003e*Defaults to first one.*                                                                                                                                                                                                                                                                                                               |\n| `target_username`      | no       | Username or list of usernames to send message to.\u003cbr/\u003eExample (my saved messages):\u003cbr/\u003e`me`\u003cbr/\u003eExample (bot):\u003cbr/\u003e`BotFather`\u003cbr/\u003eExample (user):\u003cbr/\u003e`bigfoot`\u003cbr/\u003e\u003cbr/\u003e*At least one of `target_username` or `target_user_id` is required.*                                                                                                                                     |\n| `target_id`            | no       | User/group ID or list of user/group IDs to send message to.\u003cbr/\u003eExample (user):\u003cbr/\u003e`100000000`\u003cbr/\u003eExample (group):\u003cbr/\u003e`-100000000`\u003cbr/\u003e\u003cbr/\u003e*At least one of `target_username` or `target_user_id` is required.*                                                                                                                                                                |\n| `message`              | no       | Message text to send. Could contain `html` or `markdown` formatting. See `parse_mode` parameter.\u003cbr/\u003e\u003cbr/\u003e*Optional when sending files.*                                                                                                                                                                                                                                           |\n| `reply_to`             | no       | Mark the message as a reply to a message with provided ID. Also can be used to send a message in a specific group topic (provide topic ID).                                                                                                                                                                                                                                        |\n| `parse_mode`           | no       | Message parse mode. Could be either `html` or `markdown`.\u003cbr/\u003e\u003cbr/\u003e*Defaults to `plain text`.*                                                                                                                                                                                                                                                                                     |\n| `link_preview`         | no       | Enables previews for links in the message.                                                                                                                                                                                                                                                                                                                                         |\n| `file`                 | no       | Path or paths relative to `config` directory to send with a message.\u003cbr/\u003eExample (1 file):\u003cbr/\u003e`tts/ff5789a925ee97c09d1462a53b4416c21a26e128.mp3`\u003cbr/\u003eExample (2 files):\u003cbr/\u003e`[\"configuration.yaml\", \"secrets.yaml\"]`                                                                                                                                                              |\n| `force_document`       | no       | Attach file(s) as document(s) rather than image/audio/video.                                                                                                                                                                                                                                                                                                                       |\n| `clear_draft`          | no       | Clears draft message to selected target after sending the message.                                                                                                                                                                                                                                                                                                                 |\n| `keyboard`             | no       | Button, list of buttons or list of lists of buttons to show under the message.\u003cbr/\u003eExample (1 button):\u003cbr/\u003e`Accept`\u003cbr/\u003eExample (1 row of 2 buttons):\u003cbr/\u003e`[\"Yes\", \"No\"]`\u003cbr/\u003eExample (2 rows of 2 button each):\u003cbr/\u003e`[[\"Like\", \"Dislike\"], [\"Share\", \"Subscribe\"]]`                                                                                                               |\n| `inline_keyboard`      | no       | Button, list of buttons or list of lists of buttons to show under the message. Each button could be a dictionary with `text` and `data` keys.\u003cbr/\u003eExample (1 button):\u003cbr/\u003e`Agree`\u003cbr/\u003eExample (1 row of 2 buttons):\u003cbr/\u003e`[{\"text\": \"Accept\", \"data\": \"accept\"}, {\"text\": \"Decline\", \"data\": \"decline\"}]`\u003cbr/\u003eExample (2 rows of 2 button each):\u003cbr/\u003e`[[\"-1\", \"+1\"], [\"-5\", \"+5\"]]` |\n| `keyboard_resize`      | no       | Resizes keyboard to minimize space used.\u003cbr/\u003e\u003cbr/\u003e*Can be used only if `keyboard` is defined.*                                                                                                                                                                                                                                                                                     |\n| `keyboard_single_use`  | no       | Hides keyboard after user press any button.\u003cbr/\u003e\u003cbr/\u003e*Can be used only if `keyboard` is defined.*                                                                                                                                                                                                                                                                                  |\n| `silent`               | no       | Sends message without sound notification.                                                                                                                                                                                                                                                                                                                                          |\n| `supports_streaming`   | no       | Whether the sent video supports streaming or not.                                                                                                                                                                                                                                                                                                                                  |\n| `schedule`             | no       | Schedule message delivery.\u003cbr/\u003e\u003cbr/\u003e*Can be used only in `User` mode. Bots can't schedule message delivery.*                                                                                                                                                                                                                                                                       |\n| `comment_to`           | no       | Similar to `reply_to`, but replies in the linked group of a broadcast channel instead.                                                                                                                                                                                                                                                                                             |\n| `nosound_video`        | no       | Displays video without audio track as a video. Otherwise Telegram will attempt to display such video as an animated gif.                                                                                                                                                                                                                                                           |\n\n### Service `telegram_client.edit_message`\n\nEdits text of a previously sent message to user, group, channel or bot.\n| Service data attribute | Optional | Description                                                                                                                                                                                                                                                                                                                                                                        |\n| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `config_entry_id`      | no       | Config entry ID to run service on.\u003cbr/\u003e\u003cbr/\u003e*Defaults to first one.*                                                                                                                                                                                                                                                                                                               |\n| `target_username`      | no       | Username to edit message for.\u003cbr/\u003eExample (my saved messages):\u003cbr/\u003e`me`\u003cbr/\u003eExample (bot):\u003cbr/\u003e`BotFather`\u003cbr/\u003eExample (user):\u003cbr/\u003e`bigfoot`\u003cbr/\u003e\u003cbr/\u003e*Required if target message was sent to a group or a channel.*                                                                                                                                                               |\n| `target_id`            | no       | User/group ID to edit message for.\u003cbr/\u003eExample (user):\u003cbr/\u003e`100000000`\u003cbr/\u003eExample (group):\u003cbr/\u003e`-100000000`\u003cbr/\u003e\u003cbr/\u003e*Required if target message was sent to a group or a channel.*                                                                                                                                                                                               |\n| `message`              | yes      | Message ID to edit.                                                                                                                                                                                                                                                                                                                                                                |\n| `text`                 | yes      | New message text.                                                                                                                                                                                                                                                                                                                                                                  |\n| `parse_mode`           | no       | Message parse mode. Could be either `html` or `markdown`.\u003cbr/\u003e\u003cbr/\u003e*Defaults to `plain text`.*                                                                                                                                                                                                                                                                                     |\n| `link_preview`         | no       | Enables previews for links in the message.                                                                                                                                                                                                                                                                                                                                         |\n| `file`                 | no       | Path or paths relative to `config` directory to send with a message.\u003cbr/\u003eExample (1 file):\u003cbr/\u003e`tts/ff5789a925ee97c09d1462a53b4416c21a26e128.mp3`\u003cbr/\u003eExample (2 files):\u003cbr/\u003e`[\"configuration.yaml\", \"secrets.yaml\"]`                                                                                                                                                              |\n| `force_document`       | no       | Attach file(s) as document(s) rather than image/audio/video.                                                                                                                                                                                                                                                                                                                       |\n| `keyboard`             | no       | Button, list of buttons or list of lists of buttons to show under the message.\u003cbr/\u003eExample (1 button):\u003cbr/\u003e`Accept`\u003cbr/\u003eExample (1 row of 2 buttons):\u003cbr/\u003e`[\"Yes\", \"No\"]`\u003cbr/\u003eExample (2 rows of 2 button each):\u003cbr/\u003e`[[\"Like\", \"Dislike\"], [\"Share\", \"Subscribe\"]]`                                                                                                               |\n| `inline_keyboard`      | no       | Button, list of buttons or list of lists of buttons to show under the message. Each button could be a dictionary with `text` and `data` keys.\u003cbr/\u003eExample (1 button):\u003cbr/\u003e`Agree`\u003cbr/\u003eExample (1 row of 2 buttons):\u003cbr/\u003e`[{\"text\": \"Accept\", \"data\": \"accept\"}, {\"text\": \"Decline\", \"data\": \"decline\"}]`\u003cbr/\u003eExample (2 rows of 2 button each):\u003cbr/\u003e`[[\"-1\", \"+1\"], [\"-5\", \"+5\"]]` |\n| `keyboard_resize`      | no       | Resizes keyboard to minimize space used.\u003cbr/\u003e\u003cbr/\u003e*Can be used only if `keyboard` is defined.*                                                                                                                                                                                                                                                                                     |\n| `keyboard_single_use`  | no       | Hides keyboard after user press any button.\u003cbr/\u003e\u003cbr/\u003e*Can be used only if `keyboard` is defined.*                                                                                                                                                                                                                                                                                  |\n| `supports_streaming`   | no       | Whether the sent video supports streaming or not.                                                                                                                                                                                                                                                                                                                                  |\n| `schedule`             | no       | Schedule message delivery.\u003cbr/\u003e\u003cbr/\u003e*Can be used only in `User` mode. Bots can't schedule message delivery.*                                                                                                                                                                                                                                                                       |\n\n### Service `telegram_client.delete_messages`\n\nDeletes previously sent messages to user, group, channel or bot.\n| Service data attribute | Optional | Description                                                                                                                                                                                                            |\n| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `config_entry_id`      | no       | Config entry ID to run service on.\u003cbr/\u003e\u003cbr/\u003e*Defaults to first one.*                                                                                                                                                   |\n| `target_username`      | no       | Username to delete message for.\u003cbr/\u003eExample (my saved messages):\u003cbr/\u003e`me`\u003cbr/\u003eExample (bot):\u003cbr/\u003e`BotFather`\u003cbr/\u003eExample (user):\u003cbr/\u003e`bigfoot`\u003cbr/\u003e\u003cbr/\u003e*Required if target message was sent to a group or a channel.* |\n| `target_id`            | no       | User/group ID to delete message for.\u003cbr/\u003eExample (user):\u003cbr/\u003e`100000000`\u003cbr/\u003eExample (group):\u003cbr/\u003e`-100000000`\u003cbr/\u003e\u003cbr/\u003e*Required if target message was sent to a group or a channel.*                                 |\n| `message_ids`          | yes      | Message ID(s) to delete.                                                                                                                                                                                               |\n| `revoke`               | no       | Deletes message from everyone.                                                                                                                                                                                         |\n\n## Events\n\n* `telegram_client_new_message` – [New message event](https://docs.telethon.dev/en/stable/modules/events.html#telethon.events.newmessage.NewMessage.Event)\n* `telegram_client_message_edited` – [Message edited event](https://docs.telethon.dev/en/stable/modules/events.html#telethon.events.messageedited.MessageEdited.Event)\n* `telegram_client_message_read` – [Message read event](https://docs.telethon.dev/en/stable/modules/events.html#telethon.events.messageread.MessageRead.Event)\n* `telegram_client_message_deleted` – [Message deleted event](https://docs.telethon.dev/en/stable/modules/events.html#telethon.events.messagedeleted.MessageDeleted.Event)\n* `telegram_client_callback_query` – [Callback query event](https://docs.telethon.dev/en/stable/modules/events.html#telethon.events.callbackquery.CallbackQuery.Event)\n* `telegram_client_inline_query` – [Inline query event](https://docs.telethon.dev/en/stable/modules/events.html#telethon.events.inlinequery.InlineQuery.Event)\n* `telegram_client_chat_action` – [Chat action event](https://docs.telethon.dev/en/stable/modules/events.html#telethon.events.chataction.ChatAction.Event)\n* `telegram_client_user_update` – [User update event](https://docs.telethon.dev/en/stable/modules/events.html#telethon.events.userupdate.UserUpdate.Event)\n\n## Sensors\n\n* `ID`\n* `Username`\n* `Last name` (for `User` mode)\n* `First name`\n* `Phone` (for `User mode`)\n\n## Binary sensors\n\n* `Restricted`\n* `Premium`\n\n## Automation examples\n\nBased on events described above you can create all sorts of automations.\n\n### Respond to a message from a specific user that matches pattern\n\n```yaml\nalias: Respond to a greeting message from mom\ntrigger:\n  - platform: event\n    event_type: telegram_client_new_message\n    event_data:\n      message:\n        from_id:\n          user_id: YOUR_MOM_TELEGRAM_USER_ID\ncondition:\n  - condition: template\n    value_template: \u003e-\n      {{ trigger.event.data.message.message | regex_match('hello', ignorecase=True) }}\naction:\n  - service: telegram_client.send_messages\n    data:\n      config_entry_id: \"{{ trigger.event.data.config_entry_id }}\"\n      message: Hello, mom!\n      target_id: \"{{ trigger.event.data.message.from_id.user_id }}\"\n```\n\n### Announce every edited message in specific chat\n\n```yaml\nalias: Blame \"Poker planing\" chat message editor\ntrigger:\n  - platform: event\n    event_type: telegram_client_message_edited\n    event_data:\n      chat_id: POKER_PLANNING_CHAT_ID\ncondition:\n  - condition: template\n    value_template: \u003e-\n      {{ trigger.event.data.message.from_id.user_id != trigger.event.data.me.id }}\naction:\n  - service: telegram_client.send_messages\n    data:\n      config_entry_id: \"{{ trigger.event.data.config_entry_id }}\"\n      message: You're not suppose to change your estimation!\n      target_id: \"{{ trigger.event.data.chat_id }}\"\n      reply_to: \"{{ trigger.event.data.message.id }}\"\n```\n\n### Delete latest message that was read by specific user\n\n```yaml\nalias: Secret chat with Bob\ntrigger:\n  - platform: event\n    event_type: telegram_client_message_read\n    event_data:\n      chat_id: BOBS_USER_ID\naction:\n  - delay:\n      seconds: 10\n  - service: telegram_client.delete_messages\n    data:\n      config_entry_id: \"{{ trigger.event.data.config_entry_id }}\"\n      message_ids: \"{{ trigger.event.data.max_id }}\"\nmode: restart\n\n```\n\n### Send response when user in specific chat clicks inline button\n\n```yaml\nalias: Respond to callback query\ntrigger:\n  - platform: event\n    event_type: telegram_client_callback_query\n    event_data:\n      sender_id: POKER_PLANNING_CHAT_ID\naction:\n  - service: telegram_client.send_messages\n    data:\n      config_entry_id: \"{{ trigger.event.data.config_entry_id }}\"\n      target_id: \"{{ trigger.event.data.chat_id }}\"\n      message: \u003e-\n        {{ trigger.event.data.sender.first_name }}, thanks for selecting \"{{ trigger.event.data.data }}\"!\n      reply_to: \"{{ trigger.event.data.message_id }}\"\n```\n\n### Send message when user joins specific group\n\n```yaml\nalias: Greet new joiner\ntrigger:\n  - platform: event\n    event_type: telegram_client_chat_action\n    event_data:\n      chat_id: CHAT_ID\n      user_joined: true\naction:\n  - service: telegram_client.send_messages\n    data:\n      config_entry_id: \"{{ trigger.event.data.config_entry_id }}\"\n      message: \u003e-\n        Welcome, {{ trigger.event.data.user.first_name }} {{ trigger.event.data.user.last_name }}!\n      target_id: \"{{ trigger.event.data.chat_id }}\"\n```\n\n### Send response when specific user is typing\n\n```yaml\nalias: Spy eye\ntrigger:\n  - platform: event\n    event_type: telegram_client_user_update\n    event_data:\n      user_id: BOBS_USER_ID\n      typing: true\naction:\n  - service: telegram_client.send_messages\n    data:\n      config_entry_id: \"{{ trigger.event.data.config_entry_id }}\"\n      message: Whats up, man?\n      target_id: \"{{ trigger.event.data.chat_id }}\"\n  - delay:\n      seconds: 30\nmode: restart\n```\n\n## Side note\n\nThis integration is based on Telethon library. It has complete documentation on all [methods](https://docs.telethon.dev/en/stable/modules/client.html#telethon.client.messages.MessageMethods) and [events](https://docs.telethon.dev/en/stable/modules/events.html) it can handle. So in case you are not sure what that or other method or event field is for, you can refer to official documentation.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flufton%2Fha_telegram_client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flufton%2Fha_telegram_client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flufton%2Fha_telegram_client/lists"}