#5201: Signal: add group mention gating with requireMention config
docs
channel: signal
Cluster:
Signal and Discord Fixes
Implements per-group mention gating for Signal channels, allowing bots to selectively respond only when mentioned in group chats.
## Features
- Add `channels.signal.groups.<groupId>.requireMention` config option
- Support wildcard default with `channels.signal.groups["*"]`
- **Signal native @ mentions**: Fully supported - detects mentions using Signal's mentions metadata (phone number/UUID matching)
- **Text-based patterns**: Also supported via `mentionPatterns` config (e.g., "bot", "@bot", emojis)
- Store non-mentioned messages in history context
- Full multi-account support with per-account group configs
- Multi-bot support: Each bot only responds to their own mentions
- Comprehensive test coverage (unit + integration tests: 13/13 passing)
## Configuration example
```json5
{
channels: {
signal: {
groups: {
"*": { requireMention: true },
"specific-group": { requireMention: false }
}
}
},
messages: {
groupChat: {
mentionPatterns: ["@bot", "bot", "🦞"]
}
}
}
```
## Testing
Added comprehensive test coverage:
- Unit tests for `resolveSignalGroupRequireMention()` function (8 tests)
- Integration tests for event handler mention gating logic (5 tests)
- Tests follow existing repository patterns
- All tests passing ✅
## Documentation
Updated Signal documentation with:
- Configuration examples for group mention gating
- Explanation of both Signal native mentions and text pattern support
- Multi-account configuration examples
## Implementation Details
- Added `SignalMention` type with `start`, `length`, `number`, and `uuid` fields
- Parses Signal's `dataMessage.mentions` array to detect bot-specific mentions
- Combines native mention detection with existing text pattern matching
- Only triggers when the bot's own account (phone/UUID) is mentioned
## CI Notes
⚠️ **Lint failures**: The failing lint checks (`no-base-to-string`, `restrict-template-expressions`) are **pre-existing** in `src/commands/onboard-auth.credentials.ts` and `src/commands/auth-choice.apply.oauth.ts` - they exist on main branch and are unrelated to this PR's changes. All tests related to this feature pass successfully.
Follows existing patterns from WhatsApp and Telegram channels.
Fixes #1184
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
Adds per-group mention gating for Signal by introducing `channels.signal.groups.<groupId>.requireMention` (with `"*"` wildcard support) and wiring mention-gating checks into the Signal SSE receive event handler. The handler now evaluates both text-based mentionPatterns and Signal native `dataMessage.mentions` metadata to decide whether to dispatch an inbound group message, while still recording skipped messages into group history for context. Also extends Signal config types/zod schema to include per-group settings and adds unit/integration tests plus docs/changelog updates.
<h3>Confidence Score: 3/5</h3>
- Moderately safe to merge, but has a likely correctness bug in native mention UUID matching and some behavior/documentation mismatches.
- Core change is localized and covered by tests, but the native mention detection compares `mention.uuid` to `deps.accountId` (config identifier) which is unlikely to match Signal UUIDs, causing mention gating to incorrectly skip messages in real use. History recording also misses non-text message bodies, and one config comment contradicts observed default behavior.
- src/signal/monitor/event-handler.ts (mention matching + history recording), src/config/types.signal.ts (default behavior documentation)
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
**Context used:**
- Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8))
- Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13))
<!-- /greptile_comment -->
Most Similar PRs
#4337: fix(signal): add group-level allowlist support via groups config
by derekross · 2026-01-30
83.9%
#7459: fix(signal): resolve mention placeholders to actual names
by gerigk-agent · 2026-02-02
78.5%
#18656: fix(signal): add missing groups field to Signal channel schema (#18...
by awkoy · 2026-02-16
77.2%
#20003: feat(whatsapp): follow-up window for group conversations with requi...
by alexmelges · 2026-02-18
76.6%
#8271: feat(signal): Add full quoted message context support
by ProofOfReach · 2026-02-03
75.7%
#7660: fix(signal): route group reactions to group sessions
by ClawdadBot · 2026-02-03
74.8%
#11611: feat: separate group-level allowlist from sender-level command auth...
by thisnick · 2026-02-08
73.8%
#23689: feat(discord): add ignoreOtherMentions config option
by Q00 · 2026-02-22
73.8%
#12069: fix(whatsapp): handle native group @mentions with requireMention
by abhishek0450 · 2026-02-08
73.5%
#10587: fix(extensions/mattermost): pass requireMention override from chatm...
by baku4 · 2026-02-06
73.4%