Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
from __future__ import annotations
import asyncio
import json
import logging
import re
import tempfile
import threading
from dataclasses import dataclass, field, replace
from datetime import datetime
from pathlib import Path
from typing import Any, Callable, Dict, Optional
from config.v2_config import TelegramConfig
from modules.agents.catalog import display_name_for_backend
from core import chat_discovery
from core.message_context import resolve_context_scope_settings_key, resolve_context_thread_id
from vibe.i18n import get_supported_languages, t as i18n_t
from vibe.proxy import resolve_proxy
from modules.agents.native_sessions import AgentNativeSessionService, NativeResumeSession
from core.modals import RouteDraft, RoutingModalData, route_option_label
from .base import (
BaseIMClient,
FileAttachment,
FileDownloadResult,
MessageContext,
InlineButton,
InlineKeyboard,
)
from .formatters import TelegramFormatter
from .message_facts import (
is_original_human_telegram_attachment,
is_original_human_telegram_text,
telegram_message_kind,
)
from . import telegram_api
logger = logging.getLogger(__name__)
def _telegram_size_exceeds(value: object, max_bytes: int | None) -> bool:
if max_bytes is None:
return False
try:
size = int(value) # type: ignore[arg-type]
except (TypeError, ValueError):
return False
return size >= 0 and size > max_bytes
@dataclass
class _TelegramCwdPrompt:
message_id: str
current_cwd: str
@dataclass
class _TelegramResumeSessionState:
message_id: str
options: list[tuple[str, str]]
is_dm: bool
thread_id: Optional[str]
@dataclass
class _TelegramRoutingState:
message_id: str
channel_id: str
thread_id: Optional[str]
user_id: str
is_dm: bool
routing: RoutingModalData
agent: str
# Each Agent keeps its own choices while the form is open; one not yet shown starts from the stored route.
drafts: dict[str, RouteDraft] = field(default_factory=dict)
picker_field: Optional[str] = None
picker_page: int = 0
def draft(self) -> RouteDraft:
if self.agent not in self.drafts:
self.drafts[self.agent] = self.routing.stored_draft(self.agent)
return self.drafts[self.agent]
@dataclass
class _TelegramQuestionState:
message_id: str
callback_prefix: str
questions: list[Any]
answers: list[list[str]]
index: int = 0
@dataclass
class _TelegramSettingsState:
message_id: str
show_message_types: list[str]
current_require_mention: Optional[bool]
global_require_mention: bool
current_language: str
is_dm: bool
thread_id: Optional[str]
@dataclass
class _TelegramUpdateScopeGate:
lock: asyncio.Lock
waiters: int = 0
class TelegramBot(BaseIMClient):
"""Telegram adapter using Bot API long polling."""
_MAX_IN_FLIGHT_UPDATE_TASKS = 100
# The routing picker pages its options, so a route menu offers its whole list here (no ``route_option_limit``).
_MAX_IN_FLIGHT_MESSAGE_CALLBACK_TASKS = 100
_COMMAND_MENU = (
("start", "telegram.commandMenu.start"),
("new", "telegram.commandMenu.new"),
("cwd", "telegram.commandMenu.cwd"),
("setcwd", "telegram.commandMenu.setcwd"),
("resume", "telegram.commandMenu.resume"),
("setup", "telegram.commandMenu.setup"),
("settings", "telegram.commandMenu.settings"),
("stop", "telegram.commandMenu.stop"),
)
_RICH_MARKDOWN_BLOCK_RE = re.compile(
r"(?m)^(?:#{1,6}\s+\S|[-*+]\s+\S|\d+\.\s+\S|>\s?\S|---\s*$|\|.*\|\s*$|\$\$)"
r"|```|<details\b|<tg-|!\[[^\]]*\]\(\s*<?https?://",
re.IGNORECASE,
)
_REMOTE_MARKDOWN_IMAGE_RE = re.compile(
r"!\[([^\]]*)\]\(\s*(?:<(?P<angle_url>https?://[^>\n]+)>|"
r"(?P<bare_url>https?://(?:[^()\\\s]|\([^()]*\))+))"
r"(?:\s+(?:\"[^\"]*\"|'[^']*'|\([^()]*\)))?\s*\)",
re.IGNORECASE,
)
_REMOTE_MARKDOWN_LINKED_IMAGE_RE = re.compile(
r"\[!\[([^\]]*)\]\(\s*(?:<(?P<image_angle_url>https?://[^>\n]+)>|"
r"(?P<image_bare_url>https?://(?:[^()\\\s]|\([^()]*\))+))"
r"(?:\s+(?:\"[^\"]*\"|'[^']*'|\([^()]*\)))?\s*\)\]"
r"\(\s*(?P<link_destination><[^>\n]+>|(?:[^()\\\s]|\([^()]*\))+)"
r"(?:\s+(?:\"[^\"]*\"|'[^']*'|\([^()]*\)))?\s*\)",
re.IGNORECASE,
)
_MARKDOWN_REFERENCE_DEFINITION_RE = re.compile(
r"^[ \t]{0,3}\[(?P<label>[^\]]+)\]:[ \t]*(?:<(?P<angle_url>https?://[^>\n]+)>|"
r"(?P<bare_url>https?://\S+))",
re.IGNORECASE,
)
_MARKDOWN_REFERENCE_IMAGE_RE = re.compile(r"!\[([^\]]*)\]\[(?P<label>[^\]]+)\]")
_MARKDOWN_REFERENCE_LINKED_IMAGE_RE = re.compile(
r"\[!\[([^\]]*)\]\(\s*(?:<(?P<image_angle_url>https?://[^>\n]+)>|"
r"(?P<image_bare_url>https?://(?:[^()\\\s]|\([^()]*\))+))"
r"(?:\s+(?:\"[^\"]*\"|'[^']*'|\([^()]*\)))?\s*\)\]\[(?P<label>[^\]]+)\]",
re.IGNORECASE,
)
_MARKDOWN_FENCE_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})")
_MARKDOWN_LIST_ITEM_RE = re.compile(r"^(?P<indent>[ \t]*)(?:[-*+]|\d+\.)(?P<marker_space>\s+)")
def __init__(self, config: TelegramConfig):
super().__init__(config)
self.config = config
self.formatter = TelegramFormatter()
self.settings_manager = None
self.sessions = None
self._controller = None
self._stop_event = threading.Event()
self._offset: Optional[int] = None
self._bot_user: Optional[dict[str, Any]] = None
self._on_ready: Optional[Callable] = None
self._loop: Optional[asyncio.AbstractEventLoop] = None
self._poll_task: Optional[asyncio.Task[Any]] = None
self._command_menu_task: Optional[asyncio.Task[Any]] = None
self._update_tasks: set[asyncio.Task[Any]] = set()
self._message_callback_tasks: set[asyncio.Task[Any]] = set()
self._update_scope_gates: dict[str, _TelegramUpdateScopeGate] = {}
self._cwd_prompts: dict[str, _TelegramCwdPrompt] = {}
self._resume_states: dict[str, _TelegramResumeSessionState] = {}
self._routing_states: dict[str, _TelegramRoutingState] = {}
self._question_states: dict[str, _TelegramQuestionState] = {}
self._settings_states: dict[str, _TelegramSettingsState] = {}
self._rich_markdown_supported: Optional[bool] = None
def set_settings_manager(self, settings_manager):
self.settings_manager = settings_manager
self.sessions = getattr(settings_manager, "sessions", None)
def set_controller(self, controller):
self._controller = controller
def register_callbacks(
self,
on_message: Optional[Callable] = None,
on_command: Optional[Dict[str, Callable]] = None,
on_callback_query: Optional[Callable] = None,
**kwargs,
):
super().register_callbacks(on_message, on_command, on_callback_query, **kwargs)
if "on_ready" in kwargs:
self._on_ready = kwargs["on_ready"]
def _t(self, key: str, **kwargs) -> str:
lang = "en"
if self._controller and hasattr(self._controller, "_get_lang"):
lang = self._controller._get_lang()
return i18n_t(key, lang, **kwargs)
@property
def _proxy_url(self) -> Optional[str]:
return resolve_proxy(self.config.proxy_url)
def get_default_parse_mode(self) -> Optional[str]:
return "HTML"
def should_use_thread_for_reply(self) -> bool:
return True
def should_use_message_id_for_channel_session(self, context: Optional[MessageContext] = None) -> bool:
return False
def format_markdown(self, text: str) -> str:
return self.formatter.render(text)
def register_handlers(self):
return None
def run(self):
if not self.config.bot_token:
raise ValueError("Telegram bot token is required")
self._stop_event.clear()
asyncio.run(self._run())
def stop(self):
self._stop_event.set()
loop = self._loop
poll_task = self._poll_task
if loop is not None and loop.is_running() and poll_task is not None and not poll_task.done():
loop.call_soon_threadsafe(poll_task.cancel)
async def shutdown(self) -> None:
self.stop()
async def _run(self) -> None:
self._loop = asyncio.get_running_loop()
try:
self._bot_user = (await telegram_api.get_me(self.config.bot_token, proxy_url=self._proxy_url)).get("result")
logger.info("Telegram bot connected as @%s", self._bot_user.get("username") if self._bot_user else "unknown")
self._command_menu_task = asyncio.create_task(self._sync_command_menu())
if self._on_ready:
await self._on_ready()
while not self._stop_event.is_set():
try:
self._poll_task = asyncio.create_task(telegram_api.get_updates(
self.config.bot_token,
self._offset,
proxy_url=self._proxy_url,
))
try:
updates = await self._poll_task
except asyncio.CancelledError:
if self._stop_event.is_set():
break
raise
finally:
self._poll_task = None
for update in updates.get("result", []):
await self._wait_for_update_capacity()
self._offset = int(update["update_id"]) + 1
self._spawn_update_task(update)
except Exception as err:
if self._stop_event.is_set():
break
logger.warning("Telegram poll loop error: %s", err, exc_info=True)
await asyncio.sleep(2)
finally:
self._poll_task = None
command_menu_task = self._command_menu_task
self._command_menu_task = None
if command_menu_task is not None:
if not command_menu_task.done():
command_menu_task.cancel()
await asyncio.gather(command_menu_task, return_exceptions=True)
await self._drain_background_tasks()
def _build_command_menu(self, language: str) -> list[dict[str, str]]:
return [
{"command": command, "description": i18n_t(key, language)}
for command, key in self._COMMAND_MENU
]
async def _sync_command_menu(self) -> None:
languages: list[tuple[Optional[str], str]] = [(None, "en")]
languages.extend(
(language, language)
for language in get_supported_languages()
if re.fullmatch(r"[a-z]{2}", language)
)
scopes: tuple[Optional[dict[str, str]], ...] = (
None,
{"type": "all_private_chats"},
)
for scope in scopes:
for language_code, translation_language in languages:
try:
await telegram_api.set_my_commands(
self.config.bot_token,
self._build_command_menu(translation_language),
scope=scope,
language_code=language_code,
proxy_url=self._proxy_url,
)
except Exception as err:
scope_label = scope["type"] if scope else "default"
language_label = language_code or "default"
logger.warning(
"Failed to sync Telegram command menu for scope=%s language=%s: %s",
scope_label,
language_label,
err,
)
try:
await telegram_api.set_chat_menu_button(
self.config.bot_token,
menu_button={"type": "commands"},
proxy_url=self._proxy_url,
)
except Exception as err:
logger.warning("Failed to enable Telegram command menu button: %s", err)
def _spawn_update_task(self, update: dict[str, Any]) -> None:
scope_key = self._extract_update_scope_key(update)
if scope_key:
task = asyncio.create_task(self._handle_scoped_update(update, scope_key))
else:
task = asyncio.create_task(self._handle_update(update))
self._update_tasks.add(task)
task.add_done_callback(self._handle_update_task_done)
async def _handle_scoped_update(self, update: dict[str, Any], scope_key: str) -> None:
gate = self._update_scope_gates.get(scope_key)
if gate is None:
gate = _TelegramUpdateScopeGate(lock=asyncio.Lock())
self._update_scope_gates[scope_key] = gate
gate.waiters += 1
try:
async with gate.lock:
await self._handle_update(update)
finally:
gate.waiters -= 1
if gate.waiters == 0 and self._update_scope_gates.get(scope_key) is gate:
self._update_scope_gates.pop(scope_key, None)
def _handle_update_task_done(self, task: asyncio.Task[Any]) -> None:
self._update_tasks.discard(task)
try:
task.result()
except asyncio.CancelledError:
return
except Exception:
logger.exception("Telegram update task failed")
async def _wait_for_update_capacity(self) -> None:
if len(self._update_tasks) < self._MAX_IN_FLIGHT_UPDATE_TASKS:
return
pending = tuple(self._update_tasks)
if pending:
await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
async def _wait_for_message_callback_capacity(self) -> None:
while len(self._message_callback_tasks) >= self._MAX_IN_FLIGHT_MESSAGE_CALLBACK_TASKS:
pending = tuple(self._message_callback_tasks)
if not pending:
return
await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
async def _drain_task_set(self, tasks: set[asyncio.Task[Any]]) -> None:
if not tasks:
return
pending = tuple(tasks)
await asyncio.gather(*pending, return_exceptions=True)
async def _drain_background_tasks(self) -> None:
await self._drain_task_set(self._update_tasks)
await self._drain_task_set(self._message_callback_tasks)
def _extract_update_scope_key(self, update: dict[str, Any]) -> Optional[str]:
callback_query = update.get("callback_query") or {}
if callback_query:
message = callback_query.get("message") or {}
chat = message.get("chat") or {}
from_user = callback_query.get("from") or {}
return self._raw_interaction_scope_key(chat=chat, from_user=from_user)
message = update.get("message") or {}
if message:
chat = message.get("chat") or {}
from_user = message.get("from") or {}
return self._raw_interaction_scope_key(chat=chat, from_user=from_user)
return None
def _raw_interaction_scope_key(self, *, chat: dict[str, Any], from_user: dict[str, Any]) -> Optional[str]:
chat_id = str(chat.get("id") or "").strip()
user_id = str(from_user.get("id") or "").strip()
if not chat_id or not user_id:
return None
is_dm = chat.get("type") == "private"
scope = user_id if is_dm else chat_id
return f"{scope}:{user_id}"
async def _spawn_message_callback_task(self, context: MessageContext, text: str) -> None:
if not self.on_message_callback:
return
await self._wait_for_message_callback_capacity()
task = asyncio.create_task(self.on_message_callback(context, text))
self._message_callback_tasks.add(task)
task.add_done_callback(self._handle_message_callback_task_done)
def _handle_message_callback_task_done(self, task: asyncio.Task[Any]) -> None:
self._message_callback_tasks.discard(task)
try:
task.result()
except asyncio.CancelledError:
return
except Exception:
logger.exception("Telegram message callback task failed")
async def _handle_update(self, update: dict[str, Any]) -> None:
if update.get("callback_query"):
await self._handle_callback_query(update["callback_query"])
return
message = update.get("message")
if message:
await self._handle_message(message)
async def _handle_message(self, message: dict[str, Any]) -> None:
if self._controller and hasattr(self._controller, "_refresh_config_from_disk"):
self._controller._refresh_config_from_disk()
context = self._build_message_context(message)
if context is None:
return
raw_text = message.get("text") or message.get("caption") or ""
text = self._normalize_command_text(raw_text)
if self._is_command_for_other_bot(text):
return
explicitly_addressed = self._is_explicitly_addressed(message, text)
effective_require_mention = self._effective_require_mention(context)
text = self._strip_leading_bot_mention(message, text)
if await self._consume_cwd_prompt(context, text):
return
if effective_require_mention and not context.platform_specific.get("is_dm", False):
if not explicitly_addressed:
return
denial = self.check_authorization(
user_id=context.user_id,
channel_id=context.channel_id,
thread_id=resolve_context_thread_id(context),
is_dm=bool(context.platform_specific.get("is_dm")),
text=text,
settings_manager=self.settings_manager,
)
if not denial.allowed:
denial_text = self.build_auth_denial_text(denial.denial, context.channel_id)
if denial_text:
await self.send_message(context, denial_text)
return
allow_plain_bind = self.should_allow_plain_bind(
user_id=context.user_id,
is_dm=bool(context.platform_specific.get("is_dm")),
settings_manager=self.settings_manager,
)
if await self.dispatch_text_command(context, text, allow_plain_bind=allow_plain_bind):
return
original_thread_id = resolve_context_thread_id(context)
context = await self._maybe_route_to_forum_topic(context, message, text)
if resolve_context_thread_id(context) != original_thread_id:
if (
self._effective_require_mention(context)
and not context.platform_specific.get("is_dm", False)
and not explicitly_addressed
):
return
denial = self.check_authorization(
user_id=context.user_id,
channel_id=context.channel_id,
thread_id=resolve_context_thread_id(context),
is_dm=bool(context.platform_specific.get("is_dm")),
text=text,
settings_manager=self.settings_manager,
)
if not denial.allowed:
denial_text = self.build_auth_denial_text(denial.denial, context.channel_id)
if denial_text:
await self.send_message(context, denial_text)
return
await self._spawn_message_callback_task(context, text)
def _effective_require_mention(self, context: MessageContext) -> bool:
effective = self.config.require_mention
if self.settings_manager is None or context.platform_specific.get("is_dm", False):
return bool(effective)
try:
return bool(
self.settings_manager.get_require_mention(
resolve_context_scope_settings_key(context),
global_default=self.config.require_mention,
)
)
except Exception:
logger.debug("Failed to resolve Telegram effective require_mention", exc_info=True)
return bool(effective)
async def _maybe_route_to_forum_topic(
self,
context: MessageContext,
message: dict[str, Any],
text: str,
) -> MessageContext:
if not self._should_auto_create_topic(context, message, text):
return context
try:
new_context = await self.start_new_topic_session(context, seed_text=text, message=message)
if new_context is not None:
return new_context
except Exception as err:
logger.warning("Telegram forum auto-topic failed, falling back to current topic: %s", err, exc_info=True)
return context
def _is_forum_chat(self, context: MessageContext, message: Optional[dict[str, Any]] = None) -> bool:
payload = context.platform_specific or {}
chat = (message or {}).get("chat") or {}
return (
bool(payload.get("is_forum"))
or bool(payload.get("is_topic_message"))
or bool((message or {}).get("is_topic_message"))
or bool(chat.get("is_forum"))
)
def _is_general_forum_context(self, context: MessageContext, message: dict[str, Any]) -> bool:
if not self._is_forum_chat(context, message):
return False
thread_id = str(context.thread_id or message.get("message_thread_id") or "").strip()
return thread_id in {"", "1"}
def _has_topic_seed_content(self, context: MessageContext, text: str) -> bool:
if (text or "").strip():
return True
return bool(getattr(context, "files", None))
def _should_auto_create_topic(self, context: MessageContext, message: dict[str, Any], text: str) -> bool:
if not self.config.forum_auto_topic:
return False
if (context.platform_specific or {}).get("chat_type") != "supergroup":
return False
if not self._is_general_forum_context(context, message):
return False
if not self._has_topic_seed_content(context, text):
return False
if message.get("reply_to_message"):
return False
if text.startswith("/"):
return False
return True
def _derive_topic_title(self, text: str, message: dict[str, Any]) -> str:
first_line = ""
if text:
first_line = text.strip().splitlines()[0].strip()
if first_line.startswith("/"):
first_line = ""
if first_line:
if len(first_line) > 60:
return first_line[:57].rstrip() + "..."
return first_line
sender = (message.get("from") or {}).get("first_name") or "Session"
return f"{sender} {datetime.now().strftime('%m-%d %H:%M')}"
async def start_new_topic_session(
self,
context: MessageContext,
*,
seed_text: str = "",
message: Optional[dict[str, Any]] = None,
) -> Optional[MessageContext]:
payload = context.platform_specific or {}
if payload.get("chat_type") != "supergroup":
return None
if not context.thread_id and not self._is_forum_chat(context, message):
return None
topic_name = self._derive_topic_title(seed_text, message or {})
created = await telegram_api.create_forum_topic(self.config.bot_token, context.channel_id, topic_name, proxy_url=self._proxy_url)
topic = created.get("result") or {}
topic_id = topic.get("message_thread_id")
if topic_id is None:
raise RuntimeError("Telegram createForumTopic returned no message_thread_id")
chat_discovery.remember_thread(
"telegram",
context.channel_id,
str(topic_id),
name=topic_name,
native_type="forum_topic",
metadata={"auto_created": True, "is_general": False},
)
topic_context = MessageContext(
user_id=context.user_id,
channel_id=context.channel_id,
thread_id=str(topic_id),
message_id=context.message_id,
platform="telegram",
files=context.files,
is_original_human_text=context.is_original_human_text,
is_original_human_attachment=context.is_original_human_attachment,
message_kind=context.message_kind,
platform_specific={
**payload,
"is_topic_message": True,
"is_forum": True,
"auto_topic_created": True,
"topic_name": topic_name,
},
)
if self._is_general_forum_context(context, message or {}):
try:
await self.send_message(
context,
self._t("telegram.autoTopicGeneralNotice", topic=topic_name),
reply_to=context.message_id,
)
except Exception:
logger.debug("Failed to send Telegram General handoff notice", exc_info=True)
return topic_context
async def _handle_callback_query(self, payload: dict[str, Any]) -> None:
message = payload.get("message") or {}
chat = message.get("chat") or {}
from_user = payload.get("from") or {}
if not chat or not from_user:
return
self._remember_discovered_chat(chat, message)
thread_id = message.get("message_thread_id")
context = MessageContext(
user_id=str(from_user.get("id")),
channel_id=str(chat.get("id")),
thread_id=str(thread_id) if thread_id is not None else None,
message_id=str(message.get("message_id")),
platform="telegram",
platform_specific={
"is_dm": chat.get("type") == "private",
"chat_type": chat.get("type"),
"chat_title": chat.get("title") or chat.get("username"),
"is_forum": bool(chat.get("is_forum")) or bool(message.get("is_topic_message")),
"is_topic_message": bool(message.get("is_topic_message")),
"raw_message": message,
},
)
callback_id = str(payload.get("id"))
context.platform_specific = {
**(context.platform_specific or {}),
"callback_id": callback_id,
"callback_query": payload,
}
callback_data = str(payload.get("data", ""))
primary_action = self._resolve_callback_action(callback_data)
is_internal_callback = callback_data.startswith(("tg_cwd:", "tg_resume:", "tg_route:", "tg_question:", "tg_settings:"))
if is_internal_callback:
auth_result = self.check_authorization(
user_id=context.user_id,
channel_id=context.channel_id,
thread_id=resolve_context_thread_id(context),
is_dm=bool(context.platform_specific.get("is_dm")),
action=primary_action,
settings_manager=self.settings_manager,
)
if not auth_result.allowed:
denial_text = self.build_auth_denial_text(auth_result.denial, context.channel_id)
await self.answer_callback(
callback_id,
denial_text,
show_alert=bool(denial_text),
)
return
if await self._handle_internal_callback(context, callback_data):
await self.answer_callback(callback_id)
return
if self.on_callback_query_callback:
auth_result = self.check_authorization(
user_id=context.user_id,
channel_id=context.channel_id,
thread_id=resolve_context_thread_id(context),
is_dm=bool(context.platform_specific.get("is_dm")),
action=primary_action,
settings_manager=self.settings_manager,
)
if not auth_result.allowed:
denial_text = self.build_auth_denial_text(auth_result.denial, context.channel_id)
await self.answer_callback(
callback_id,
denial_text,
show_alert=bool(denial_text),
)
return
await self.on_callback_query_callback(context, callback_data)
await self.answer_callback(callback_id)
async def _handle_internal_callback(self, context: MessageContext, callback_data: str) -> bool:
if callback_data.startswith("tg_cwd:"):
await self._handle_cwd_callback(context, callback_data)
return True
if callback_data.startswith("tg_resume:"):
await self._handle_resume_callback(context, callback_data)
return True
if callback_data.startswith("tg_route:"):
await self._handle_routing_callback(context, callback_data)
return True
if callback_data.startswith("tg_settings:"):
await self._handle_settings_callback(context, callback_data)
return True
if callback_data.startswith("tg_question:"):
await self._handle_question_callback(context, callback_data)
return True
return False
def _build_message_context(self, message: dict[str, Any]) -> Optional[MessageContext]:
chat = message.get("chat") or {}
from_user = message.get("from") or {}
if not chat or not from_user:
return None
self._remember_discovered_chat(chat, message)
chat_id = str(chat.get("id"))
user_id = str(from_user.get("id"))
thread_id = message.get("message_thread_id")
files = self._extract_files(message)
return MessageContext(
user_id=user_id,
channel_id=chat_id,
thread_id=str(thread_id) if thread_id is not None else None,
message_id=str(message.get("message_id")),
files=files,
is_original_human_text=is_original_human_telegram_text(message, files),
is_original_human_attachment=is_original_human_telegram_attachment(message, files),
message_kind=telegram_message_kind(message, files),
platform="telegram",
platform_specific={
"is_dm": chat.get("type") == "private",
"chat_type": chat.get("type"),
"chat_title": chat.get("title") or chat.get("username"),
"is_forum": bool(chat.get("is_forum")),
"is_topic_message": bool(message.get("is_topic_message")),
"raw_message": message,
},
)
def _remember_discovered_chat(self, chat: dict[str, Any], message: Optional[dict[str, Any]] = None) -> None:
try:
parts = [str(chat.get("first_name") or "").strip(), str(chat.get("last_name") or "").strip()]
display_name = " ".join(part for part in parts if part).strip()
name = chat.get("title") or chat.get("username") or display_name or str(chat.get("id") or "")
chat_type = str(chat.get("type") or "")
is_topic_message = bool((message or {}).get("is_topic_message"))
is_forum = bool(chat.get("is_forum")) or is_topic_message
chat_discovery.remember_chat(
platform="telegram",
chat_id=str(chat.get("id")),
name=name,
native_type=chat_type,
is_private=chat_type == "private",
supports_threads=chat_type == "supergroup" and is_forum,
metadata={
chat_discovery.METADATA_USERNAME: str(chat.get("username") or ""),
chat_discovery.METADATA_IS_FORUM: is_forum,
chat_discovery.METADATA_SUPPORTS_TOPICS: chat_type == "supergroup" and is_forum,
},
)
topic_id = (message or {}).get("message_thread_id")
if topic_id is None and is_forum:
topic_id = 1
if topic_id is not None and is_forum:
created = (message or {}).get("forum_topic_created") or {}
edited = (message or {}).get("forum_topic_edited") or {}
topic_name = created.get("name") or edited.get("name") or ""
chat_discovery.remember_thread(
"telegram",
str(chat.get("id")),
str(topic_id),
name=str(topic_name or ""),
native_type="forum_topic",
metadata={"is_general": str(topic_id) == "1"},
)
except Exception:
logger.debug("Failed to remember Telegram discovered chat", exc_info=True)
def _extract_files(self, message: dict[str, Any]) -> list[FileAttachment]:
files: list[FileAttachment] = []
document = message.get("document")
if document:
files.append(
FileAttachment(
name=document.get("file_name") or "telegram-document",
mimetype=document.get("mime_type") or "application/octet-stream",
url=document.get("file_id"),
size=document.get("file_size"),
)
)
photo = message.get("photo") or []
if photo:
best = photo[-1]
files.append(
FileAttachment(
name="telegram-photo.jpg",
mimetype="image/jpeg",
url=best.get("file_id"),
size=best.get("file_size"),
)
)
voice = message.get("voice")
if voice:
files.append(
FileAttachment(
name="telegram-voice.ogg",
mimetype=voice.get("mime_type") or "audio/ogg",
url=voice.get("file_id"),
size=voice.get("file_size"),
)
)
audio = message.get("audio")
if audio:
files.append(
FileAttachment(
name=audio.get("file_name") or "telegram-audio.mp3",
mimetype=audio.get("mime_type") or "audio/mpeg",
url=audio.get("file_id"),
size=audio.get("file_size"),
)
)
return files
def _normalize_command_text(self, text: str) -> str:
stripped = (text or "").strip()
if not stripped.startswith("/"):
return stripped
head, *tail = stripped.split(maxsplit=1)
command, username = self._split_command_target(head)
bot_username = str((self._bot_user or {}).get("username") or "")
if username and bot_username and username.lower() == bot_username.lower():
head = command
return " ".join([head, *tail]).strip()
def _split_command_target(self, head: str) -> tuple[str, str]:
command, sep, username = str(head or "").partition("@")
if not sep:
return command, ""
return command, username
def _is_command_for_other_bot(self, text: str) -> bool:
stripped = (text or "").strip()
if not stripped.startswith("/"):
return False
head = stripped.split(maxsplit=1)[0]
_, username = self._split_command_target(head)
if not username:
return False
bot_username = str((self._bot_user or {}).get("username") or "")
return bool(bot_username) and username.lower() != bot_username.lower()
def _strip_leading_bot_mention(self, message: dict[str, Any], text: str) -> str:
stripped = (text or "").strip()
if not stripped or stripped.startswith("/"):
return stripped
username = str((self._bot_user or {}).get("username") or "")
if not username:
return stripped
entities = message.get("entities") or []
candidate = stripped
for entity in entities:
if entity.get("type") != "mention":
continue
offset = int(entity.get("offset", 0))
length = int(entity.get("length", 0))
if offset != 0 or length <= 0:
continue
mention_text = candidate[offset : offset + length]
if mention_text.lower() != f"@{username.lower()}":
continue
remainder = candidate[offset + length :].lstrip(" \t\r\n,:-")
return remainder.strip()
return stripped
def _resolve_callback_action(self, callback_data: str) -> str:
if callback_data.startswith("tg_cwd:"):
return "cmd_change_cwd"
if callback_data.startswith("tg_route:"):
return "cmd_routing"
if callback_data.startswith("tg_settings:"):
return "cmd_settings"
if callback_data.startswith("toggle_msg_") or callback_data in {"open_settings_modal", "info_msg_types"}:
return "cmd_settings"
return callback_data
def _interaction_scope_key(self, context: MessageContext) -> str:
payload = context.platform_specific or {}
is_dm = bool(payload.get("is_dm"))
scope = context.user_id if is_dm else context.channel_id
thread_id = resolve_context_thread_id(context)
thread_suffix = f":{thread_id}" if not is_dm and thread_id is not None else ""
return f"{scope}:{context.user_id}{thread_suffix}"
async def _consume_cwd_prompt(self, context: MessageContext, text: str) -> bool:
prompt = self._cwd_prompts.get(self._interaction_scope_key(context))
if prompt is None:
return False
stripped = text.strip()
if not stripped:
return False
if stripped == "/cancel":
self._cwd_prompts.pop(self._interaction_scope_key(context), None)
await self._delete_interaction_message(context, prompt.message_id)
return True
known_commands = {
"start",
"new",
"clear",
"resume",
"settings",
"routing",
"agent",
"cwd",
"setcwd",
"set_cwd",
"bind",
"stop",
"memory",
}
parsed_command = self.parse_text_command(stripped, allow_plain_bind=True)
if parsed_command and parsed_command[0] in known_commands:
return False
self._cwd_prompts.pop(self._interaction_scope_key(context), None)
await self._delete_interaction_message(context, prompt.message_id)
if self._controller is None or not hasattr(self._controller, "command_handler"):
await self.send_message(context, f"❌ {self._t('error.cwdChangeFailed')}")
return True
await self._controller.command_handler.handle_set_cwd(context, stripped)
return True
def _is_explicitly_addressed(self, message: dict[str, Any], text: str) -> bool:
if text.startswith("/"):
head = text.split(maxsplit=1)[0]
_, username = self._split_command_target(head)
if not username:
return True
bot_username = str((self._bot_user or {}).get("username") or "")
return bool(bot_username) and username.lower() == bot_username.lower()
reply_to = message.get("reply_to_message") or {}
reply_from = reply_to.get("from") or {}
if self._bot_user and str(reply_from.get("id")) == str(self._bot_user.get("id")):
return True
username = str((self._bot_user or {}).get("username") or "")
if not username:
return False
entities = message.get("entities") or []
for entity in entities:
if entity.get("type") != "mention":
continue
offset = int(entity.get("offset", 0))
length = int(entity.get("length", 0))
if text[offset : offset + length].lower() == f"@{username.lower()}":
return True
return False
def _build_payload(
self,
context: MessageContext,
text: Optional[str] = None,
keyboard: Optional[InlineKeyboard] = None,
*,
reply_to: Optional[str] = None,
parse_mode: Optional[str] = None,
) -> dict[str, Any]:
payload: dict[str, Any] = {"chat_id": context.channel_id}
if context.thread_id:
payload["message_thread_id"] = int(context.thread_id)
if text is not None:
payload["text"] = text
resolved_parse_mode = self._resolve_parse_mode(parse_mode)
if text is not None and resolved_parse_mode:
payload["parse_mode"] = resolved_parse_mode
if reply_to:
payload["reply_parameters"] = {"message_id": int(reply_to)}
if keyboard is not None:
payload["reply_markup"] = {
"inline_keyboard": [
[{"text": button.text, "callback_data": button.callback_data} for button in row]
for row in keyboard.buttons
]
}
return payload
def _build_rich_message_payload(
self,
context: MessageContext,
text: str,
keyboard: Optional[InlineKeyboard] = None,
*,
reply_to: Optional[str] = None,
) -> dict[str, Any]:
payload: dict[str, Any] = {
"chat_id": context.channel_id,
"rich_message": {
"markdown": text,
},
}
if context.thread_id:
payload["message_thread_id"] = int(context.thread_id)
if reply_to:
payload["reply_parameters"] = {"message_id": int(reply_to)}
if keyboard is not None:
payload["reply_markup"] = {
"inline_keyboard": [
[{"text": button.text, "callback_data": button.callback_data} for button in row]
for row in keyboard.buttons
]
}
return payload
def _should_send_rich_markdown(self, text: str) -> bool:
if not text or not text.strip():
return False
if self._rich_markdown_supported is False:
return False
return bool(self._RICH_MARKDOWN_BLOCK_RE.search(text))
@staticmethod
def _is_rich_message_method_unavailable(err: Exception) -> bool:
description = str(err).lower()
return "method not found" in description
@staticmethod
def _is_rich_message_remote_media_error(err: Exception) -> bool:
description = str(err)
return "RICH_MESSAGE_PHOTO_NO_MEDIA_FOUND" in description
@classmethod
def _degrade_remote_markdown_images(cls, text: str) -> str:
reference_urls: dict[str, str] = {}
for line in text.splitlines():
match = cls._MARKDOWN_REFERENCE_DEFINITION_RE.match(line)
if match:
label = " ".join(match.group("label").casefold().split())
angle_url = match.group("angle_url")
reference_urls[label] = f"<{angle_url}>" if angle_url is not None else match.group("bare_url")
def is_escaped(segment: str, pos: int) -> bool:
backslashes = 0
cursor = pos - 1
while cursor >= 0 and segment[cursor] == "\\":
backslashes += 1
cursor -= 1
return backslashes % 2 == 1
def replace(match: re.Match[str]) -> str:
if is_escaped(match.string, match.start()):
return match.group(0)
angle_url = match.group("angle_url")
url = angle_url or match.group("bare_url")
label = match.group(1).strip() or url
destination = f"<{angle_url}>" if angle_url is not None else url
return f"[{label}]({destination})"
def replace_linked(match: re.Match[str]) -> str:
if is_escaped(match.string, match.start()):
return match.group(0)
image_url = match.group("image_angle_url") or match.group("image_bare_url")
label = match.group(1).strip() or image_url
destination = match.group("link_destination")
return f"[{label}]({destination})"
def replace_reference_linked(match: re.Match[str]) -> str:
if is_escaped(match.string, match.start()):
return match.group(0)
image_url = match.group("image_angle_url") or match.group("image_bare_url")
label = match.group(1).strip() or image_url
destination_label = match.group("label")
return f"[{label}][{destination_label}]"
def replace_reference(match: re.Match[str]) -> str:
if is_escaped(match.string, match.start()):
return match.group(0)
destination_label = " ".join(match.group("label").casefold().split())
destination = reference_urls.get(destination_label)
if destination is None:
return match.group(0)
label = match.group(1).strip() or destination
return f"[{label}]({destination})"
def degrade_images(segment: str) -> str:
segment = cls._MARKDOWN_REFERENCE_LINKED_IMAGE_RE.sub(replace_reference_linked, segment)
segment = cls._REMOTE_MARKDOWN_LINKED_IMAGE_RE.sub(replace_linked, segment)
segment = cls._REMOTE_MARKDOWN_IMAGE_RE.sub(replace, segment)
return cls._MARKDOWN_REFERENCE_IMAGE_RE.sub(replace_reference, segment)
def replace_outside_inline_code(segment: str) -> str:
parts: list[str] = []
pos = 0
while pos < len(segment):
if segment[pos] != "`":
next_code = segment.find("`", pos)
end = len(segment) if next_code == -1 else next_code
parts.append(degrade_images(segment[pos:end]))
pos = end
continue
marker_end = pos + 1
while marker_end < len(segment) and segment[marker_end] == "`":
marker_end += 1
marker = segment[pos:marker_end]
close = segment.find(marker, marker_end)
if close == -1:
parts.append(segment[pos])
pos += 1
continue
close_end = close + len(marker)
parts.append(segment[pos:close_end])
pos = close_end
return "".join(parts)
parts: list[str] = []
fence_char: Optional[str] = None
fence_len = 0
list_content_indent: Optional[int] = None
for line in text.splitlines(keepends=True):
fence_match = cls._MARKDOWN_FENCE_RE.match(line)
if fence_char is not None:
parts.append(line)
if fence_match:
marker = fence_match.group(1)
if marker[0] == fence_char and len(marker) >= fence_len:
fence_char = None
fence_len = 0
continue
if fence_match:
marker = fence_match.group(1)
fence_char = marker[0]
fence_len = len(marker)
parts.append(line)
continue
list_match = cls._MARKDOWN_LIST_ITEM_RE.match(line)
if list_match:
list_content_indent = len(line[: list_match.end()].replace("\t", " "))
elif line.strip():
indent = len(line) - len(line.lstrip(" \t"))
if list_content_indent is not None and indent < list_content_indent:
list_content_indent = None
indent = len(line) - len(line.lstrip(" \t"))
is_list_continuation = list_content_indent is not None and indent >= list_content_indent
is_list_code = list_content_indent is not None and indent >= list_content_indent + 4
if line.startswith((" ", "\t")) and (not is_list_continuation or is_list_code):
parts.append(line)
continue
parts.append(replace_outside_inline_code(line))
return "".join(parts)
async def _send_rich_markdown_payload(
self,
context: MessageContext,
text: str,
keyboard: Optional[InlineKeyboard] = None,
*,
reply_to: Optional[str] = None,
) -> str:
payload = self._build_rich_message_payload(context, text, keyboard=keyboard, reply_to=reply_to)
result = await telegram_api.call_api(
self.config.bot_token,
"sendRichMessage",
payload,
proxy_url=self._proxy_url,
)
return str(result["result"]["message_id"])
async def _send_message_with_buttons_payload(
self,
context: MessageContext,
text: str,
keyboard: InlineKeyboard,
*,
parse_mode: Optional[str] = None,
reply_to: Optional[str] = None,
) -> str:
payload = self._build_payload(
context,
self.format_markdown(text),
keyboard=keyboard,
reply_to=reply_to,
parse_mode=parse_mode,
)
result = await telegram_api.call_api(self.config.bot_token, "sendMessage", payload, proxy_url=self._proxy_url)
return str(result["result"]["message_id"])
async def send_markdown_message(
self,
context: MessageContext,
text: str,
keyboard: Optional[InlineKeyboard] = None,
reply_to: Optional[str] = None,
subtext: Optional[str] = None,
) -> str:
"""Send LLM-authored Markdown through Telegram Rich Messages when useful.
Bot API 10.1 rich messages understand GFM-like block structure. Plain
short markdown still uses the legacy HTML conversion path because it is
older, broadly deployed, and sufficient for simple emphasis/links/code.
``subtext`` is accepted for the BaseIMClient contract and ignored:
Telegram has no native de-emphasized footer, so the dispatcher folds any
footnote into ``text`` for this platform instead.
"""
if not self._should_send_rich_markdown(text):
if keyboard is not None:
return await self._send_message_with_buttons_payload(
context,
text,
keyboard,
parse_mode="markdown",
reply_to=reply_to,
)
return await self.send_message(context, text, parse_mode="markdown", reply_to=reply_to)
try:
message_id = await self._send_rich_markdown_payload(context, text, keyboard=keyboard, reply_to=reply_to)
except Exception as err:
if self._is_rich_message_method_unavailable(err):
self._rich_markdown_supported = False
elif self._is_rich_message_remote_media_error(err):
degraded = self._degrade_remote_markdown_images(text)
if degraded != text:
try:
message_id = await self._send_rich_markdown_payload(
context,
degraded,
keyboard=keyboard,
reply_to=reply_to,
)
except Exception:
logger.warning("Telegram sendRichMessage retry without remote image media failed", exc_info=True)
else:
self._rich_markdown_supported = True
return message_id
logger.warning("Telegram sendRichMessage failed; falling back to sendMessage", exc_info=True)
if keyboard is not None:
return await self._send_message_with_buttons_payload(
context,
text,
keyboard,
parse_mode="markdown",
reply_to=reply_to,
)
return await self.send_message(context, text, parse_mode="markdown", reply_to=reply_to)
self._rich_markdown_supported = True
return message_id
async def send_message(
self,
context: MessageContext,
text: str,
parse_mode: Optional[str] = None,
reply_to: Optional[str] = None,
subtext: Optional[str] = None,
) -> str:
# ``subtext`` (concise status-bubble footer) is part of the BaseIMClient
# contract; Telegram has no native footer styling, so it is accepted and
# ignored (no behavior change).
payload = self._build_payload(
context,
self.format_markdown(text),
reply_to=reply_to,
parse_mode=parse_mode,
)
result = await telegram_api.call_api(self.config.bot_token, "sendMessage", payload, proxy_url=self._proxy_url)
return str(result["result"]["message_id"])
async def send_message_with_buttons(
self, context: MessageContext, text: str, keyboard: InlineKeyboard, parse_mode: Optional[str] = None
) -> str:
payload = self._build_payload(
context,
self.format_markdown(text),
keyboard=keyboard,
parse_mode=parse_mode,
)
result = await telegram_api.call_api(self.config.bot_token, "sendMessage", payload, proxy_url=self._proxy_url)
return str(result["result"]["message_id"])
async def upload_markdown(
self,
context: MessageContext,
title: str,
content: str,
filetype: str = "markdown",
) -> str:
suffix = ".md" if filetype == "markdown" else f".{filetype.lstrip('.')}"
with tempfile.NamedTemporaryFile("w", encoding="utf-8", suffix=suffix, delete=False) as tmp:
tmp.write(content or "")
tmp_path = tmp.name
try:
return await self.upload_file_from_path(context, tmp_path, title=title)
finally:
try:
Path(tmp_path).unlink(missing_ok=True)
except Exception:
logger.debug("Failed to clean up temporary markdown file", exc_info=True)
async def edit_message(
self,
context: MessageContext,
message_id: str,
text: Optional[str] = None,
keyboard: Optional[InlineKeyboard] = None,
parse_mode: Optional[str] = None,
subtext: Optional[str] = None,
) -> bool:
# ``subtext`` is accepted for the BaseIMClient contract and ignored:
# Telegram has no native de-emphasized footer styling (no behavior change).
payload = {
"chat_id": context.channel_id,
"message_id": int(message_id),
}
if keyboard is not None:
payload["reply_markup"] = {
"inline_keyboard": [
[{"text": button.text, "callback_data": button.callback_data} for button in row]
for row in keyboard.buttons
]
}
elif text is None:
payload["reply_markup"] = {"inline_keyboard": []}
if text is not None:
payload["text"] = self.format_markdown(text)
resolved_parse_mode = self._resolve_parse_mode(parse_mode)
if resolved_parse_mode:
payload["parse_mode"] = resolved_parse_mode
if keyboard is None:
payload["reply_markup"] = {"inline_keyboard": []}
await telegram_api.call_api(self.config.bot_token, "editMessageText", payload, proxy_url=self._proxy_url)
return True
await telegram_api.call_api(self.config.bot_token, "editMessageReplyMarkup", payload, proxy_url=self._proxy_url)
return True
def _resolve_parse_mode(self, parse_mode: Optional[str]) -> Optional[str]:
if not parse_mode:
return self.get_default_parse_mode()
if parse_mode.lower() == "markdown":
return self.get_default_parse_mode()
return parse_mode
async def answer_callback(self, callback_id: str, text: Optional[str] = None, show_alert: bool = False) -> bool:
payload = {"callback_query_id": callback_id, "show_alert": show_alert}
if text:
payload["text"] = text
await telegram_api.call_api(self.config.bot_token, "answerCallbackQuery", payload, proxy_url=self._proxy_url)
return True
async def get_user_info(self, user_id: str) -> Dict[str, Any]:
result = await telegram_api.call_api(self.config.bot_token, "getChat", {"chat_id": user_id}, proxy_url=self._proxy_url)
chat = result["result"]
display_name = chat.get("first_name") or chat.get("username") or "Telegram User"
return {"id": user_id, "name": display_name, "display_name": display_name, "real_name": display_name}
async def get_channel_info(self, channel_id: str) -> Dict[str, Any]:
result = await telegram_api.call_api(self.config.bot_token, "getChat", {"chat_id": channel_id}, proxy_url=self._proxy_url)
chat = result["result"]
name = chat.get("title") or chat.get("username") or channel_id
return {"id": channel_id, "name": name, "type": chat.get("type")}
async def send_dm(self, user_id: str, text: str, **kwargs) -> Optional[str]:
context = MessageContext(
user_id=user_id,
channel_id=user_id,
platform="telegram",
platform_specific={"is_dm": True},
)
keyboard = kwargs.get("keyboard")
parse_mode = kwargs.get("parse_mode")
if keyboard is not None:
return await self.send_message_with_buttons(context, text, keyboard, parse_mode=parse_mode)
return await self.send_message(context, text, parse_mode=parse_mode)
def _normalize_reaction_emoji(self, emoji: str) -> Optional[str]:
normalized = (emoji or "").strip()
if not normalized:
return None
aliases = {
":eyes:": "👀",
"eyes": "👀",
"eye": "👀",
"👀": "👀",
":robot_face:": "🤖",
"robot_face": "🤖",
"robot": "🤖",
"🤖": "🤖",
# Telegram's allowed reaction set lists the writing hand WITHOUT the
# U+FE0F variation selector; the presentation variant is rejected.
"✍️": "✍",
"writing_hand": "✍",
"thinking_face": "🤔",
"shrug": "🤷",
# Terminal receipts. ``setMessageReaction`` accepts ONLY emoji from
# Telegram's fixed list, and neither ⏹️ nor ⚠️ is on it — sent raw,
# the whole call is rejected and the turn ends with no trace at all.
# These two stand-ins are on the list and carry the same reading:
# 🙊 for "stopped talking on your command" (the stop result is
# deliberately silent) and 😱 for the alarm of a runtime that died
# mid-turn. Both spellings of each source emoji are listed because
# the constants carry U+FE0F and callers may strip it.
"⏹️": "🙊",
"⏹": "🙊",
"stop_button": "🙊",
"⚠️": "😱",
"⚠": "😱",
"warning": "😱",
}
return aliases.get(normalized, normalized)
async def add_reaction(self, context: MessageContext, message_id: str, emoji: str) -> bool:
normalized = self._normalize_reaction_emoji(emoji)
if not normalized or not message_id:
return False
try:
await telegram_api.set_message_reaction(self.config.bot_token, context.channel_id, message_id, normalized, proxy_url=self._proxy_url)
return True
except Exception as err:
logger.debug("Failed to add Telegram reaction: %s", err)
return False
async def remove_reaction(self, context: MessageContext, message_id: str, emoji: str) -> bool:
if not message_id or not self._normalize_reaction_emoji(emoji):
return False
try:
await telegram_api.clear_message_reaction(self.config.bot_token, context.channel_id, message_id, proxy_url=self._proxy_url)
return True
except Exception as err:
logger.debug("Failed to remove Telegram reaction: %s", err)
return False
async def send_typing_indicator(self, context: MessageContext) -> bool:
payload = {"chat_id": context.channel_id, "action": "typing"}
if context.thread_id:
payload["message_thread_id"] = int(context.thread_id)
await telegram_api.call_api(self.config.bot_token, "sendChatAction", payload, proxy_url=self._proxy_url)
return True
async def clear_typing_indicator(self, context: MessageContext) -> bool:
return True
async def delete_message(self, context: MessageContext, message_id: str) -> bool:
if not message_id:
return False
await telegram_api.delete_message(self.config.bot_token, context.channel_id, message_id, proxy_url=self._proxy_url)
return True
async def _delete_interaction_message(self, context: MessageContext, message_id: str) -> None:
if not message_id:
return
try:
await self.delete_message(context, message_id)
except Exception:
logger.debug("Failed to delete Telegram interaction message %s", message_id, exc_info=True)
async def upload_file_from_path(
self,
context: MessageContext,
file_path: str,
title: Optional[str] = None,
) -> str:
payload = self._build_payload(context)
if title:
payload["caption"] = title
result = await telegram_api.send_multipart_file(
self.config.bot_token,
"sendDocument",
payload,
file_path,
"document",
proxy_url=self._proxy_url,
)
return str(result["result"]["message_id"])
async def upload_image_from_path(
self,
context: MessageContext,
file_path: str,
title: Optional[str] = None,
) -> str:
payload = self._build_payload(context)
if title:
payload["caption"] = title
result = await telegram_api.send_multipart_file(
self.config.bot_token,
"sendPhoto",
payload,
file_path,
"photo",
proxy_url=self._proxy_url,
)
return str(result["result"]["message_id"])
async def download_file(
self,
file_info: Dict[str, Any],
max_bytes: Optional[int] = None,
timeout_seconds: int = 30,
) -> Optional[bytes]:
file_id = (
file_info.get("telegram_file_id")
or file_info.get("url")
or file_info.get("file_id")
)
if not file_id:
raise ValueError("Telegram file_id is required")
file_result = await telegram_api.get_file(self.config.bot_token, str(file_id), proxy_url=self._proxy_url)
file_path = file_result["result"]["file_path"]
content = await telegram_api.download_file(self.config.bot_token, file_path, timeout_seconds=timeout_seconds, proxy_url=self._proxy_url)
if max_bytes is not None and len(content) > max_bytes:
raise ValueError("Downloaded file exceeds max_bytes")
return content
async def download_file_to_path(
self,
file_info: Dict[str, Any],
target_path: str,
max_bytes: Optional[int] = None,
timeout_seconds: int = 30,
target_fd: Optional[int] = None,
) -> FileDownloadResult:
"""Resolve and stream a Telegram file without buffering it in memory."""
file_id = (
file_info.get("telegram_file_id")
or file_info.get("url")
or file_info.get("file_id")
)
if not file_id:
return FileDownloadResult(False, "Telegram file_id is required")
if _telegram_size_exceeds(file_info.get("size"), max_bytes):
return FileDownloadResult(False, "File exceeds max_bytes", "file_too_large")
target = Path(target_path)
try:
file_result = await telegram_api.get_file(
self.config.bot_token,
str(file_id),
proxy_url=self._proxy_url,
)
resolved = file_result.get("result")
if not isinstance(resolved, dict) or not resolved.get("file_path"):
return FileDownloadResult(False, "Telegram file metadata is invalid")
if _telegram_size_exceeds(resolved.get("file_size"), max_bytes):
return FileDownloadResult(False, "File exceeds max_bytes", "file_too_large")
download_options: Dict[str, Any] = {
"max_bytes": max_bytes,
"timeout_seconds": timeout_seconds,
"proxy_url": self._proxy_url,
}
if target_fd is not None:
download_options["target_fd"] = target_fd
await telegram_api.download_file_to_path(
self.config.bot_token,
str(resolved["file_path"]),
target,
**download_options,
)
return FileDownloadResult(True)
except telegram_api.TelegramFileTooLargeError:
if target_fd is None:
target.unlink(missing_ok=True)
return FileDownloadResult(False, "File exceeds max_bytes", "file_too_large")
except Exception:
if target_fd is None:
target.unlink(missing_ok=True)
return FileDownloadResult(False, "Telegram file download failed")
async def open_change_cwd_modal(self, trigger_id: Any, current_cwd: str, channel_id: str = None):
context = trigger_id if isinstance(trigger_id, MessageContext) else None
if context is None:
raise ValueError("Telegram change-cwd flow requires a message context")
keyboard = InlineKeyboard(
buttons=[[InlineButton(text=f"✖️ {self._t('common.cancel')}", callback_data="tg_cwd:cancel")]]
)
text = "\n".join(
[
f"📂 {self._t('telegram.cwdPromptTitle')}",
"",
f"{self._t('modal.cwd.current')} `{current_cwd}`",
self._t("telegram.cwdPromptBody"),
]
)
prompt_message_id = await self.send_message_with_buttons(context, text, keyboard)
self._cwd_prompts[self._interaction_scope_key(context)] = _TelegramCwdPrompt(
message_id=prompt_message_id,
current_cwd=current_cwd,
)
async def _handle_cwd_callback(self, context: MessageContext, callback_data: str) -> None:
scope_key = self._interaction_scope_key(context)
if callback_data == "tg_cwd:cancel":
prompt = self._cwd_prompts.pop(scope_key, None)
await self._delete_interaction_message(context, (prompt.message_id if prompt else context.message_id or ""))
async def open_resume_session_modal(
self,
trigger_id: Any,
sessions: list[NativeResumeSession],
channel_id: str,
thread_id: Optional[str],
host_message_ts: Optional[str],
):
context = trigger_id if isinstance(trigger_id, MessageContext) else None
if context is None:
raise ValueError("Telegram resume flow requires a message context")
options: list[tuple[str, str]] = []
rows: list[list[InlineButton]] = []
summary_lines = [
f"⏮️ {self._t('telegram.resumeTitle')}",
self._t("telegram.resumeBody"),
]
for item in list(sessions)[:12]:
idx = len(options)
options.append((item.agent, item.native_session_id))
label = AgentNativeSessionService.format_display_summary(item)
rows.append([InlineButton(text=label[:40], callback_data=f"tg_resume:{idx}")])
summary_lines.append(
f"{idx + 1}. {label} ({AgentNativeSessionService.format_display_time(item)})"
)
if len(options) >= 12:
break
rows.append([InlineButton(text=f"✖️ {self._t('common.cancel')}", callback_data="tg_resume:cancel")])
text = "\n".join(summary_lines)
if not options:
text += f"\n\nℹ️ {self._t('telegram.resumeNoStoredSessions')}"
message_id = await self.send_message_with_buttons(context, text, InlineKeyboard(buttons=rows))
self._resume_states[self._interaction_scope_key(context)] = _TelegramResumeSessionState(
message_id=message_id,
options=options,
is_dm=bool((context.platform_specific or {}).get("is_dm")),
thread_id=resolve_context_thread_id(context),
)
async def _handle_resume_callback(self, context: MessageContext, callback_data: str) -> None:
scope_key = self._interaction_scope_key(context)
state = self._resume_states.get(scope_key)
if state is None or state.message_id != (context.message_id or ""):
return
if callback_data == "tg_resume:cancel":
self._resume_states.pop(scope_key, None)
await self._delete_interaction_message(context, state.message_id)
return
try:
option_index = int(callback_data.split(":", 1)[1])
except Exception:
return
if option_index < 0 or option_index >= len(state.options):
return
agent, session_id = state.options[option_index]
self._resume_states.pop(scope_key, None)
if self._controller is None or not hasattr(self._controller, "session_handler"):
await self.send_message(context, f"❌ {self._t('error.resumeFailed')}")
return
await self._delete_interaction_message(context, state.message_id)
await self._controller.session_handler.handle_resume_session_submission(
user_id=context.user_id,
channel_id=context.channel_id,
thread_id=getattr(state, "thread_id", resolve_context_thread_id(context)),
agent=agent,
session_id=session_id,
is_dm=state.is_dm,
platform="telegram",
)
async def open_routing_modal(self, trigger_id: Any, channel_id: str, routing: RoutingModalData):
context = trigger_id if isinstance(trigger_id, MessageContext) else None
if context is None:
raise ValueError("Telegram routing flow requires a message context")
state = _TelegramRoutingState(
message_id="",
channel_id=channel_id,
thread_id=resolve_context_thread_id(context),
user_id=context.user_id,
is_dm=bool((context.platform_specific or {}).get("is_dm")),
routing=routing,
agent=routing.shown_agent(routing.current_agent) or "",
)
text, keyboard = self._render_routing_state(state)
message_id = await self.send_message_with_buttons(context, text, keyboard)
state.message_id = message_id
self._routing_states[self._interaction_scope_key(context)] = state
async def open_question_modal(self, trigger_id: Any, context: MessageContext, pending: Any, callback_prefix: str):
target_context = trigger_id if isinstance(trigger_id, MessageContext) else context
if target_context is None or not isinstance(target_context, MessageContext):
raise ValueError("Telegram question flow requires a message context")
raw_questions = getattr(pending, "questions", None)
if raw_questions is None and isinstance(pending, dict):
raw_questions = pending.get("questions")
questions = list(raw_questions or [])
if not questions:
raise ValueError("Pending question has no questions")
state = _TelegramQuestionState(
message_id=str(target_context.message_id or ""),
callback_prefix=callback_prefix,
questions=questions,
answers=[[] for _ in questions],
)
self._question_states[self._interaction_scope_key(target_context)] = state
text, keyboard = self._render_question_state(target_context, state)
if state.message_id:
await self.edit_message(target_context, state.message_id, text=text, keyboard=keyboard)
else:
state.message_id = await self.send_message_with_buttons(target_context, text, keyboard)
@staticmethod
def _agent_label(state: _TelegramRoutingState, agent_id: str) -> str:
agent = state.routing.agent(agent_id)
return agent.label if agent else agent_id
def _question_definition(self, question: Any) -> tuple[str, str, list[tuple[str, str]], bool]:
if isinstance(question, dict):
header = str(question.get("header") or "").strip()
prompt = str(question.get("question") or "").strip()
options_raw = list(question.get("options") or [])
multiple = bool(question.get("multiple") or question.get("multiSelect"))
else:
header = str(getattr(question, "header", "") or "").strip()
prompt = str(getattr(question, "question", "") or "").strip()
options_raw = list(getattr(question, "options", []) or [])
multiple = bool(getattr(question, "multiple", False))
options: list[tuple[str, str]] = []
for option in options_raw:
if isinstance(option, dict):
label = str(option.get("label") or "").strip()
description = str(option.get("description") or "").strip()
else:
label = str(getattr(option, "label", "") or "").strip()
description = str(getattr(option, "description", "") or "").strip()
if label:
options.append((label, description))
return header, prompt, options, multiple
def _render_question_state(
self,
context: MessageContext,
state: _TelegramQuestionState,
) -> tuple[str, InlineKeyboard]:
header, prompt, options, multiple = self._question_definition(state.questions[state.index])
current_answers = set(state.answers[state.index])
lines = []
title = header or f"Question {state.index + 1}"
lines.append(f"❓ {title}")
if prompt:
lines.append(prompt)
if len(state.questions) > 1:
lines.append(f"{state.index + 1}/{len(state.questions)}")
rows: list[list[InlineButton]] = []
for idx, (label, description) in enumerate(options, start=1):
prefix = "☑️ " if label in current_answers else ""
text = f"{prefix}{label}"
if description:
lines.append(f"{idx}. {label} - {description}")
rows.append(
[
InlineButton(
text=text[:40],
callback_data=f"tg_question:{'toggle' if multiple else 'choose'}:{idx}",
)
]
)
footer_row: list[InlineButton] = []
if multiple:
action_label = self._t("common.submit") if state.index + 1 >= len(state.questions) else self._t("common.next")
footer_row.append(InlineButton(text=action_label, callback_data="tg_question:advance"))
footer_row.append(InlineButton(text=f"✖️ {self._t('common.cancel')}", callback_data="tg_question:cancel"))
rows.append(footer_row)
return "\n".join(lines), InlineKeyboard(buttons=rows)
async def _handle_question_callback(self, context: MessageContext, callback_data: str) -> None:
scope_key = self._interaction_scope_key(context)
state = self._question_states.get(scope_key)
if state is None or state.message_id != (context.message_id or ""):
return
_, action, *rest = callback_data.split(":")
header, prompt, options, multiple = self._question_definition(state.questions[state.index])
del header, prompt
if action == "cancel":
self._question_states.pop(scope_key, None)
await self._delete_interaction_message(context, state.message_id)
return
if action in {"choose", "toggle"} and rest:
try:
option_idx = int(rest[0]) - 1
except Exception:
option_idx = -1
if 0 <= option_idx < len(options):
label = options[option_idx][0]
if action == "choose":
state.answers[state.index] = [label]
if state.index + 1 < len(state.questions):
state.index += 1
else:
await self._finalize_question_state(context, scope_key, state)
return
else:
answers = state.answers[state.index]
if label in answers:
state.answers[state.index] = [value for value in answers if value != label]
else:
answers.append(label)
elif action == "advance":
if multiple and state.index + 1 < len(state.questions):
state.index += 1
else:
await self._finalize_question_state(context, scope_key, state)
return
text, keyboard = self._render_question_state(context, state)
await self.edit_message(context, state.message_id, text=text, keyboard=keyboard)
async def _finalize_question_state(
self,
context: MessageContext,
scope_key: str,
state: _TelegramQuestionState,
) -> None:
self._question_states.pop(scope_key, None)
answers_payload = state.answers
await self._delete_interaction_message(context, state.message_id)
auth_result = self.check_authorization(
user_id=context.user_id,
channel_id=context.channel_id,
thread_id=resolve_context_thread_id(context),
is_dm=bool((context.platform_specific or {}).get("is_dm")),
action=state.callback_prefix,
settings_manager=self.settings_manager,
)
if not auth_result.allowed:
denial_text = self.build_auth_denial_text(auth_result.denial, context.channel_id)
if denial_text:
await self.send_message(context, denial_text)
return
if self.on_callback_query_callback:
synthetic_payload = f"{state.callback_prefix}:modal:{json.dumps(answers_payload, ensure_ascii=True)}"
await self.on_callback_query_callback(context, synthetic_payload)
def _routing_field_label(self, state: _TelegramRoutingState, field: Optional[str]) -> str:
agent = state.routing.agent(state.agent)
mapping = {
"agent": self._t("routing.label.agent"),
"variant": self._t(
"modal.routing.backendAgent", backend=display_name_for_backend(agent.backend) if agent else ""
),
"model": self._t("routing.label.model"),
"reasoning_effort": self._t("routing.label.reasoningEffort"),
}
return mapping.get(field or "", field or "")
def _routing_fields(self, state: _TelegramRoutingState) -> list[tuple[str, str]]:
"""The shown Agent's fields as ``(field, current value's text)``; the native agent only where it has one."""
draft = state.draft()
menu = state.routing.menu(state.agent)
fields = [("model", draft.model), ("reasoning_effort", draft.reasoning_effort)]
if menu.variant_options(draft.variant):
fields.insert(0, ("variant", draft.variant))
shown = []
for name, value in fields:
target = menu.shown_value(value) if value else None
options = self._routing_picker_options(state, name)
text = next((text for text, option in options if option == target), value or "")
# Catalog labels and stored ids are unbounded, and a Telegram message holds 4096 characters.
shown.append((name, text if len(text) <= 100 else f"{text[:99]}…"))
return shown
def _routing_summary_lines(self, state: _TelegramRoutingState) -> list[str]:
lines = [
f"🤖 {self._t('telegram.routingTitle')}",
"",
f"{self._t('routing.label.agent')}: {self._agent_label(state, state.agent)}",
]
lines.extend(f"{self._routing_field_label(state, name)}: {text}" for name, text in self._routing_fields(state))
return lines
def _routing_picker_options(
self, state: _TelegramRoutingState, field_name: Optional[str] = None
) -> list[tuple[str, Optional[str]]]:
field_name = field_name or state.picker_field
if field_name == "agent":
return [(agent.label, agent.id) for agent in state.routing.agent_options()]
menu = state.routing.menu(state.agent)
draft = state.draft()
if field_name == "variant":
options = menu.variant_options(draft.variant)
elif field_name == "model":
options = menu.model_options(draft.model)
elif field_name == "reasoning_effort":
options = menu.effort_options(draft.model, draft.reasoning_effort)
else:
return []
effort = field_name == "reasoning_effort"
default = route_option_label(self._t, menu.default_option(field_name), effort=effort)
return [(default, None)] + [
(route_option_label(self._t, option, effort=effort), option.value) for option in options
]
def _apply_routing_option(self, state: _TelegramRoutingState, value: Optional[str]) -> None:
draft = state.draft()
if state.picker_field in ("variant", "model", "reasoning_effort"):
value = state.routing.menu(state.agent).chosen(state.picker_field, value)
if state.picker_field == "model":
state.drafts[state.agent] = draft.with_model(value)
elif state.picker_field == "variant":
state.drafts[state.agent] = replace(draft, variant=value)
elif state.picker_field == "reasoning_effort":
state.drafts[state.agent] = replace(draft, reasoning_effort=value)
state.picker_field = None
state.picker_page = 0
def _render_routing_state(self, state: _TelegramRoutingState) -> tuple[str, InlineKeyboard]:
if state.picker_field:
return self._render_routing_picker(state)
text = "\n".join(self._routing_summary_lines(state))
# Agent names are free text and Telegram callback data holds 64 bytes, so buttons carry list positions.
agents = state.routing.agent_options()
agent_row = [
InlineButton(
text=(f"☑️ {agent.name}" if agent.id == state.agent else agent.name)[:40],
callback_data=f"tg_route:agent:{index}",
)
for index, agent in enumerate(agents[:3])
]
rows: list[list[InlineButton]] = []
if agent_row:
rows.append(agent_row)
if len(agents) > 3:
rows.append(
[
InlineButton(
text=f"… {self._t('routing.label.agent')}"[:40],
callback_data="tg_route:field:agent",
)
]
)
rows.extend(
[
InlineButton(
text=f"{self._routing_field_label(state, name)}: {value_text}"[:40],
callback_data=f"tg_route:field:{name}",
)
]
for name, value_text in self._routing_fields(state)
)
rows.append(
[
InlineButton(text=f"💾 {self._t('common.save')}", callback_data="tg_route:save"),
InlineButton(text=f"✖️ {self._t('common.cancel')}", callback_data="tg_route:cancel"),
]
)
return text, InlineKeyboard(buttons=rows)
def _render_routing_picker(self, state: _TelegramRoutingState) -> tuple[str, InlineKeyboard]:
options = self._routing_picker_options(state)
page_size = 6
total_pages = max(1, (len(options) + page_size - 1) // page_size)
page = max(0, min(state.picker_page, total_pages - 1))
state.picker_page = page
page_options = options[page * page_size : (page + 1) * page_size]
lines = self._routing_summary_lines(state)
lines.extend(
[
"",
f"{self._t('telegram.routingChoosePrefix')} {self._routing_field_label(state, state.picker_field)}",
]
)
rows = [
[InlineButton(text=(label or self._t("common.default"))[:40], callback_data=f"tg_route:option:{index}")]
for index, (label, _) in enumerate(page_options, start=page * page_size)
]
nav_row: list[InlineButton] = []
if page > 0:
nav_row.append(InlineButton(text="◀️", callback_data="tg_route:page:prev"))
if page + 1 < total_pages:
nav_row.append(InlineButton(text="▶️", callback_data="tg_route:page:next"))
if nav_row:
rows.append(nav_row)
rows.append([InlineButton(text=f"↩️ {self._t('common.back')}", callback_data="tg_route:back")])
return "\n".join(lines), InlineKeyboard(buttons=rows)
async def _handle_routing_callback(self, context: MessageContext, callback_data: str) -> None:
scope_key = self._interaction_scope_key(context)
state = self._routing_states.get(scope_key)
if state is None or state.message_id != (context.message_id or ""):
return
parts = callback_data.split(":")
action = parts[1] if len(parts) > 1 else ""
if action == "cancel":
self._routing_states.pop(scope_key, None)
await self._delete_interaction_message(context, state.message_id)
return
if action == "save":
self._routing_states.pop(scope_key, None)
if self._controller is None or not hasattr(self._controller, "settings_handler"):
await self.send_message(context, f"❌ {self._t('error.routingModalFailed')}")
return
await self._delete_interaction_message(context, state.message_id)
draft = state.draft()
routing_update = {
"user_id": state.user_id,
"channel_id": state.channel_id,
"agent_id": state.agent,
"variant": draft.variant,
"model": draft.model,
"reasoning_effort": draft.reasoning_effort,
"is_dm": state.is_dm,
"platform": "telegram",
}
state_thread_id = getattr(state, "thread_id", None)
if state_thread_id is not None:
routing_update["thread_id"] = state_thread_id
await self._controller.settings_handler.handle_routing_update(**routing_update)
return
if action == "back":
state.picker_field = None
state.picker_page = 0
elif action == "agent" and len(parts) > 2:
agents = state.routing.agent_options()
index = int(parts[2]) if parts[2].isdigit() else -1
if 0 <= index < len(agents):
state.agent = agents[index].id
state.picker_field = None
state.picker_page = 0
elif action == "page" and len(parts) > 2:
state.picker_page += -1 if parts[2] == "prev" else 1
elif action == "field" and len(parts) > 2:
state.picker_field = parts[2]
state.picker_page = 0
elif action == "option" and len(parts) > 2:
try:
option_index = int(parts[2])
except Exception:
option_index = -1
options = self._routing_picker_options(state)
if 0 <= option_index < len(options):
_, value = options[option_index]
if state.picker_field == "agent" and value:
state.agent = value
state.picker_field = None
state.picker_page = 0
else:
self._apply_routing_option(state, value)
text, keyboard = self._render_routing_state(state)
await self.edit_message(context, state.message_id, text=text, keyboard=keyboard)
async def open_settings_modal(
self,
trigger_id: Any,
user_settings: Any,
message_types: list,
display_names: dict,
channel_id: str = None,
current_require_mention: object = None,
global_require_mention: bool = False,
current_language: str = None,
owner_user_id: Optional[str] = None,
):
del display_names, owner_user_id
context = trigger_id if isinstance(trigger_id, MessageContext) else None
if context is None:
raise ValueError("Telegram settings flow requires a message context")
state = _TelegramSettingsState(
message_id="",
show_message_types=list(getattr(user_settings, "show_message_types", []) or []),
current_require_mention=current_require_mention,
global_require_mention=global_require_mention,
current_language=current_language or self._get_lang(),
is_dm=bool((context.platform_specific or {}).get("is_dm")),
thread_id=resolve_context_thread_id(context),
)
text, keyboard = self._render_settings_state(state, list(message_types or []))
message_id = await self.send_message_with_buttons(context, text, keyboard)
state.message_id = message_id
self._settings_states[self._interaction_scope_key(context)] = state
def _settings_mention_label(self, value: Optional[bool], global_require_mention: bool) -> str:
if value is None:
default_status = (
self._t("modal.settings.mentionStatusOn")
if global_require_mention
else self._t("modal.settings.mentionStatusOff")
)
return f"{self._t('common.default')} ({default_status})"
return self._t("modal.settings.optionRequireMention") if value else self._t("modal.settings.optionDontRequireMention")
def _settings_message_type_label(self, msg_type: str) -> str:
display_names = {
"assistant": self._t("messageType.assistant"),
"toolcall": self._t("messageType.toolcall"),
}
return display_names.get(msg_type, msg_type)
def _render_settings_state(
self,
state: _TelegramSettingsState,
message_types: list[str],
) -> tuple[str, InlineKeyboard]:
selected = [self._settings_message_type_label(msg_type) for msg_type in state.show_message_types]
selected_text = ", ".join(selected) if selected else "-"
language_label = self._t(f"language.{state.current_language}")
if language_label == f"language.{state.current_language}":
language_label = state.current_language
lines = [
f"⚙️ {self._t('modal.settings.title')}",
"",
f"1. {self._t('modal.settings.showMessageTypes')}",
f" {self._t('modal.settings.current')}: {selected_text}",
"",
f"2. {self._t('modal.settings.requireMention')}",
f" {self._t('modal.settings.current')}: {self._settings_mention_label(state.current_require_mention, state.global_require_mention)}",
"",
f"3. {self._t('modal.settings.language')}",
f" {self._t('modal.settings.current')}: {language_label}",
]
rows: list[list[InlineButton]] = []
row: list[InlineButton] = []
for index, msg_type in enumerate(message_types):
is_shown = msg_type in state.show_message_types
checkbox = "☑️" if is_shown else "⬜"
row.append(
InlineButton(
text=f"{checkbox} {self._settings_message_type_label(msg_type)}"[:40],
callback_data=f"tg_settings:toggle:{msg_type}",
)
)
if len(row) == 2 or index == len(message_types) - 1:
rows.append(row)
row = []
mention_options = [
("default", self._t("common.default"), state.current_require_mention is None),
("on", self._t("modal.settings.optionRequireMention"), state.current_require_mention is True),
("off", self._t("modal.settings.optionDontRequireMention"), state.current_require_mention is False),
]
rows.append(
[
InlineButton(
text=(f"☑️ {label}" if selected_option else label)[:40],
callback_data=f"tg_settings:mention:{value}",
)
for value, label, selected_option in mention_options
]
)
rows.append(
[
InlineButton(
text=(f"☑️ {self._t(f'language.{lang}')}" if lang == state.current_language else self._t(f"language.{lang}"))[:40],
callback_data=f"tg_settings:lang:{lang}",
)
for lang in get_supported_languages()
]
)
rows.append([InlineButton(text=f"ℹ️ {self._t('button.aboutMessageTypes')}", callback_data="info_msg_types")])
rows.append(
[
InlineButton(text=f"💾 {self._t('common.save')}", callback_data="tg_settings:save"),
InlineButton(text=f"✖️ {self._t('common.cancel')}", callback_data="tg_settings:cancel"),
]
)
return "\n".join(lines), InlineKeyboard(buttons=rows)
async def _handle_settings_callback(self, context: MessageContext, callback_data: str) -> None:
scope_key = self._interaction_scope_key(context)
state = self._settings_states.get(scope_key)
if state is None or state.message_id != (context.message_id or ""):
return
settings_manager = self.settings_manager
message_types = list(settings_manager.get_available_message_types()) if settings_manager else []
parts = callback_data.split(":")
action = parts[1] if len(parts) > 1 else ""
if action == "cancel":
self._settings_states.pop(scope_key, None)
await self._delete_interaction_message(context, state.message_id)
return
if action == "save":
self._settings_states.pop(scope_key, None)
if self._controller is None or not hasattr(self._controller, "settings_handler"):
await self.send_message(context, f"❌ {self._t('error.settingsFailed')}")
return
await self._delete_interaction_message(context, state.message_id)
settings_update = {
"user_id": context.user_id,
"show_message_types": state.show_message_types,
"channel_id": context.channel_id,
"require_mention": state.current_require_mention,
"language": state.current_language,
"notify_user": True,
"is_dm": state.is_dm,
"platform": "telegram",
}
state_thread_id = getattr(state, "thread_id", None)
if state_thread_id is not None:
settings_update["thread_id"] = state_thread_id
await self._controller.settings_handler.handle_settings_update(**settings_update)
return
if action == "toggle" and len(parts) > 2:
msg_type = parts[2]
if msg_type in state.show_message_types:
state.show_message_types = [item for item in state.show_message_types if item != msg_type]
elif msg_type in message_types:
state.show_message_types.append(msg_type)
elif action == "mention" and len(parts) > 2:
value = parts[2]
if value == "default":
state.current_require_mention = None
elif value == "on":
state.current_require_mention = True
elif value == "off":
state.current_require_mention = False
elif action == "lang" and len(parts) > 2 and parts[2] in get_supported_languages():
state.current_language = parts[2]
text, keyboard = self._render_settings_state(state, message_types)
await self.edit_message(context, state.message_id, text=text, keyboard=keyboard)