Summary

Add a configurable option to the Mattermost gateway adapter to only respond when @-mentioned in channels/groups, while always processing DMs.

Motivation

In multi-user channels, the bot currently processes every message from other users. This creates noise and unnecessary API calls. Most messaging platforms (Discord, Slack) already filter for mentions in their adapters — Mattermost should have parity.

Proposed behavior

• DMs (channel_type == "D"): Always processed (no change)
• Channels/groups: Only processed if the bot is @-mentioned
  • Check post["mentions"] list for bot's user ID
  • Fallback: check message text for @username or <@user_id>
  • Also respond to @channel, @all, @here broadcast mentions

Implementation

In gateway/platforms/mattermost.py _handle_post(), after the self-message filter, add:

```python

Mention-only mode: skip channel messages that don't @mention the bot.

DMs (type "D") are always processed.

channel_type_raw = data.get("channel_type", "O")
if channel_type_raw != "D":
# Check structured mentions field first
mentions = post.get("mentions", [])
if isinstance(mentions, str):
mentions = mentions.split(",")
has_mention = self._bot_user_id in mentions if mentions else False

# Fallback: check message text for @username or @user_id
if not has_mention:
    mention_patterns = [f"@{self._bot_username}", f"@{self._bot_user_id}"]
    has_mention = any(p.lower() in message.lower() for p in mention_patterns)

# Also respond to broadcast mentions
if not has_mention:
    has_mention = any(m in message for m in ("@channel", "@all", "@here"))

if not has_mention:
    return

```

Configuration option (optional)

A MATTERMOST_MENTION_ONLY env var (default: true) could gate this behavior for backwards compatibility.

Context

This has been running as a local patch in production on a hermes-agent Docker deployment and works well. The structured mentions field from the WebSocket posted event reliably contains the bot's user ID when mentioned.

Related

Parity with Discord and Slack adapters which already filter for mentions.