From c8422c9fb8dd31cea18f64c5bd3ae8160b4203b0 Mon Sep 17 00:00:00 2001
From: Joost Lekkerkerker <joostlek@outlook.com>
Date: Thu, 26 Jun 2025 18:21:56 +0200
Subject: [PATCH] Improve explanation on how to get API token in Telegram
 (#147605)

---
 homeassistant/components/telegram_bot/config_flow.py | 6 +++++-
 homeassistant/components/telegram_bot/strings.json   | 5 ++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/homeassistant/components/telegram_bot/config_flow.py b/homeassistant/components/telegram_bot/config_flow.py
index d9b334a4ac1..67981cbd704 100644
--- a/homeassistant/components/telegram_bot/config_flow.py
+++ b/homeassistant/components/telegram_bot/config_flow.py
@@ -293,10 +293,15 @@ class TelgramBotConfigFlow(ConfigFlow, domain=DOMAIN):
     ) -> ConfigFlowResult:
         """Handle a flow to create a new config entry for a Telegram bot."""
 
+        description_placeholders: dict[str, str] = {
+            "botfather_username": "@BotFather",
+            "botfather_url": "https://t.me/botfather",
+        }
         if not user_input:
             return self.async_show_form(
                 step_id="user",
                 data_schema=STEP_USER_DATA_SCHEMA,
+                description_placeholders=description_placeholders,
             )
 
         # prevent duplicates
@@ -305,7 +310,6 @@ class TelgramBotConfigFlow(ConfigFlow, domain=DOMAIN):
 
         # validate connection to Telegram API
         errors: dict[str, str] = {}
-        description_placeholders: dict[str, str] = {}
         bot_name = await self._validate_bot(
             user_input, errors, description_placeholders
         )
diff --git a/homeassistant/components/telegram_bot/strings.json b/homeassistant/components/telegram_bot/strings.json
index a51d4a371f1..17b2e6f24d6 100644
--- a/homeassistant/components/telegram_bot/strings.json
+++ b/homeassistant/components/telegram_bot/strings.json
@@ -2,11 +2,10 @@
   "config": {
     "step": {
       "user": {
-        "title": "Telegram bot setup",
-        "description": "Create a new Telegram bot",
+        "description": "To create a Telegram bot, follow these steps:\n\n1. Open Telegram and start a chat with [{botfather_username}]({botfather_url}).\n1. Send the command `/newbot`.\n1. Follow the instructions to create your bot and get your API token.",
         "data": {
           "platform": "Platform",
-          "api_key": "[%key:common::config_flow::data::api_key%]",
+          "api_key": "[%key:common::config_flow::data::api_token%]",
           "proxy_url": "Proxy URL"
         },
         "data_description": {