Summary

Matrix plugin does not send the m.mentions field when @mentioning users, so mentioned users receive no notification in Matrix clients.

Problem to solve

When sending a message that @mentions a user (e.g. @username), the Matrix room event is sent without the m.mentions field, so the homeserver doesn't notify the mentioned user.

Current outgoing event format (incorrect):

{
  "type": "m.room.message",
  "sender": "@bot:matrix.custom.com",
  "content": {
    "msgtype": "m.text",
    "body": "@ciao test",
    "format": "org.matrix.custom.html",
    "formatted_body": "<p>@ciao test</p>"
  }
}

Expected format (per Matrix spec):

{
  "type": "m.room.message",
  "sender": "@bot:matrix.custom.com",
  "content": {
    "msgtype": "m.text",
    "body": "@ciao test",
    "format": "org.matrix.custom.html",
    "formatted_body": "<p><span data-mention=\"@ciao:matrix.custom.com\">@ciao</span> test</p>",
    "": {
      "user_ids": ["@ciao:matrix.custom.com"]
    }
  }
}

The m.mentions field with user_ids array is the standard Matrix mechanism for notifying mentioned users. Without it, Element and other Matrix clients do not highlight or notify the mentioned user.

Root cause

In buildTextContent() (dist/auth-profiles-*.js, line ~56749), the function constructs the MatrixTextContent object but never populates the m.mentions field, even when the message body contains @username mentions.

The TextualMessageEventContent type in the plugin SDK does define m.mentions:

// dist/plugin-sdk/extensions/matrix/src/matrix/sdk/types.d.ts
export type MessageEventContent = {
  ...
  "m.mentions"?: {
    user_ids?: string[];
    room?: boolean;
  };
  [key: string]: unknown;
};

So the type exists but is simply never populated at send time.

Environment

Core OpenClaw: v2026.3.28
Matrix plugin (bundled): v2026.3.28
Homeserver: (v1.149.1)
Client: Element

Proposed solution

buildTextContent() should:

1. Parse the body string for @username patterns
2. Resolve each to a Matrix user ID (e.g. @ciao:matrix.custom.com)
3. Populate content["m.mentions"] = { user_ids: [...] } before sending

Additionally, formatted_body HTML should use tags so that non-pluralized clients also render the mention correctly.

Alternatives considered

No response

Impact

Normal (nice-to-have for proper Matrix spec compliance)

Evidence/examples

No response

Additional information

No response