Blog post for new MQTT subscribe wait option

[jbouwh]

Proposed change

Blog post for new MQTT subscribe wait option

Type of change

• Document existing features within Home Assistant
• Document new or changing features for which there is an existing pull request elsewhere
• Spelling or grammatical corrections, or rewording for improved clarity
• Changes to the backend of this documentation
• Remove stale or deprecated documentation

Checklist

• I have read and followed the documentation guidelines.
• I have verified that my changes render correctly in the documentation.

Additional information

• This PR fixes or closes issue: fixes #
• Link to relevant existing code or pull request: Allow to wait for MQTT subscription core#152994

Summary by CodeRabbit

• Documentation
  • Added a blog post detailing a new “wait” option for MQTT subscribe, enabling you to await broker-side subscription completion.
  • Includes practical examples: subscribing with wait enabled, performing actions safely after confirmation, and cleanly unsubscribing via the provided callback.
  • Clarifies default queued/debounced behavior versus explicit waiting, helping improve reliability for time-sensitive workflows.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds documentation for a new wait option to the MQTT async_subscribe API. The API now accepts wait: bool (default false) to optionally await broker-side subscription completion. The function returns a callback to unsubscribe. Example usage is included.

Changes

Cohort / File(s)	Summary
Documentation: MQTT subscribe wait option blog/2025-09-26-mqtt-subscribe-wait.md	New doc describing async_subscribe’s new wait parameter, default behavior vs. queued/debounced subscriptions, and example showing subscribe with wait=True and later unsubscribe via returned callback.
Public API declaration homeassistant.components.mqtt	Exported method updated: added async_subscribe(hass, topic, msg_callback, qos=DEFAULT_QOS, encoding=DEFAULT_ENCODING, wait: bool=False) -> CALLBACK_TYPE.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Client
  participant MQTT as MQTT Component
  participant Broker as MQTT Broker

  Client->>MQTT: async_subscribe(topic, callback, qos, encoding, wait=False)
  alt wait=False (default)
    note right of MQTT: Queue/debounce subscription
    MQTT-->>Client: return unsubscribe CALLBACK_TYPE
    MQTT->>Broker: Subscribe(topic) (async, not awaited)
    Broker-->>MQTT: SUBACK (later)
  else wait=True
    MQTT->>Broker: Subscribe(topic)
    Broker-->>MQTT: SUBACK
    MQTT-->>Client: return unsubscribe CALLBACK_TYPE
  end

  Client->>MQTT: Call unsubscribe callback
  MQTT->>Broker: Unsubscribe(topic)
  Broker-->>MQTT: UNSUBACK

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The PR description retains the template but the “Proposed change” section is only a one-line summary and lacks detail on what the blog post covers, the checklist items are all unchecked, and the “fixes #” entry is incomplete, so required template sections are not properly filled out.	Please expand the “Proposed change” section with a detailed summary of the blog post content, tick off the checklist items after verifying guidelines and rendering, and remove or complete the “This PR fixes or closes issue” entry if no issue is linked.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title clearly summarizes the primary change by indicating the addition of a blog post documenting the new MQTT subscribe wait option and directly relates to the content of the PR.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch mqtt-subscribe-wait

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 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

📥 Commits

Reviewing files that changed from the base of the PR and between 94701a2 and 2db8b0f.

📒 Files selected for processing (1)

• blog/2025-09-26-mqtt-subscribe-wait.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

*/**(html|markdown|md)

⚙️ CodeRabbit configuration file

*/**(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 the goal of the instruction is fronted.

• Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
• In step-by-step instructions, front the location phrase in the instructional sentence.
• In step-by-step instructions, front the 'goal' in the instructional sentence.
• In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
• do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'

*/**(html|markdown|md): - Use bold to mark UI strings.

• If "" are used to mark UI strings, replace them by bold.

• Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"

• Use sentence-style capitalization also in headings.

do not comment on HTML used for icons

Avoid flagging inline HTML for embedding videos in future reviews for this repository.

Files:

• blog/2025-09-26-mqtt-subscribe-wait.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Redirect rules - developers-home-assistant
• GitHub Check: Header rules - developers-home-assistant
• GitHub Check: Pages changed - developers-home-assistant