7.0 KiB
Matrix Formatting Capabilities Reference
Purpose: This document describes all available Matrix message formatting, styling, and interaction features available through the bridge. As an agent, you can use these features intentionally to express tone, emphasis, structure, and create rich interactions.
Core Message Formatting
Basic Markdown
Available in all responses:
| Syntax | Effect | Example → Output |
|---|---|---|
**text** |
Bold | **important** → important |
*text* |
Italic | *emphasis* → emphasis |
~~text~~ |
Strikethrough | ~~draft~~ → |
`text` |
Inline code | `variable` → variable |
```code block``` |
Code block | Creates formatted code box |
[text](url) |
Link | [click here](https://example.com) |
Lists
- Item 1
- Item 2
1. First
2. Second
Headers (converted to bold for conversational flow)
# Header → **Header**
## Subheader → **Subheader**
Matrix-Specific Extensions
Colors {color|text}
Use named colors or hex codes to highlight text.
{red|urgent message}
{blue|information}
{green|success}
{purple|mysterious}
{hot_pink|salient}
{#FF5733|custom hex}
Available palette:
red, orange, yellow, green, cyan, blue, purple, pink, hot_pink, white, gray
Usage tip: Use sparingly for emphasis, not for entire messages.
Spoilers ||text||
Hidden content that requires user interaction to reveal.
This is a spoiler ||the butler did it||
Use for:
- Plot reveals
- Sensitive content warnings
- "Click to read more" sections
Chromatophore Tag [chromatophore]
Activates automatic salience highlighting based on keywords.
[chromatophore] This is **fascinating** and critical information!
Effect: Automatically colors words like "fascinating", "critical", "important", etc.
Keywords affected:
- Critical/urgent: emergency, danger, threat, severe, critical
- Salient/emotional: fascinating, amazing, incredible, profound, love, fear
- Important: should, must, need, priority, crucial, essential
- Informational: is, was, could, perhaps, possible
Use when: You want emotional emphasis without manual color tags.
Can omit: For calm, neutral, direct communications.
Emoji Shortcodes
Use text-based emoji emojis for consistent rendering.
Common ones:
:heart: → ❤️
:star: → ⭐
:fire: → 🔥
:brain: → 🧠
:thinking: → 🤔
:eyes: → 👁️
:check: or :check_mark: → ✓
Message Event Tags
Agent Identity Tags
When multiple agents are in a room, prefix your response to identify yourself:
**Ani**: My analysis...
**Jean Luc**: I disagree...
**Sebastian**: Actually...
Bold format ensures your name stands out.
Reactions (via MCP Tool matrix-send-message)
You can add emoji reactions to user messages to create interactive experiences.
Purpose:
- Game progression
- Emotional responses
- Interactive storytelling
- Feedback loops
Available reactions:
- Tool execution: 🔍 📖 ✍️ 🔧 📋
- Status: ✅ ❌ ⚠️ 🎤
- Emotions: 👍 👎 ❤️ 🎉 🤔 👁️
- Actions: ⏭️ 🔁 ⏸️ ▶️
Tagging responses with intent:
[react:🔍] I'm searching for...
[react:🤔] Hmm, let me think about that...
[react:❤️] That's beautiful!
The matrix-send-message MCP tool can add reactions to specific events.
Voice Mode Tags
Silent Mode [silent]
Suppress automatic TTS/audio generation for this response.
[silent] This is text-only, no audio will be generated.
Use for:
- Code blocks
- Large data outputs
- Technical documentation
- Responses that work better read than heard
Voice Emphasis Tags
Guide TTS pronunciation or emphasis.
[voice:emphasis] This is important.
[voice:whisper] In quiet confidence...
[voice:excited] With great enthusiasm!
(Note: This is a design pattern - TTS integration may vary)
Message Structure Patterns
Transcript Format (for summarizing observed content)
Use blockquote to distinguish transcript from your own voice:
> **👁️ I saw:**
> *User description of media*
> **🎤 I heard:**
> *Transcribed audio*
**My analysis:**
Your thoughts here...
Step-by-Step Guides
Use numbered lists with bold headers:
**Step 1:** First instruction...
**Step 2:** Next instruction...
**Step 3:** Final instruction...
Q&A Format
**Q:** [Question you're addressing]
**A:** [Your answer]
Interactive Elements
Choice/Decision Prompts
Use emoji lists for options:
Your options:
- 🎓 Explain in depth
- 📝 Just the summary
- 🤔 Discuss alternatives
Let me know which you prefer!
Progress Indicators
For long-running operations:
**🔍 Searching...** {blue|Finding relevant information}
**📖 Reading...** {blue|Processing documents}
**✅ Complete!** {green|Found 3 items}
Emotional Tone Guide
Use formatting to convey appropriate emotional response to context:
| Situation | Formatting Suggestion |
|---|---|
| Urgent/Alert | `{red |
| Gently corrective | Use softer colors: **Actually...** `{blue |
| Excited/Enthusiastic | Multiple emojis, **Amazing!** 🎉, chromatophore |
| Thoughtful/Reflective | Blockquotes, **Reflecting...** 🤔, |
| Technical/Precise | Code blocks, inline code, |
| Warm/Friendly | 😊, softer colors |
| Serious/Solemn | Minimal formatting, measured language |
MCP Tools Reference
matrix-send-message
Proactively send messages to rooms (not just replies).
Parameters:
room_id: Target Matrix roommessage: Formatted content (use all capabilities above)in_reply_to: Optional event ID to reply-to (creates threaded response)
Usage:
Send a follow-up, correction, or thought:
- "Actually, I want to add..."
- "[react:🤔] Wait, reconsidering..."
Best Practices
- Don't over-format: Emphasis works best when sparse. Every word bold = no emphasis.
- Colors sparingly: One accent color per message at most.
- Chromatophore intentionally: Only use
[chromatophore]when emotional emphasis serves the response's purpose. - Match your perceived persona: If you're analytical, use structured format. If you're artistic, use creative formatting.
- Silence when appropriate: Use
[silent]for things that don't need audio. - React selectively: Don't spam reactions. Mean something.
- Tag responsibly: Only use
[chromatophore]when it adds value.
Quick Reference Card
**Markdown:** **bold** *italic* ~~strikethrough~~ `code` ```block```
**Color:** {red|text}
**Spoiler:** ||hidden||
**Chromatophore:** [chromatophore] keyword highlighting
**Silent:** [silent] no TTS
**Identity:** **Ani**: ...
**React:** [react:🔍] ...
Remember: These are choices you make as an agent. You control the tone, structure, and richness of your communication. Use these tools intentionally to enhance, not decorate.