Skip to content

Matrix Message Full Semantics

This page is the complete reference for the matrix_message tool. The model-facing tool description is a condensed summary of these semantics.

Send, reply, react to, read, edit, or inspect Matrix messages using current room and thread context defaults.

Actions

  • send: Send text and optional attachments to a room. It defaults to the current room. When the effective target is room-level, text+attachment sends post the text to the room timeline and thread attachments under that text event. When the effective target is room-level and you send multiple attachments without text, the first attachment is posted to the room timeline and the remaining attachments are threaded under it. In thread_mode: room, room-level sends stay plain room messages and do not auto-thread attachments unless you pass an explicit thread_id.
  • reply: Send text and optional attachments into a thread. It defaults to the current thread when one can be resolved and errors if no thread is available.
  • thread-reply: Same threading behavior as reply, kept as a separate action name for agent convenience.
  • react: React to target with message as the emoji, defaulting to thumbs-up when message is empty.
  • read: Read recent messages from the current thread when one is active, otherwise from the room timeline. An edited message is reported once, at its newest revision, with event_id naming the original and latest_event_id naming the revision on screen. A room-timeline read still asks the homeserver for limit raw events, so a heavily edited stretch of the room returns fewer than limit messages. A room-timeline read whose window holds a revision but not the message it revises cannot tell where that message lives, and reports thread_id_unknown instead of a thread.
  • room-threads: List thread roots in a room with pagination support via page_token.
  • thread-list: List messages in a thread and include edit options keyed by event ID. It uses the current thread when one is active, otherwise you must pass thread_id.
  • edit: Edit a previously sent message identified by target. The required target selects the event; current thread context does not select or validate the edit target.
  • context: Return room, thread, reply target, requester, and agent metadata so you can plan a later tool call.

Thread targeting

  • send is room-level by default even if the current conversation is inside a thread.
  • send only creates a new attachment thread when its effective thread target is room-level. If you pass an explicit thread_id, both text and attachments stay in that existing thread.
  • thread_mode: room disables implicit attachment auto-threading for room-level sends. Pass an explicit thread_id when you intentionally want threaded output from the tool.
  • reply and thread-reply inherit the current thread when possible.
  • read and context also inherit the current thread when possible.
  • thread_id="room" is a sentinel meaning "force room-level scope and do not inherit the current thread." Use it when you want the room timeline instead of the active thread.

Mention handling with ignore_mentions

  • This flag only affects text sends for send, reply, and thread-reply.
  • Default True: the tool writes com.mindroom.skip_mentions=True into the outgoing event content. The bot runtime checks that flag and suppresses mention-triggered agent dispatch, so visible mentions do not page agents.
  • False: the tool does not set the skip flag, so normal mention handling stays active. When the requester is a human rather than the sending bot, the tool also writes com.mindroom.original_sender=<human requester id>, not the bot ID. Downstream authorization and reply-permission checks then treat the event as coming from the original human requester.
  • self-trigger: an agent can mention itself with ignore_mentions=False to intentionally create a new turn. Use the same pattern for deliberate cross-agent handoffs when another agent should actually wake up and respond.

Safety

  • The default ignore_mentions=True exists to prevent accidental infinite loops and noisy mutual paging between agents.
  • Set ignore_mentions=False only for intentional dispatch. Prefer one deliberate handoff message over repeated self-mentions or agent-to-agent pings.
  • Direct send, reply, thread-reply, and edit calls reject interactive prompt blocks; use normal agent response delivery for interactive prompts.
  • Calls are limited to 12 weighted actions per 30 seconds for each agent, requester, and room combination. Each call costs one action, and each attachment on send, reply, or thread-reply costs one additional action.

Attachments

  • Attachments are only supported for send, reply, and thread-reply.
  • attachment_ids are context-scoped att_* IDs.
  • attachment_file_paths are local file paths that will be registered into the current attachment context before sending. Relative paths resolve from the agent workspace, the same root used as HOME in worker-routed tools.
  • The combined limit of attachment_ids plus attachment_file_paths is 5 per call.
  • A send or reply call may include text, attachments, or both, but not neither.

Message extras

  • message_extras adds collapsible MindRoom sections to send, reply, thread-reply, and edit events.
  • message_extras requires a non-empty message; attachment-only sends with extras are rejected.
  • Keep the visible message brief; put supporting evidence in extras.
  • Each section has title, content, optional content_type, and optional collapsed.
  • At most 8 sections are accepted; each title must be non-empty and at most 120 characters, and each content value may contain at most 16,384 characters.
  • collapsed must be a boolean and defaults to true.
  • Supported content_type values are text/plain, text/markdown, and text/html; default is text/markdown.
  • HTML content may use sanitized rich fragments: paragraphs, headings, lists, tables, blockquotes, code/pre blocks, basic inline formatting, and links. Do not include scripts, styles, images, forms, media, SVG/math, or interactive elements; links should use http, https, or mailto.
  • Example: message_extras=[{"title": "Evidence", "content_type": "text/html", "content": "<table><tr><td>42</td></tr></table>", "collapsed": true}].

Arguments

  • action (str): Supported actions are send, reply, thread-reply, react, read, room-threads, thread-list, edit, and context; they send text or attachments, react to an event, read messages, list room thread roots or thread messages, edit a prior event, or return targeting metadata.
  • message (str | None): Text body for send, reply, thread-reply, and edit; reaction emoji for react with a thumbs-up default when empty; use None for read, room-threads, thread-list, and context.
  • attachment_ids (list[str] | None): Context-scoped att_* attachment IDs; only valid for send, reply, and thread-reply, and the combined total with attachment_file_paths cannot exceed 5.
  • attachment_file_paths (list[str] | None): Local file paths to register and send in the current context; relative paths resolve from the agent workspace. It is only valid for send, reply, and thread-reply, and the combined total with attachment_ids cannot exceed 5.
  • room_id (str | None): Optional target room ID or alias; defaults to the current room context when omitted.
  • target (str | None): Event ID to react to for react or to edit for edit.
  • thread_id (str | None): Optional explicit thread target; thread_id="room" forces room-level scope instead of inheriting the current thread.
  • ignore_mentions (bool): Text-send safety flag for send, reply, and thread-reply; default True writes com.mindroom.skip_mentions=True to suppress mention-triggered agent dispatch, while False keeps mentions active and also writes com.mindroom.original_sender=<human requester id> when the requester is not the sending bot.
  • message_extras (list[dict[str, object]] | None): Optional collapsible MindRoom sections for supporting evidence. Each section supports title, content, content_type (text/plain, text/markdown, or sanitized text/html), and collapsed.
  • limit (int | None): Maximum messages returned for read or thread-list, or thread roots returned for room-threads; values are clamped to 1-50 and default to 20 when omitted.
  • page_token (str | None): Pagination token for room-threads, returned by a previous room-threads call to fetch the next page of thread roots.