Update Matrix integration docs for new features #39646
Conversation
|
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. |
📝 WalkthroughWalkthroughThe Matrix integration documentation was updated to introduce support for triggering commands via emoji reactions on messages. This includes a new Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant MatrixBot
participant Automation
User->>MatrixBot: Reacts to a message with 👍
MatrixBot->>Automation: Emits matrix_command event (command: thumbsup)
Automation->>MatrixBot: Sends threaded reply acknowledging reaction
sequenceDiagram
participant User
participant MatrixBot
participant Automation
User->>MatrixBot: Sends "!testword" command
MatrixBot->>Automation: Emits matrix_command event (command: testword)
Automation->>MatrixBot: Adds ✅ reaction to original message
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 (
|
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
source/_integrations/matrix.markdown (2)
129-130: Consider quoting emoji literals
To ensure compatibility across all YAML parsers, wrap the emoji in quotes.- reaction: "👍"
273-276: Refine wording for clarity
In the “Replying in threads” section, replace “inside of a thread” with “inside a thread” in both occurrences to eliminate redundancy.
📜 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/matrix.markdown(6 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/matrix.markdown
[style] ~273-~273: This phrase is redundant. Consider using “inside”.
Context: ...he received message. If the message was inside of a thread, the event will also contain a...
(OUTSIDE_OF)
[style] ~276-~276: This phrase is redundant. Consider using “inside”.
Context: ...e root message of the thread. To reply inside of a thread, pass the correct message iden...
(OUTSIDE_OF)
🔇 Additional comments (8)
source/_integrations/matrix.markdown (8)
55-55: Approve minor formatting change
Enclosing the default homeserver URL in<...>correctly creates a clickable link in the docs.
75-77: Approve updated “word” key documentation
The description, required flag, and type for thewordcommand key are clear and consistent with existing entries.
80-82: Approve updated “expression” key documentation
The regex-based command example is well-described and follows the same pattern as other command keys.
83-85: Approve new “reaction” key in schema
Adding thereactionkey with a concise description correctly documents emoji-triggered commands.
138-139: Approve automation alias rename
Changing the alias to “Respond to !testword” matches the updated “handle” semantics.
149-150: Approve automation alias rename
Updating the alias to “Respond to an introduction” maintains consistent terminology.
173-185: Approve emoji reaction action example
Thematrix.reactaction with a ✅ reaction is correctly formatted and clearly demonstrates usage.
191-193: Approve updated summary bullet
The new bullet accurately describes listening for emoji reactions and responding in threads.
source/_integrations/matrix.markdown
Outdated
| - alias: "Respond to a reaction in a thread" | ||
| triggers: | ||
| - trigger: event | ||
| event_type: matrix_command | ||
| event_data: | ||
| command: thumbsup | ||
| actions: | ||
| - action: notify.matrix_notify | ||
| data: | ||
| message: "I saw that {{trigger.event.data.args['reaction']}} -- glad you appreciated this!" | ||
| data: | ||
| thread_id: "{{trigger.event.data.thread_parent | default(trigger.event.data.event_id)}}" | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Document reaction event data
The “Event data” section above covers word and expression commands but omits reaction triggers. Please add details (e.g., that data.args['reaction'] contains the emoji) under “### Event data.”
🤖 Prompt for AI Agents
In source/_integrations/matrix.markdown around lines 160 to 172, the
documentation lacks details about reaction event data for matrix_command
triggers. Add a section under "### Event data" explaining that for reaction
triggers, data.args['reaction'] contains the emoji used in the reaction. This
will clarify how reaction events are represented and used in triggers.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
source/_integrations/matrix.markdown (1)
274-277: Remove redundant “inside of” phrasing
Simplify wording by replacing “inside of a thread” with “in a thread” for conciseness.- If the message was inside of a thread, `thread_parent` will be the identifier of the root message of the thread. If it is not inside of a thread, `thread_parent` will be the same as `event_id`. + If the message was in a thread, `thread_parent` will be the identifier of the root message. If it is not in a thread, `thread_parent` will be the same as `event_id`.
📜 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/matrix.markdown(6 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/matrix.markdown
[style] ~274-~274: This phrase is redundant. Consider using “inside”.
Context: ...ssage of the thread. If the message was inside of a thread, thread_parent will be the i...
(OUTSIDE_OF)
[style] ~275-~275: This phrase is redundant. Consider using “inside”.
Context: ...oot message of the thread. If it is not inside of a thread, thread_parent will be the s...
(OUTSIDE_OF)
[style] ~277-~277: This phrase is redundant. Consider using “inside”.
Context: ...ll be the same as event_id. To reply inside of a thread, pass the correct message iden...
(OUTSIDE_OF)
⏰ 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 (12)
source/_integrations/matrix.markdown (12)
55-57: Clarify default homeserver URL formatting
Enclosing the default Matrix homeserver URL in angle brackets improves readability and prevents YAML parsing issues.
75-75: Improve word command description clarity
The updated description clearly explains how thewordkey is used to trigger commands.
79-81: Enhance expression command schema
Addingrequired: falseand thetype: stringfor theexpressionkey completes the schema definition.
82-85: Introducereactionkey in commands schema
Documenting thereactionoption aligns the schema with the new feature for emoji-triggered commands.
129-130: Add example for reaction-triggered command
Including the 👍 reaction command in the sample configuration demonstrates the newreactionkey in action.
138-138: Update alias label to “Respond to”
Changing “React to !testword” to “Respond to !testword” better reflects the action taken in the automation.
149-149: Consistent alias wording for introduction
Aligns the introduction automation’s alias with the updated “Respond to” phrasing.
160-172: Add threaded reaction automation example
The new automation shows how to reply in the correct thread usingthread_parent, illustrating the threaded reply feature.
173-185: Add emoji reaction automation example
Documenting thematrix.reactaction withreaction,room, andmessage_idparameters clarifies how to programmatically react to a message.
191-193: Update overview bullets to include reactions
Reflects the new behavior in the high-level summary, ensuring the documentation matches the examples.
270-288: Document replying in threads section
This new section clearly explains how to usethread_parentto send replies in Matrix threads.
289-299: Document reacting to messages section
The “Reacting to messages” section provides clear instructions and a complete example for using thematrix.reactaction.
Proposed change
This PR adds documentation to the Matrix integration page that relates to my PR to core adding some new functionality to the integration.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
Summary by CodeRabbit