Update docs for telegram bot for new config flow - #39341
Conversation
home-assistant
Bot
added
in-progress
|
It seems that this PR is targeted against an incorrect branch. Documentation updates which apply to our current stable release should target the |
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
home-assistant
Bot
added
has-parent
|
@MartinHjelmare please review the docs, thanks! |
📝 WalkthroughWalkthroughThe documentation for the Telegram bot integration was consolidated and extensively revised. The previously separate documentation files for the broadcast, polling, and webhook platforms were removed, and a single, comprehensive guide was created. This unified documentation introduces a new configuration flow, clarifies platform distinctions, adds detailed setup instructions, and introduces a new Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant HomeAssistant
participant TelegramBot
participant TelegramAPI
User->>HomeAssistant: Start Telegram Bot integration setup
HomeAssistant->>User: Prompt for platform selection (Broadcast, Polling, Webhooks)
User->>HomeAssistant: Provide API key, platform, and options
HomeAssistant->>TelegramAPI: Register bot (setWebhook if Webhooks)
TelegramAPI-->>HomeAssistant: Confirmation
HomeAssistant->>User: Prompt to whitelist chat IDs
User->>HomeAssistant: Add chat IDs
HomeAssistant->>User: Integration setup complete
Note over HomeAssistant,TelegramBot: On notification action
User->>HomeAssistant: Call action (e.g., send_message) with optional config_entry_id
HomeAssistant->>TelegramBot: Route action to specified bot instance
TelegramBot->>TelegramAPI: Send message or perform action
TelegramAPI-->>TelegramBot: Response
TelegramBot-->>HomeAssistant: Action result
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🧰 Additional context used📓 Path-based instructions (6)`*/**(html|markdown|md)`: - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure t...
`*/**(html|markdown|md)`: - Use bold to mark UI strings. - If "" are used to mark UI strings, replace them by bold.
`*/**(html|markdown|md)`: - Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
`*/**(html|markdown|md)`: - Use sentence-style capitalization also in headings.
`*/**(html|markdown|md)`: do not comment on HTML used for icons
`*/**(html|markdown|md)`: Avoid flagging inline HTML for embedding videos in future reviews for this repository.
🔇 Additional comments (2)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
MartinHjelmare
changed the title
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
source/_integrations/telegram_bot.markdown (1)
148-154: Consistentconfig_entry_idaddition across actions
You’ve added theconfig_entry_idrow in each action table. Ensure the phrasing and table alignment remain identical for every entry.Also applies to: 174-181, 199-206, 225-233, 250-256, 275-283, 301-309, 320-328, 338-346, 353-358, 366-370, 378-382, 389-392, 399-401
🧹 Nitpick comments (6)
source/_integrations/telegram_bot.markdown (6)
15-16: Clarify introduction wording
The new sentence explains what this integration does, but consider tightening the phrasing. For example:
“Use this integration to send, edit, and receive messages via a Telegram Bot in Home Assistant.”
36-45: Prerequisites section completeness
The “Create Telegram bot” and webhook connectivity subsections cover the needed steps. Consider adding a note about bot permissions (e.g., enabling privacy mode) if relevant.
100-108: Document Subentries for allowlisting chat IDs
The new “Allowlisting chat IDs via Subentries” section is helpful. Consider adding a link to the community forum or example automation for retrieving IDs, beyond just the upstream/integrations/telegramanchor.
110-113: Allowlist configuration table formatting
The table for Chat ID looks good. You may want to explicitly note whether negative IDs (groups) are supported here, as in other docs.
115-119: Introduce newconfig_entry_idattribute
Great overview of the notification actions and mention ofconfig_entry_id. Perhaps call out that it defaults to the first entry when only one bot is configured.
125-134: Enhanceconfig_entry_iddescription insend_message
The new row is necessary, but clarify default behavior. For example:-| `config_entry_id` | yes | The config entry representing the Telegram bot to send the message. Required if you have multiple Telegram bots.| +| `config_entry_id` | yes | The config entry representing the Telegram bot to use. Required when multiple bots are configured; defaults to the first entry when only one is present.|
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
source/_integrations/telegram_bot.markdown(17 hunks)
🔇 Additional comments (8)
source/_integrations/telegram_bot.markdown (8)
8-8: Addha_config_flowmetadata flag
Theha_config_flow: trueline correctly signals support for the new config flow. Ensure this aligns with the integration manifest in the core PR and that the flag is properly documented in the metadata reference.
17-21: Consolidate platform introduction
Good call on adding a unified “Introduction – Telegram bot platforms” section. You might merge lines 19–20 into a single sentence for brevity. Otherwise, this reads clearly.
22-35: Review platform sub‐sections for consistency
The Broadcast, Polling, and Webhooks descriptions are clear. Double-check that the level-3 headings (###) match the style guide and that each module’s prerequisites are linked (e.g., link to polling docs if available).
50-69: Verify reverse proxy and direct HTTPS instructions
The reverse proxy and direct exposure steps look correct. Please ensure the IP and proxy examples align with the HTTP integration docs, and confirm thatuse_x_forwarded_forguidance reflects the current defaults.
70-79: Use ofconfig_flow.mdinclude
Great use of the standardintegrations/config_flow.mdinclude. This ensures consistency across integrations. No further action needed here.
81-89: Webhooks configuration snippet
The additional configuration options for webhooks (URL, trusted networks) are clear. Verify that the indentation and parameter order match other integrations’ examples.
91-98: Options flow for default parse mode
Including parse mode in the options flow is a nice touch. Confirm that the allowed values (markdown,markdownv2,html) match the API client’s implementation.
759-765: Standard removal instructions
The “Removing the integration” section correctly points to the standard removal include. This aligns with other integrations and needs no extra steps.
There was a problem hiding this comment.
I forgot: We should probably add redirects for the deleted pages to the main telegram bot page.
Here's an example:
home-assistant.io/source/_redirects
Line 33 in 146606e
|
added the redirects. |
home-assistant
Bot
removed
parent-merged
2 participants
Proposed change
Preview: https://deploy-preview-39341--home-assistant-docs.netlify.app/integrations/telegram_bot/
telegram_broadcast,telegram_pollingandtelegram_webhookspages since all these are combined.Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
config_entry_idoption for all notification actions, allowing users to specify which bot instance to use.