Skip to content

Agent Zero AI framework

Improve Telegram plugin settings experience

Alessandroc37d2731d7e5
diff --git a/plugins/_telegram_integration/AGENTS.md b/plugins/_telegram_integration/AGENTS.md
index e18285205..a7e027c77 100644
--- a/plugins/_telegram_integration/AGENTS.md
+++ b/plugins/_telegram_integration/AGENTS.md
@@ -10,6 +10,7 @@
- `helpers/handler.py` and `helpers/telegram_client.py` own message routing, replies, and Telegram API interaction.
- `helpers/dependencies.py` and `requirements.txt` own framework-runtime dependency bootstrap.
- `api/`, `prompts/`, `extensions/`, `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own tests/webhook endpoints, prompt fragments, hooks, settings, metadata, docs, and UI.
+- `webui/main.html`, `webui/telegram-main-store.js`, and `api/status.py` own the secret-free runtime dashboard opened from the plugin list.
## Local Contracts
@@ -17,6 +18,8 @@
- Keep allowed-user, group-mode, project, model, and `/send` controls enforced.
- Webhook dispatch requires an active webhook and a matching nonempty secret header. Setup requires a random 32–256 character secret using letters, digits, `_` or `-`; polling and webhook removal revoke HTTP delivery.
- Install Telegram dependencies into the framework runtime only when required.
+- Keep project and agent-profile configuration scopes available through the shared plugin settings modal.
+- Runtime status responses may expose bot labels, Telegram usernames, delivery modes, and lifecycle state, but never tokens or webhook secrets.
- Agent profile picker actions change the top-level chat profile and must
preserve existing subordinate agent profiles. Picker rows and direct matches
use the shared presentation catalog while current status may still report an
diff --git a/plugins/_telegram_integration/api/status.py b/plugins/_telegram_integration/api/status.py
new file mode 100644
index 000000000..26e955219
--- /dev/null
+++ b/plugins/_telegram_integration/api/status.py
@@ -0,0 +1,47 @@
+from helpers import plugins
+from helpers.api import ApiHandler, Request
+
+
+class Status(ApiHandler):
+
+ async def process(self, input: dict, request: Request) -> dict:
+ config = plugins.get_plugin_config("_telegram_integration") or {}
+ try:
+ from plugins._telegram_integration.helpers.bot_manager import get_all_bots
+ running = get_all_bots()
+ except Exception:
+ running = {}
+
+ bots = []
+ for index, bot_cfg in enumerate(config.get("bots") or []):
+ name = str(bot_cfg.get("name") or f"Bot {index + 1}")
+ instance = running.get(name)
+ task = getattr(instance, "task", None)
+ active = bool(instance and (getattr(instance, "webhook_active", False) or (task and not task.done())))
+ info = getattr(instance, "bot_info", None)
+ if not bot_cfg.get("token"):
+ state = "Needs token"
+ elif not bot_cfg.get("enabled"):
+ state = "Disabled"
+ elif active:
+ state = "Running"
+ else:
+ state = "Ready"
+ bots.append({
+ "name": name,
+ "enabled": bool(bot_cfg.get("enabled")),
+ "configured": bool(bot_cfg.get("token")),
+ "running": active,
+ "state": state,
+ "mode": "Webhook" if getattr(instance, "webhook_active", False) else str(bot_cfg.get("mode") or "polling").title(),
+ "username": f"@{info.username}" if getattr(info, "username", None) else "",
+ "access": f"{len(bot_cfg.get('allowed_users') or [])} allowed" if bot_cfg.get("allowed_users") else "Open access",
+ "project": str(bot_cfg.get("default_project") or "No project"),
+ })
+
+ return {
+ "ok": True,
+ "configured": sum(bot["configured"] for bot in bots),
+ "running": sum(bot["running"] for bot in bots),
+ "bots": bots,
+ }
diff --git a/plugins/_telegram_integration/plugin.yaml b/plugins/_telegram_integration/plugin.yaml
index 72bbf76a5..7953e6482 100644
--- a/plugins/_telegram_integration/plugin.yaml
+++ b/plugins/_telegram_integration/plugin.yaml
@@ -4,5 +4,5 @@ description: Communicate with Agent Zero via Telegram. Supports polling and webh
version: 1.0.0
settings_sections:
- external
-per_project_config: false
-per_agent_config: false
+per_project_config: true
+per_agent_config: true
diff --git a/plugins/_telegram_integration/webui/config.html b/plugins/_telegram_integration/webui/config.html
index 2fcf51c02..1ba6c0e65 100644
--- a/plugins/_telegram_integration/webui/config.html
+++ b/plugins/_telegram_integration/webui/config.html
@@ -261,13 +261,14 @@
</template>
<template x-if="$store.telegramConfig.currentStep > 0">
- <details class="tg-advanced">
- <summary>
+ <div class="settings-advanced-section" x-data="{ advOpen: false }">
+ <button type="button" class="settings-advanced-toggle"
+ :aria-expanded="advOpen" @click="advOpen = !advOpen">
+ <x-icon class="settings-advanced-toggle-icon"
+ :style="advOpen ? 'transform:rotate(90deg)' : ''" name="chevron_right"></x-icon>
<span>Advanced</span>
- <x-icon class="tg-advanced-chevron"
- aria-hidden="true" name="keyboard_arrow_down"></x-icon>
- </summary>
- <div class="tg-advanced-body">
+ </button>
+ <div class="settings-advanced-body" x-show="advOpen" x-transition.opacity style="display: none;">
<div class="field" x-show="bot.mode === 'webhook'">
<div class="field-label">
<div class="field-title">Webhook secret</div>
@@ -318,7 +319,7 @@
</div>
</div>
- </details>
+ </div>
</template>
</div>
</template>
@@ -341,19 +342,6 @@
gap: 0.9rem;
}
- .tg-advanced summary {
- cursor: pointer;
- list-style: none;
- font-weight: 700;
- display: flex;
- align-items: center;
- gap: 0.75rem;
- }
-
- .tg-advanced summary::-webkit-details-marker {
- display: none;
- }
-
.tg-guide-card,
.tg-empty,
.tg-card {
@@ -534,37 +522,6 @@
background: color-mix(in srgb, #f59e0b 14%, var(--color-background) 86%);
}
- .tg-advanced {
- margin-top: 0.95rem;
- border: 1px solid color-mix(in srgb, var(--color-border) 88%, white 12%);
- border-radius: 14px;
- overflow: hidden;
- }
-
- .tg-advanced summary {
- padding: 0.9rem 1rem;
- background: color-mix(in srgb, var(--color-background) 88%, white 12%);
- }
-
- .tg-advanced-chevron {
- margin-left: auto;
- flex: 0 0 auto;
- transition: transform 0.18s ease, opacity 0.18s ease;
- opacity: 0.72;
- }
-
- .tg-advanced[open] .tg-advanced-chevron {
- transform: rotate(180deg);
- opacity: 1;
- }
-
- .tg-advanced-body {
- padding: 1rem;
- display: flex;
- flex-direction: column;
- gap: 0.2rem;
- }
-
.tg-test-panel {
margin-top: 1rem;
padding: var(--spacing-xs) 0;
diff --git a/plugins/_telegram_integration/webui/main.html b/plugins/_telegram_integration/webui/main.html
new file mode 100644
index 000000000..2386c2fca
--- /dev/null
+++ b/plugins/_telegram_integration/webui/main.html
@@ -0,0 +1,82 @@
+<html>
+<head>
+ <title>Telegram Integration</title>
+ <script type="module">
+ import { store } from "/plugins/_telegram_integration/webui/telegram-main-store.js";
+ </script>
+</head>
+<body>
+ <div x-data>
+ <template x-if="$store.telegramMain">
+ <section class="tg-main" x-init="$store.telegramMain.refresh()" :aria-busy="$store.telegramMain.loading">
+ <header class="tg-main-header">
+ <div>
+ <div class="section-title">Telegram</div>
+ <div class="section-description">Connect Telegram bots to Agent Zero conversations.</div>
+ </div>
+ <div class="tg-main-actions">
+ <button type="button" class="btn btn-field" @click="$store.telegramMain.refresh()"
+ :disabled="$store.telegramMain.loading">
+ <x-icon name="refresh"></x-icon>
+ <span>Refresh</span>
+ </button>
+ <button type="button" class="btn btn-field" @click="$store.telegramMain.openConfig()">
+ <x-icon name="settings"></x-icon>
+ <span>Config</span>
+ </button>
+ </div>
+ </header>
+
+ <div class="tg-main-summary">
+ <div><strong x-text="$store.telegramMain.configured"></strong><span>Configured</span></div>
+ <div><strong x-text="$store.telegramMain.running"></strong><span>Running</span></div>
+ </div>
+
+ <p class="tg-main-empty" x-show="!$store.telegramMain.loading && !$store.telegramMain.bots.length">
+ No Telegram bots are configured yet. Open Config to connect one.
+ </p>
+
+ <div class="tg-main-bots">
+ <template x-for="bot in $store.telegramMain.bots" :key="bot.name">
+ <article class="tg-main-bot">
+ <div class="tg-main-bot-heading">
+ <div>
+ <h4 x-text="bot.username || bot.name"></h4>
+ <span x-show="bot.username" x-text="bot.name"></span>
+ </div>
+ <span class="tg-main-state" x-text="bot.state"></span>
+ </div>
+ <dl>
+ <div><dt>Delivery</dt><dd x-text="bot.mode"></dd></div>
+ <div><dt>Access</dt><dd x-text="bot.access"></dd></div>
+ <div><dt>Project</dt><dd x-text="bot.project"></dd></div>
+ </dl>
+ </article>
+ </template>
+ </div>
+ </section>
+ </template>
+ </div>
+
+ <style>
+ .tg-main { display: flex; flex-direction: column; gap: var(--spacing-md); color: var(--color-text); font-family: var(--font-family-main); }
+ .tg-main-header, .tg-main-actions, .tg-main-bot-heading { display: flex; align-items: center; justify-content: space-between; gap: var(--spacing-sm); flex-wrap: wrap; }
+ .tg-main-actions .btn { display: inline-flex; align-items: center; gap: var(--spacing-xs); }
+ .tg-main-summary { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); border-block: 1px solid var(--color-border); }
+ .tg-main-summary div { display: flex; align-items: baseline; gap: var(--spacing-xs); padding: var(--spacing-sm) 0; color: var(--color-text-muted); }
+ .tg-main-summary strong { color: var(--color-text); font-size: 1.25rem; }
+ .tg-main-bots { display: grid; gap: var(--spacing-sm); }
+ .tg-main-bot { padding: var(--spacing-md); border: 1px solid var(--color-border); border-radius: var(--border-radius-sm); }
+ .tg-main-bot h4 { margin: 0; color: var(--color-text); }
+ .tg-main-bot-heading span, .tg-main-empty, .tg-main-bot dt { color: var(--color-text-muted); font-size: var(--font-size-small); }
+ .tg-main-state { padding: var(--spacing-xs) var(--spacing-sm); border-radius: var(--border-radius-sm); background: var(--color-input); }
+ .tg-main-bot dl { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: var(--spacing-sm); margin: var(--spacing-md) 0 0; }
+ .tg-main-bot dd { margin: var(--spacing-xxs) 0 0; overflow-wrap: anywhere; }
+ @media (max-width: 540px) {
+ .tg-main-actions { width: 100%; }
+ .tg-main-actions .btn { flex: 1; justify-content: center; }
+ .tg-main-bot dl { grid-template-columns: 1fr; }
+ }
+ </style>
+</body>
+</html>
diff --git a/plugins/_telegram_integration/webui/telegram-main-store.js b/plugins/_telegram_integration/webui/telegram-main-store.js
new file mode 100644
index 000000000..1a2f5886a
--- /dev/null
+++ b/plugins/_telegram_integration/webui/telegram-main-store.js
@@ -0,0 +1,34 @@
+import { createStore } from "/js/AlpineStore.js";
+import { callJsonApi } from "/js/api.js";
+import { toastFrontendError } from "/components/notifications/notification-store.js";
+import { store as pluginSettings } from "/components/plugins/plugin-settings-store.js";
+
+export const store = createStore("telegramMain", {
+ bots: [],
+ configured: 0,
+ running: 0,
+ loading: false,
+
+ async refresh() {
+ if (this.loading) return;
+ this.loading = true;
+ try {
+ const data = await callJsonApi("/plugins/_telegram_integration/status", {});
+ this.bots = data.bots || [];
+ this.configured = Number(data.configured || 0);
+ this.running = Number(data.running || 0);
+ } catch (error) {
+ void toastFrontendError(error, "Telegram status");
+ } finally {
+ this.loading = false;
+ }
+ },
+
+ async openConfig() {
+ try {
+ await pluginSettings.openConfig("_telegram_integration");
+ } catch (error) {
+ void toastFrontendError(error, "Telegram configuration");
+ }
+ },
+});
diff --git a/tests/test_telegram_plugin_ui.py b/tests/test_telegram_plugin_ui.py
new file mode 100644
index 000000000..f4d0e265c
--- /dev/null
+++ b/tests/test_telegram_plugin_ui.py
@@ -0,0 +1,46 @@
+import asyncio
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+import yaml
+
+from plugins._telegram_integration.api import status as status_api
+from plugins._telegram_integration.helpers import bot_manager
+
+
+ROOT = Path(__file__).parents[1] / "plugins" / "_telegram_integration"
+
+
+def test_telegram_plugin_exposes_scoped_open_and_config_pages(monkeypatch):
+ manifest = yaml.safe_load((ROOT / "plugin.yaml").read_text())
+ config = (ROOT / "webui" / "config.html").read_text()
+ main = (ROOT / "webui" / "main.html").read_text()
+
+ assert manifest["per_project_config"] is True
+ assert manifest["per_agent_config"] is True
+ assert "settings-advanced-section" in config
+ assert 'class="tg-advanced"' not in config
+ assert ".tg-advanced" not in config
+ assert "telegram-main-store.js" in main
+
+ task = SimpleNamespace(done=lambda: False)
+ runtime = SimpleNamespace(
+ task=task,
+ webhook_active=False,
+ bot_info=SimpleNamespace(username="live_bot"),
+ )
+ monkeypatch.setattr(status_api.plugins, "get_plugin_config", lambda _name: {
+ "bots": [
+ {"name": "Live", "enabled": True, "token": "secret-token", "mode": "polling", "allowed_users": [1]},
+ {"name": "Draft", "enabled": False, "token": "", "webhook_secret": "secret-hook"},
+ ]
+ })
+ monkeypatch.setattr(bot_manager, "get_all_bots", lambda: {"Live": runtime})
+
+ result = asyncio.run(status_api.Status(None, None).process({}, None))
+ assert result["configured"] == 1
+ assert result["running"] == 1
+ assert result["bots"][0]["username"] == "@live_bot"
+ assert "secret-token" not in json.dumps(result)
+ assert "secret-hook" not in json.dumps(result)