Issue Station
Sign In
Tools hereToolbox

hermes - ✅(Solved) Fix telegram: group mention gating treats raw substrings as valid mentions [3 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#12545•Fetched 2026-04-20 12:18:22
View on GitHub
Comments
0
Participants
1
Timeline
10
Reactions
0
Author
NewTurn2017NewTurn2017
Participants
NewTurn2017NewTurn2017
Timeline (top)
referenced ×6cross-referenced ×3closed ×1

Telegram mention gating accepts any raw substring match for @<bot_username>, so unrelated text like email addresses or longer handles can wake the bot when require_mention=true.

Root Cause

Telegram mention gating accepts any raw substring match for @<bot_username>, so unrelated text like email addresses or longer handles can wake the bot when require_mention=true.

Fix Action

Fixed

PR fix notes

PR #12637: fix(telegram): require entity mentions for group gating

Description (problem / solution / changelog)

Summary

Fix Telegram group mention gating so only real Telegram mention entities wake the bot.

Root Cause

TelegramAdapter._message_mentions_bot() returned True on any raw @<bot_username> substring before checking Telegram entities. That let unrelated text like foo@hermes_bot.example and longer handles like @hermes_botx bypass require_mention=true.

Changes

  • remove the raw substring fast-path from gateway/platforms/telegram.py
  • keep the existing entity-based mention and text_mention handling intact
  • add regression tests for email-domain and longer-handle false positives in tests/gateway/test_telegram_group_gating.py

Validation

  • scripts/run_tests.sh tests/gateway/test_telegram_group_gating.py -q

Closes #12545.

Changed files

  • gateway/platforms/telegram.py (modified, +0/-2)
  • tests/gateway/test_telegram_group_gating.py (modified, +15/-0)

PR #12826: fix(telegram): use word-boundary matching for bot mention detection

Description (problem / solution / changelog)

What changed

Bot mention detection in the Telegram adapter now uses regex with word-boundary assertions ((?<!\w)@username(?!\w)) instead of substring matching (@username in text).

Before: Substring matching caused false positives when the bot username appeared as part of a larger word or email-like construct, e.g., foo@hermes_bot.example would incorrectly trigger mention detection.

After: The regex ensures the bot username is preceded and followed by non-word characters (or string boundaries), preventing partial matches while still detecting all valid mentions including @Bot, @bot, and mentions within captions.

How to test

  1. Configure a Telegram bot with username hermes_bot
  2. Send messages containing edge cases:
    • @hermes_bot hello — should match (valid mention)
    • foo@hermes_bot.example — should NOT match (partial)
    • @@hermes_bot — should match (valid)
  3. Run the test suite: 
    pytest tests/gateway/test_telegram_mention_boundaries.py -v

Platforms tested

  • Linux (Docker container, Python 3.11)

Closes #12545

Changed files

  • gateway/platforms/telegram.py (modified, +3/-2)
  • tests/gateway/test_telegram_mention_boundaries.py (added, +110/-0)

PR #12848: fix(telegram): use word-boundary matching for bot mention detection

Description (problem / solution / changelog)

Salvages #12826 onto current main and takes the fix further.

Summary

Telegram mention detection now relies only on the MessageEntity objects Telegram's server emits for real mentions. The text-scanning path is gone entirely.

Fixes #12545.

Why this approach over the original PR's regex

Telegram's server parses every message and emits MENTION / TEXT_MENTION entities for real @handles. Those entities are the authoritative signal — it's what renders the blue clickable link in clients. Text-scanning (substring OR regex) is both redundant (entities are always present when there's a real mention) and unreliable in contexts Telegram specifically does not treat as mentions:

InputOld substringRegex fix (#12826)Entity-only (this PR)
@hermes_bot hello (real mention)matchmatchmatch
foo@hermes_bot.example (bug #12545)false positivecorrectcorrect
@hermes_botx hifalse positivecorrectcorrect
@hermes_bot inside a URLfalse positivefalse positivecorrect
@hermes_bot inside a code blockfalse positivefalse positivecorrect
Forwarded quoted text containing @hermes_botfalse positivefalse positivecorrect

Changes

  • gateway/platforms/telegram.py: drop the substring/regex text scan in _message_mentions_bot; keep only the MENTION / TEXT_MENTION entity check that was already there. Net -3 lines of live code plus a comment explaining the rationale.
  • tests/gateway/test_telegram_mention_boundaries.py: 18 tests grouped into real-mention detection, substring-false-positive rejection, entity edge cases (malformed offset/length, different target user), and case-insensitivity.

Validation

  • scripts/run_tests.sh tests/gateway/test_telegram_mention_boundaries.py tests/gateway/test_telegram_group_gating.py → 27 passed.
  • E2E against a live TelegramAdapter with realistic payloads: the exact bug repro foo@hermes_bot.example → False; real @hermes_bot with a MENTION entity → True; @hermes_bot inside URL/code without an entity → False; TEXT_MENTION targeting the bot → True; TEXT_MENTION targeting a different user → False.
  • Pre-existing xdist pollution in test_telegram_approval_buttons.py (3 failures when the whole telegram suite runs together) is unrelated — reproduces on stashed main.

Credit

Bug caught and originally fixed by @Tranquil-Flow in #12826 — the problem statement and test scaffolding were theirs. Cherry-picked onto current main with authorship preserved, then a follow-up commit from us swaps the regex approach for entity-only detection and expands the test coverage to the URL/code-block cases.

Changed files

  • gateway/platforms/telegram.py (modified, +9/-4)
  • tests/gateway/test_telegram_mention_boundaries.py (added, +185/-0)

Code Example

from types import SimpleNamespace
from gateway.platforms.telegram import TelegramAdapter

adapter = TelegramAdapter.__new__(TelegramAdapter)
adapter._bot = SimpleNamespace(username='hermes_bot', id=42)
msg = SimpleNamespace(
    text='email me at foo@hermes_bot.example',
    entities=[],
    caption=None,
    caption_entities=[],
)
print(adapter._message_mentions_bot(msg))
# Actual: True
# Expected: False
RAW_BUFFERClick to expand / collapse

Summary

Telegram mention gating accepts any raw substring match for @<bot_username>, so unrelated text like email addresses or longer handles can wake the bot when require_mention=true.

Affected code

  • gateway/platforms/telegram.py:2056-2058
  • tests/gateway/test_telegram_group_gating.py (does not cover substring false positives)

Why this is a bug

if bot_username and f"@{bot_username}" in source_text.lower(): return True bypasses the stricter entity-based mention parsing that follows. Text such as foo@hermes_bot.example or @hermes_botx is not a Telegram mention entity, but the adapter still treats it as a real mention.

Minimal reproduction

from types import SimpleNamespace
from gateway.platforms.telegram import TelegramAdapter

adapter = TelegramAdapter.__new__(TelegramAdapter)
adapter._bot = SimpleNamespace(username='hermes_bot', id=42)
msg = SimpleNamespace(
    text='email me at foo@hermes_bot.example',
    entities=[],
    caption=None,
    caption_entities=[],
)
print(adapter._message_mentions_bot(msg))
# Actual: True
# Expected: False

Expected behavior

  • Mention gating should only trigger on actual Telegram mention entities or exact identifier matches.

Actual behavior

  • Any substring containing @<bot_username> passes the gate.

Suggested investigation

  • Require entity-based mentions or token-boundary checks before returning True.
  • Add regression coverage for email/domain and longer-handle false positives.

extent analysis

TL;DR

The issue can be fixed by modifying the TelegramAdapter to require entity-based mentions or token-boundary checks before returning True for mention gating.

Guidance

  • Modify the if statement in gateway/platforms/telegram.py:2056-2058 to check for exact matches of the bot username within the message text, rather than just substring matches.
  • Add additional checks to ensure that the mention is a valid Telegram mention entity, such as verifying the presence of a specific entity type in the entities list.
  • Update the tests/gateway/test_telegram_group_gating.py to include test cases for email addresses and longer handles that should not trigger the mention gate.
  • Consider adding a token-boundary check to prevent matches within larger words or identifiers.

Example

if bot_username and any(entity['type'] == 'mention' and entity['text'] == f'@{bot_username}' for entity in msg.entities):
    return True

Notes

The provided code snippet is a simplified example and may require additional modifications to fit the exact requirements of the TelegramAdapter class. The entity['text'] comparison assumes that the entity text matches the bot username exactly, including the @ symbol.

Recommendation

Apply a workaround by modifying the TelegramAdapter to use entity-based mentions or token-boundary checks, as this will provide a more accurate and robust solution for mention gating.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

  • Mention gating should only trigger on actual Telegram mention entities or exact identifier matches.
#dependency error#configuration error#environment variable#network issue#logging issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING