Skip to content

feat(telegram): add configurable regex wake-word gating for group text and media#3539

Closed
mcleay wants to merge 1 commit into
NousResearch:mainfrom
mcleay:feat/telegram-group-invocation-gating-clean
Closed

feat(telegram): add configurable regex wake-word gating for group text and media#3539
mcleay wants to merge 1 commit into
NousResearch:mainfrom
mcleay:feat/telegram-group-invocation-gating-clean

Conversation

@mcleay

@mcleay mcleay commented Mar 28, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

This PR adds Telegram-specific group invocation gating with configurable regex wake words.

The goal is to let Hermes ignore ambient group chatter while still responding to explicit Telegram group triggers. It adds Hermes-side gating for Telegram group messages and captions so the bot only responds when explicitly invoked.

Changes Made

  • Added Telegram config bridging in gateway/config.py for:
    • telegram.require_mention
    • telegram.mention_patterns
  • Added Telegram group invocation handling in gateway/platforms/telegram.py
  • Group messages are now processed when they:
    • match a configured regex wake word
    • reply to one of the bot’s messages
  • Strips the matched wake-word prefix from the beginning of the text/caption before dispatching to the model
  • Applies the same invocation gating to media/caption messages, not just plain text
  • Avoids mutating Telegram Message objects directly when cleaning invocation prefixes
  • Added focused Telegram gating tests in:
    • tests/gateway/test_telegram_group_gating.py

Example config

telegram:
  require_mention: true
  mention_patterns:
    - "^\\s*wakeword\\b"

With the example above:

  • wakeword hi in a group is processed
  • a plain uninvoked group message is ignored
  • an image with caption wakeword what is this is processed
  • a plain image with no caption is ignored
  • replies to the bot are processed

How to Test

Run:

  • pytest -q tests/gateway/test_telegram_group_gating.py tests/gateway/test_telegram_text_batching.py

Then verify in a Telegram group where the bot receives group messages:

  • plain text with no invocation is ignored
  • wakeword hi is processed
  • reply-to-bot is processed
  • plain image with no caption is ignored
  • image with a wake-word caption is processed

Notes

  • This is Telegram-specific behavior and does not change Discord or other platform adapters.
  • The tests use generic placeholder names/patterns rather than user-specific wake words.

Checklist

  • Code changes tested
  • Group text invocation gating works
  • Group media invocation gating works
  • No private/local config included
  • No user-specific bot names or wake words used in tests

jeremiahrthompson pushed a commit to sumofagents/hermes-agent that referenced this pull request Apr 1, 2026
Add two new hook events that fire in BasePlatformAdapter for ALL platform
adapters without requiring per-adapter modification:

- message:received: fires before session registration, hooks can set
  context['should_process']=False to drop the message silently. Uses
  asyncio.wait_for with configurable 5s timeout (HERMES_HOOK_TIMEOUT).
  Fail-open on timeout and exception (hooks never break message delivery).

- message:processed: fires after agent response is sent (or on error),
  includes response text, success flag, and error string.

Both hooks use the existing HookRegistry. set_hooks() added to
BasePlatformAdapter to wire the registry from GatewayRunner. No
adapter files modified — all 12 adapters inherit hook support via
BasePlatformAdapter.

Ref: NousResearch#3539 NousResearch#2764 NousResearch#3434
@teknium1

Copy link
Copy Markdown
Contributor

Thanks for the contribution @mcleay — closing as redundant. PR #3870 (merged March 29) added telegram.require_mention and mention_patterns (configurable regex wake-words) to main, covering the same feature you proposed. Appreciate the work.

@teknium1 teknium1 closed this Apr 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants