feat: add Telegram Secretary Mode (Business API) support - #46728
Open
kxnkxv wants to merge 1 commit into
Open
Conversation
Enable via config.extra.secretary_mode: true or telegram: secretary_mode: true. This adds: - _handle_business_connection — tracks BusinessConnection lifecycle (user connects/disconnects the bot as a secretary) - _handle_business_message — routes business_message updates through the standard text/command/media handlers - _effective_update_message fallback for business_message - business_connection_id injection in send() and _send_message_with_thread_fallback so outgoing replies are sent on behalf of the account owner - _business_chat_to_conn mapping so reply-to-business-message works without the account owner needing to manually forward the connection context - Config bridge secretary_mode from YAML → PlatformConfig.extra Uses filters.UpdateType.BUSINESS_MESSAGE (PTB v22+) for type-safe dispatch, with a TypeHandler fallback for older versions. Docs: https://core.telegram.org/bots/features#secretary-bots
alt-glitch
added
type/feature
Closed
teknium1
reviewed
Jul 14, 2026
teknium1
left a comment
teknium1
left a comment
Contributor
There was a problem hiding this comment.
Thanks for implementing the Secretary Mode ingress and reply idea. The feature is still absent from current main, but this patch needs substantive salvage before it can run safely.
Problems
gateway/platforms/telegram.py:37importsTypeHandler as _TypeHandler, while the enabled registration path callsTypeHandler(...)at lines 1650 and 1664. With PTB already installed,TypeHandleris undefined and enabling the feature raisesNameError.gateway/platforms/telegram.py:6144-6149routes all business updates without asender_business_botguard; the PR source has no bot-echo classification.- Business media is routed at line 6148, but
_handle_media_message()returns unlessupdate.messageis present at lines 5623-5626, rather than usingbusiness_message. - Current main moved this adapter to
plugins/platforms/telegram/adapter.pyin5600105478ffde29d7566b45421b100eaa29c4ef; its YAML bridge now belongs in that plugin's_apply_yaml_config().
Suggested changes
- Port the work to the plugin surface, bind the handler correctly, carry the connection ID through session metadata, and cover text/media/bot-echo/outbound paths with tests.
Automated hermes-sweeper review.
| MessageHandler as TelegramMessageHandler, | ||
| ContextTypes, | ||
| filters, | ||
| TypeHandler as _TypeHandler, |
Contributor
There was a problem hiding this comment.
TypeHandler is imported only as _TypeHandler, but the enabled registration path below invokes TypeHandler(...). On the normal installed-PTB import path, TypeHandler is never bound, so enabling secretary_mode raises NameError during adapter connection.
|
|
||
| # Process as a regular message — the existing handlers work | ||
| # because _effective_update_message falls back to business_message. | ||
| if msg.text and (not msg.text.startswith("/")): |
Contributor
There was a problem hiding this comment.
This routes every business text update as customer input. Add bot-echo classification before dispatch (for the relayed business updates created by this adapter's own replies), otherwise the agent can process its own output as a new request.
| await self._handle_text_message(update, context) | ||
| elif msg.text and msg.text.startswith("/"): | ||
| await self._handle_command(update, context) | ||
| elif msg.photo or msg.video or msg.audio or msg.voice or msg.document or msg.sticker: |
Contributor
There was a problem hiding this comment.
_handle_media_message() still returns unless update.message exists (lines 5623-5626 in this PR), while this update uses business_message. Business media therefore never reaches the normal media pipeline.
teknium1
added
sweeper:risk-message-delivery
This was referenced Aug 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Telegram Secretary Mode (Business API) support to Hermes Agent, letting users connect the bot to their Telegram account so it can read and reply to messages in authorised chats on their behalf.
What was added
_handle_business_connection— TracksBusinessConnectionlifecycle (user connects/disconnects the bot). Logged and stored in_business_connectionsdict._handle_business_message— Routes incomingbusiness_messageupdates through the existing text/command/media handler pipeline. Trackschat_id → business_connection_idmapping for reply context._effective_update_message— Falls back toupdate.business_messagewhen noupdate.effective_messageorupdate.messageis present.business_connection_idinsend()and_send_message_with_thread_fallback— Injects the trackedbusiness_connection_idso replies are sent on behalf of the account owner (required by Telegram Business API).secretary_modeconfig bridge — YAMLtelegram: secretary_mode: trueis bridged intoPlatformConfig.extraso the adapter can opt in.filters.UpdateType.BUSINESS_MESSAGE(PTB 22+) with a fallbackTypeHandlerfor older versions.Configuration
Enable in
~/.hermes/config.yaml:Then activate Secretary Mode for your bot via @Botfather → Bot Settings → Secretary Mode, and select which chats to grant access to.
Testing
_handle_business_connection,_handle_business_message_effective_update_messageextended withbusiness_messagefallbackbusiness_connection_idinjected in bothsend()paths (Markdown and plain-text fallback)Documentation
Type safety
LSP diagnostics show warnings for the
except ImportErrorfallback path (pre-existing pattern —filters,Application,_app, etc. are allAny/Nonewhen PTB is not installed). The primary install path has full type coverage.