Update Pushover Documentation to add TTL and Resolve Issue 36584 #38808
Conversation
|
It seems that this PR is targeted against an incorrect branch since it has a parent PR on one of our codebases. Documentation that needs to be updated for an upcoming release should target the |
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe Pushover integration documentation for Home Assistant was extensively revised and expanded. The changes include a clearer description of the integration, a detailed table of all Pushover API parameters, updated configuration instructions, and enhanced automation examples. New sections explain advanced features such as message auto-deletion, priority handling (including emergency messages), multi-device targeting, and HTML message formatting. Visual aids and comprehensive templating examples were added to illustrate usage. No changes were made to code or exported entities; all modifications are limited to documentation content. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant HomeAssistant
participant PushoverAPI
User ->> HomeAssistant: Triggers automation (e.g., sends notification)
HomeAssistant ->> PushoverAPI: Sends notification with parameters (message, title, target, etc.)
PushoverAPI -->> HomeAssistant: Acknowledges receipt
HomeAssistant -->> User: (Optional) Confirms notification sent
sequenceDiagram
participant User
participant HomeAssistant
participant PushoverAPI
User ->> HomeAssistant: Triggers automation with HTML-formatted message and advanced parameters (priority, ttl, etc.)
HomeAssistant ->> PushoverAPI: Sends notification with advanced parameters
PushoverAPI -->> HomeAssistant: Processes according to priority, retry, expire, and formatting
HomeAssistant -->> User: (Optional) Updates status or logs result
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:
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 (
|
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
source/_integrations/pushover.markdown (3)
24-36: Enhance API parameters table for accuracy and consistency
- Update the
targetType to accept a list of strings (multi-device support).- In the
soundrow, replace curly quotes around “pushover” with backticks ( `pushover` ).- Optionally annotate the
ttlentry to note that it’s incompatible with emergency priority (2).🧰 Tools
🪛 LanguageTool
[uncategorized] ~35-~35: Possible missing comma found.
Context: ...ation period in seconds for priority 2 (maximum 10800 seconds). | | h...(AI_HYDRA_LEO_MISSING_COMMA)
38-55: Remove trailing spaces and extra blank lines
Lines 38, 55, and 79 contain trailing spaces, and there are consecutive blank lines at 40–41. Cleaning these up will resolve MD009 and MD012 warnings.Also applies to: 79-79
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
38-38: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
40-40: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
54-54: Fenced code blocks should be surrounded by blank lines
null(MD031, blanks-around-fences)
55-55: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
114-114: Hyphenate "1024-character limit"
When used as a compound modifier, add a hyphen:- up to the 1024 character limit + up to the 1024-character limit🧰 Tools
🪛 LanguageTool
[grammar] ~114-~114: When ‘1024-character’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...mic, html-formatted messages (up to the 1024 character limit), as in this example. {% raw %} ...(WORD_ESSAY_HYPHEN)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
source/images/integrations/pushover/html_example.jpgis excluded by!**/*.jpg
📒 Files selected for processing (1)
source/_integrations/pushover.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/pushover.markdown
[uncategorized] ~35-~35: Possible missing comma found.
Context: ...ation period in seconds for priority 2 (maximum 10800 seconds). | | h...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~79-~79: Possible missing comma found.
Context: ...after 6 hours. Also note that in this example the sound parameter is not explicitly s...
(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~114-~114: When ‘1024-character’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...mic, html-formatted messages (up to the 1024 character limit), as in this example. {% raw %} ...
(WORD_ESSAY_HYPHEN)
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/pushover.markdown
38-38: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
40-40: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
54-54: Fenced code blocks should be surrounded by blank lines
null
(MD031, blanks-around-fences)
55-55: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
77-77: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
180-180: Multiple top-level headings in the same document
null
(MD025, single-title, single-h1)
205-205: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (6)
source/_integrations/pushover.markdown (6)
17-17: Clear and concise introduction to Pushover integration
The added paragraph effectively explains prerequisites, links to relevant resources, and aligns with Home Assistant documentation style.
19-19: Proper inclusion of config flow snippet
Using{% include integrations/config_flow.md %}follows our standard pattern for config-flow integrations.
44-53: Verify YAML syntax for service call
Home Assistant examples typically useservice: notify.pushoverrather thanaction:. Please confirm thataction: notify.pushoveris intended or update to:- - action: notify.pushover + - service: notify.pushoverAlso double-check the nested
data:blocks and indentation.
62-71: Confirm service call in multi-device example
As above, replaceaction: notify.pushoverwithservice: notify.pushoverif that aligns with current automation syntax. Ensure the YAML list undertarget:is properly indented.
82-91: Validate YAML for auto-deleting example
Theaction:key appears again; standard usage isservice: notify.pushover. Please verify and adjust if necessary.
100-110: Verify priority example YAML syntax
Confirm whetheraction: notify.pushovershould beservice: notify.pushoverhere as well, to maintain consistency across examples.
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (1)
source/_integrations/pushover.markdown (1)
199-199:⚠️ Potential issueEnforce uppercase “URL” in voice integration
In the Voice Integration example, changeurl:toURL:for consistency with terminology standards.Example diff:
- url: "https://www.home-assistant.io/" + URL: "https://www.home-assistant.io/"
🧹 Nitpick comments (5)
source/_integrations/pushover.markdown (5)
38-38: Remove trailing space
This line has an extra trailing space. Please remove it to satisfy markdownlint rules (MD009).🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
38-38: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
43-54: Surround code fences with blank lines
Ensure fenced code blocks are preceded and followed by blank lines per markdownlint MD031. Add a blank line after the closingyamlat line 54.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
54-54: Fenced code blocks should be surrounded by blank lines
null(MD031, blanks-around-fences)
55-55: Remove trailing space
The sentence ends with an unnecessary trailing space. Remove it to comply with markdownlint rules (MD009).🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
55-55: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
🪛 GitHub Actions: home-assistant.io Test
[error] 55-55: Incorrect usage of the term: “url”, use “URL” instead (terminology)
77-77: Remove trailing space
There’s an extra space at the end of this line. Please remove to comply with markdownlint MD009.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
77-77: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
114-114: Hyphenate “1024-character”
When used as a modifier, this term should be hyphenated. Please apply:-(up to the 1024 character limit) +(up to the 1024-character limit)🧰 Tools
🪛 LanguageTool
[grammar] ~114-~114: When ‘1024-character’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...mic, html-formatted messages (up to the 1024 character limit), as in this example. {% raw %} ...(WORD_ESSAY_HYPHEN)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/pushover.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/pushover.markdown
[uncategorized] ~35-~35: Possible missing comma found.
Context: ...ation period in seconds for priority 2 (maximum 10800 seconds). | | h...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~79-~79: Possible missing comma found.
Context: ...after 6 hours. Also note that in this example the sound parameter is not explicitly s...
(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~114-~114: When ‘1024-character’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...mic, html-formatted messages (up to the 1024 character limit), as in this example. {% raw %} ...
(WORD_ESSAY_HYPHEN)
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/pushover.markdown
38-38: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
40-40: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
54-54: Fenced code blocks should be surrounded by blank lines
null
(MD031, blanks-around-fences)
55-55: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
77-77: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
205-205: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
🪛 GitHub Actions: home-assistant.io Test
source/_integrations/pushover.markdown
[error] 28-28: Incorrect usage of the term: “url”, use “URL” instead (terminology)
[error] 55-55: Incorrect usage of the term: “url”, use “URL” instead (terminology)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (6)
source/_integrations/pushover.markdown (6)
3-3: Approve updated description
The new description clearly states the integration’s purpose and usage.
17-17: Approve improved introduction
The expanded introduction provides clear context and helpful links.
19-19: Approve config flow include
Integrating the standard config flow include aligns with Home Assistant documentation guidelines.
57-71: Approve multi-device example
The section clearly explains multi-device targeting with proper YAML formatting.
100-104: Approve emergency priority example
The YAML example correctly demonstrates settingpriority,retry, andexpireparameters for an emergency message.
23-37:⚠️ Potential issueEnforce uppercase “URL” in API parameters table
The table currently listsurlandurl_titlein lowercase. According to terminology standards, use uppercase “URL” consistently.Apply this diff:
-| url | string | no | URL to show as a clickable link. | -| url_title | string | no | Text to display for the link. | +| URL | string | no | URL to show as a clickable link. | +| URL title | string | no | Text to display for the link. |Likely an incorrect or invalid review comment.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~35-~35: Possible missing comma found.
Context: ...ation period in seconds for priority 2 (maximum 10800 seconds). | | h...(AI_HYDRA_LEO_MISSING_COMMA)
🪛 GitHub Actions: home-assistant.io Test
[error] 28-28: Incorrect usage of the term: “url”, use “URL” instead (terminology)
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (5)
source/_integrations/pushover.markdown (5)
67-75: Duplicate: replaceaction:withservice:
Same issue as above—useservice: notify.pushoverinstead ofaction:in this example.
87-96: Duplicate: replaceaction:withservice:and trim whitespace
- Use
service: notify.pushoverhere as well.- There is trailing whitespace after
ttl: 21600; consider:- ttl: 21600 + ttl: 21600
105-115: Duplicate: replaceaction:withservice:
Ensure consistency across all examples by usingservice: notify.pushover.
185-185: Use correct header level for Voice Integration
Change# Voice Integrationto## Voice Integrationto maintain a single H1 in the document.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
185-185: Multiple top-level headings in the same document
null(MD025, single-title, single-h1)
124-172:⚠️ Potential issueDuplicate: replace
action:withservice:and verify HTML support
- As above, change all
- action: notify.pushoverto- service: notify.pushover.- Pushover’s HTML support is limited to a small set of tags (
<b>,<i>,<u>,<strong>,<em>,<a>,<br>). The<font>tag withcolorattributes may not render. Please verify the allowed HTML tags and update this example accordingly.
🧹 Nitpick comments (2)
source/_integrations/pushover.markdown (2)
17-17: Consider simplifying redundant phrasing
The phrase "send messages or notifications" could be streamlined to just "send notifications" for clarity.
23-38: Clarify parameter types
- The
targetfield accepts a single string or a list of strings; consider updating the Type column accordingly (e.g.,string or list).- The
htmlparameter requires a numeric value (1or0) rather than a boolean; consider changing its Type tointeger.🧰 Tools
🪛 LanguageTool
[uncategorized] ~36-~36: Possible missing comma found.
Context: ...ation period in seconds for priority 2 (maximum 10800 seconds). | | h...(AI_HYDRA_LEO_MISSING_COMMA)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/pushover.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/pushover.markdown
[uncategorized] ~36-~36: Possible missing comma found.
Context: ...ation period in seconds for priority 2 (maximum 10800 seconds). | | h...
(AI_HYDRA_LEO_MISSING_COMMA)
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/pushover.markdown
185-185: Multiple top-level headings in the same document
null
(MD025, single-title, single-h1)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (3)
source/_integrations/pushover.markdown (3)
3-3: Metadata description looks good
Concise and clear summary of the Pushover integration.
19-19: Config flow include is appropriate
Using the sharedconfig_flow.mdinclude aligns with other integrations.
21-21: Heading level is consistent
Using an H2 for the API parameters section correctly follows the frontmatter title.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
source/_integrations/pushover.markdown (1)
185-185: Use proper header level for section
The "Voice Integration" section is marked using a single#. For consistency and to avoid multiple top-level headings, change it to## Voice Integration.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
185-185: Multiple top-level headings in the same document
null(MD025, single-title, single-h1)
🧹 Nitpick comments (2)
source/_integrations/pushover.markdown (2)
28-28: Clarifytargetparameter type
The table liststargetas Type:string, but it also supports a list of device names. Consider updating the Type column tostring or listto accurately reflect multi-device usage.
105-114: Consistent YAML indentation
In this priority example, the initial dash (- service: notify.pushover) aligns with column 1. For consistency with other snippets, consider indenting it the same way (e.g., two spaces before the dash).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/pushover.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/pushover.markdown
[uncategorized] ~36-~36: Possible missing comma found.
Context: ...ation period in seconds for priority 2 (maximum 10800 seconds). | | h...
(AI_HYDRA_LEO_MISSING_COMMA)
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/pushover.markdown
185-185: Multiple top-level headings in the same document
null
(MD025, single-title, single-h1)
🔇 Additional comments (3)
source/_integrations/pushover.markdown (3)
47-57: Basic example snippet looks good
The YAML syntax and indentation correctly demonstrate how to callnotify.pushoverwith optional parameters.
67-76: Multi-device example is accurate
The sample correctly shows using a YAML list for multipletargetdevices and is clear for end users.
87-96: TTL example is clear
Thettlusage is correctly demonstrated with a self-delete timeline.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
source/_integrations/pushover.markdown (2)
84-84: Grammar nitpick: missing comma
Consider adding a comma after “after 6 hours” for clarity:“…the message will self-delete from the targeted device(s) after 6 hours, also note that in this example…”
🧰 Tools
🪛 LanguageTool
[uncategorized] ~84-~84: Possible missing comma found.
Context: ... after 6 hours. Also note that in this example the sound parameter is not explicitly s...(AI_HYDRA_LEO_MISSING_COMMA)
123-172: Dynamic HTML templating example: readability suggestion
This is a comprehensive example, but the long inline templating block could be split or collapsed for readability. Also, ensuremetadata: {}is documented in the API table if required for attachments.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/pushover.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/pushover.markdown
[uncategorized] ~84-~84: Possible missing comma found.
Context: ... after 6 hours. Also note that in this example the sound parameter is not explicitly s...
(AI_HYDRA_LEO_MISSING_COMMA)
🔇 Additional comments (9)
source/_integrations/pushover.markdown (9)
3-3: Description header clarity
The newdescriptionfield succinctly explains the integration.
17-17: Introduction paragraph is clear and informative
This succinctly covers the Pushover integration, API key requirement, and linking to notifications docs.
19-19: Correct inclusion of config flow snippet
Using{% include integrations/config_flow.md %}aligns with other integrations’ documentation patterns.
21-21: Appropriate heading for API parameters
The## Pushover API Parametersheading properly introduces the parameter table.
47-56: Example automation action is accurate
The YAML correctly usesservice: notify.pushoverwith nesteddata, matching Home Assistant conventions.
67-76: Multi-device targeting example looks good
Demonstrates list syntax and notes acceptable UI formatting.
87-95: Auto-deleting messages snippet is correct
YAML indentation and the use ofttlalign with the API specification.
105-115: Emergency priority example is accurate
The snippet correctly showspriority: 2with mandatoryretryandexpire; indentation matches other examples.
185-189: Voice integration example is clear
Usingservice: notify.pushoverunder the Alexaactionblock correctly demonstrates an intent-based call. Examples are consistent and showcase templating effectively.Also applies to: 198-207, 209-209
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
source/_integrations/pushover.markdown (3)
23-38: Clarifytargetfield type in the parameters table
The table liststargetas a list, but examples also accept a single string. Consider updating the Type column tostring or listfor consistency and clarity:-| target | list | no | List of Pushover devices to receive message. | +| target | string or list | no | List of Pushover devices to receive the message (single device or list of devices). |🧰 Tools
🪛 LanguageTool
[uncategorized] ~36-~36: Possible missing comma found.
Context: ...ation period in seconds for priority 2 (maximum 10800 seconds). | | h...(AI_HYDRA_LEO_MISSING_COMMA)
105-105: Ensure consistent indentation in examples
This block starts- service: notify.pushoverat the margin, whereas other snippets indent list items by two spaces. For uniformity, align all action/service snippets to the same indentation level.
109-109: Maintain consistenttargetusage
Heretargetis a plain string (iphone11pro); consider using a one-element list (target: ["iphone11pro"]) to match the updated table’sstring or listtype.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/pushover.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/pushover.markdown
[uncategorized] ~36-~36: Possible missing comma found.
Context: ...ation period in seconds for priority 2 (maximum 10800 seconds). | | h...
(AI_HYDRA_LEO_MISSING_COMMA)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (13)
source/_integrations/pushover.markdown (13)
3-3: Approve thedescriptionfrontmatter entry
The description succinctly and accurately summarizes the integration’s purpose.
17-17: Approve the integration overview paragraph
The introduction provides a clear, concise explanation of Pushover integration and setup requirements.
19-19: Approve inclusion of config flow snippet
Using{% include integrations/config_flow.md %}aligns with other integrations and keeps this doc DRY.
21-21: Approve the API parameters section heading
The## Pushover API Parametersheader clearly introduces the detailed parameter table.
47-51: Approve example automation action top-level fields
The example correctly demonstrates invokingservice: notify.pushoverwithmessage,title, andtarget.
53-56: Approve example nesteddataparameters
The URL, URL title, sound, and attachment fields are well-illustrated under the nesteddata:block.
67-71: Approve multiple-devices example top-level keys
Demonstratingtarget:as a YAML list clearly shows how to address multiple devices.
72-73: Approve list items intarget
The individual device entries (- pixel9,- johnsmith) are correctly formatted.
75-75: Approve nested sound parameter for multiple devices
Thesound: spacealarmexample under thedata:block is correct.
87-95: Approve auto-delete (ttl) example
This snippet accurately shows TTL usage (21600 seconds = 6 hours) and aligns with the API behavior.
119-119: Approve dynamic messaging introduction
The description of thehtml: 1parameter and templating usage is clear and accurate.
121-171: Approve comprehensive HTML templating example
The raw block and Jinja logic effectively showcase advanced HTML-formatted notifications. It’s lengthy but valuable for power users.
197-197: Approve voice integration example
Usingaction:in the Alexa intent context is correct (distinct from automation’sservice:). The snippet accurately reflects how to call the notify service from an Alexa intent.
Update pushover documentation to incorporate changes proposed in PR 143791, resolve issue 36584 , and add additional supporting references and examples.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
Summary by CodeRabbit