Add configurable Telegram parse mode

Author: clown145

apps/admin-web/src/api/client.ts

@@ -216,6 +216,7 @@ export function createAdminClient(getToken: () => string) {
       name: string;
       botToken?: string;
       webhookSecret?: string;
+      parseMode?: TelegramIntegration["parseMode"];
     }) => {
       return request<ApiResult<{ integration: TelegramIntegration }>>(
         "/admin/platforms/telegram",
@@ -225,6 +226,18 @@ export function createAdminClient(getToken: () => string) {
         }
       );
     },
+    updateTelegramIntegration: (
+      integrationId: string,
+      body: { parseMode?: TelegramIntegration["parseMode"] }
+    ) => {
+      return request<ApiResult<{ integration: TelegramIntegration }>>(
+        `/admin/platforms/telegram/${integrationId}`,
+        {
+          method: "PUT",
+          body: JSON.stringify(body)
+        }
+      );
+    },
     testTelegramIntegration: (integrationId: string) => {
       return request<ApiResult<{ integration: TelegramIntegration; bot: unknown; webhook: unknown }>>(
         `/admin/platforms/telegram/${integrationId}/test`,

apps/admin-web/src/api/types.ts

@@ -309,6 +309,7 @@ export type TelegramIntegration = {
   name: string;
   status: string;
   webhookSecretConfigured: boolean;
+  parseMode: "none" | "HTML" | "MarkdownV2";
   hasCredential: boolean;
   lastCheckedAt?: string;
   lastError?: string;

apps/admin-web/src/styles/panels.css

@@ -44,6 +44,7 @@
     minmax(140px, 0.8fr)
     minmax(220px, 1.2fr)
     minmax(220px, 1.2fr)
+    minmax(120px, 0.6fr)
     auto;
   gap: 10px;
   align-items: end;
@@ -516,7 +517,7 @@
 
 .telegram-row {
   display: grid;
-  grid-template-columns: minmax(0, 1fr) auto auto auto auto auto;
+  grid-template-columns: minmax(0, 1fr) minmax(120px, 160px) auto auto auto auto auto;
   gap: 10px;
   align-items: center;
   border: 1px solid var(--border);
@@ -536,6 +537,14 @@
   font-size: 12px;
 }
 
+.inline-select-label {
+  display: grid;
+  gap: 4px;
+  min-width: 0;
+  color: var(--text-muted);
+  font-size: 12px;
+}
+
 .search-provider-row {
   display: grid;
   grid-template-columns: minmax(0, 1fr) auto auto auto auto auto;

apps/admin-web/src/ui/i18n/translations.ts

@@ -172,8 +172,11 @@ export const translations: Record<Locale, Record<string, string>> = {
     "platforms.name": "名称",
     "platforms.botToken": "Bot Token",
     "platforms.webhookSecret": "Webhook Secret",
+    "platforms.parseMode": "格式模式",
+    "platforms.parseModeNone": "纯文本",
     "platforms.telegramSaved": "Telegram 集成已保存",
     "platforms.telegramSavedWebhook": "Telegram 集成已保存并设置 webhook",
+    "platforms.integrationUpdated": "Telegram 集成已更新",
     "platforms.botTested": "Telegram bot 测试完成",
     "platforms.webhookSet": "Telegram webhook 已设置",
     "platforms.webhookDeleted": "Telegram webhook 已删除",
@@ -420,8 +423,11 @@ export const translations: Record<Locale, Record<string, string>> = {
     "platforms.name": "Name",
     "platforms.botToken": "Bot token",
     "platforms.webhookSecret": "Webhook secret",
+    "platforms.parseMode": "Parse mode",
+    "platforms.parseModeNone": "Plain text",
     "platforms.telegramSaved": "Telegram integration saved",
     "platforms.telegramSavedWebhook": "Telegram integration saved and webhook set",
+    "platforms.integrationUpdated": "Telegram integration updated",
     "platforms.botTested": "Telegram bot tested",
     "platforms.webhookSet": "Telegram webhook set",
     "platforms.webhookDeleted": "Telegram webhook deleted",

apps/admin-web/src/ui/panels/PlatformsPanel.tsx

@@ -20,7 +20,8 @@ export function PlatformsPanel({ client, notify }: PanelProps) {
     agentId: "default",
     name: "Telegram",
     botToken: "",
-    webhookSecret: ""
+    webhookSecret: "",
+    parseMode: "HTML"
   });
 
   async function load() {
@@ -39,7 +40,8 @@ export function PlatformsPanel({ client, notify }: PanelProps) {
         agentId: draft.agentId || undefined,
         name: draft.name,
         botToken: draft.botToken || undefined,
-        webhookSecret: draft.webhookSecret || undefined
+        webhookSecret: draft.webhookSecret || undefined,
+        parseMode: draft.parseMode
       });
       if (draft.botToken) {
         const webhook = await client.setTelegramWebhook(
@@ -75,6 +77,16 @@ export function PlatformsPanel({ client, notify }: PanelProps) {
     await runAction(() => client.deleteTelegramWebhook(id), t("platforms.webhookDeleted"));
   }
 
+  async function updateParseMode(
+    id: string,
+    parseMode: TelegramIntegration["parseMode"]
+  ) {
+    await runAction(
+      () => client.updateTelegramIntegration(id, { parseMode }),
+      t("platforms.integrationUpdated")
+    );
+  }
+
   async function deleteIntegration(id: string) {
     await runAction(() => client.deleteTelegramIntegration(id), t("platforms.integrationDeleted"));
   }
@@ -119,6 +131,7 @@ export function PlatformsPanel({ client, notify }: PanelProps) {
 
       <TelegramIntegrationList
         integrations={integrations}
+        onUpdateParseMode={(id, parseMode) => void updateParseMode(id, parseMode)}
         onTest={(id) => void testIntegration(id)}
         onSetWebhook={(id) => void setWebhook(id)}
         onDeleteWebhook={(id) => void deleteWebhook(id)}

apps/admin-web/src/ui/panels/platforms/TelegramIntegrationForm.tsx

@@ -1,11 +1,13 @@
 import { Plus } from "lucide-react";
+import type { TelegramIntegration } from "../../../api/types";
 import { useI18n } from "../../i18n/I18nProvider";
 
 export type TelegramIntegrationDraft = {
   agentId: string;
   name: string;
   botToken: string;
   webhookSecret: string;
+  parseMode: TelegramIntegration["parseMode"];
 };
 
 type TelegramIntegrationFormProps = {
@@ -54,6 +56,22 @@ export function TelegramIntegrationForm({
           onChange={(event) => onDraftChange({ ...draft, webhookSecret: event.target.value })}
         />
       </label>
+      <label>
+        {t("platforms.parseMode")}
+        <select
+          value={draft.parseMode}
+          onChange={(event) =>
+            onDraftChange({
+              ...draft,
+              parseMode: event.target.value as TelegramIntegration["parseMode"]
+            })
+          }
+        >
+          <option value="HTML">HTML</option>
+          <option value="MarkdownV2">MarkdownV2</option>
+          <option value="none">{t("platforms.parseModeNone")}</option>
+        </select>
+      </label>
       <button className="primary-button" type="button" onClick={onSubmit}>
         <Plus size={16} />
         {t("common.add")}

apps/admin-web/src/ui/panels/platforms/TelegramIntegrationList.tsx

@@ -6,6 +6,10 @@ import { ToolbarButton } from "../../ToolbarButton";
 
 type TelegramIntegrationListProps = {
   integrations: TelegramIntegration[];
+  onUpdateParseMode: (
+    integrationId: string,
+    parseMode: TelegramIntegration["parseMode"]
+  ) => void;
   onTest: (integrationId: string) => void;
   onSetWebhook: (integrationId: string) => void;
   onDeleteWebhook: (integrationId: string) => void;
@@ -14,6 +18,7 @@ type TelegramIntegrationListProps = {
 
 export function TelegramIntegrationList({
   integrations,
+  onUpdateParseMode,
   onTest,
   onSetWebhook,
   onDeleteWebhook,
@@ -36,6 +41,22 @@ export function TelegramIntegrationList({
             </span>
             {integration.lastError && <span>{integration.lastError}</span>}
           </div>
+          <label className="inline-select-label">
+            {t("platforms.parseMode")}
+            <select
+              value={integration.parseMode}
+              onChange={(event) =>
+                onUpdateParseMode(
+                  integration.id,
+                  event.target.value as TelegramIntegration["parseMode"]
+                )
+              }
+            >
+              <option value="HTML">HTML</option>
+              <option value="MarkdownV2">MarkdownV2</option>
+              <option value="none">{t("platforms.parseModeNone")}</option>
+            </select>
+          </label>
           <StatusBadge value={integration.status} />
           <ToolbarButton
             label={t("platforms.testBot")}

src/adapters/telegram/formatting.ts

@@ -0,0 +1,30 @@
+export type TelegramParseMode = "none" | "HTML" | "MarkdownV2";
+
+export const DEFAULT_TELEGRAM_PARSE_MODE: TelegramParseMode = "HTML";
+
+export function normalizeTelegramParseMode(value: unknown): TelegramParseMode {
+  return value === "none" || value === "HTML" || value === "MarkdownV2"
+    ? value
+    : DEFAULT_TELEGRAM_PARSE_MODE;
+}
+
+export function telegramParseModePayload(
+  parseMode: TelegramParseMode
+): "HTML" | "MarkdownV2" | undefined {
+  return parseMode === "none" ? undefined : parseMode;
+}
+
+export function stripTelegramMarkup(text: string): string {
+  return text
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/(p|div|section|article|li|h[1-6])>/gi, "\n")
+    .replace(/<a\s+[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, "$2 ($1)")
+    .replace(/<\/?(b|strong|i|em|u|s|strike|del|code|pre|blockquote|tg-spoiler)[^>]*>/gi, "")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .replace(/&quot;/g, "\"")
+    .replace(/&#39;/g, "'")
+    .trim();
+}

src/adapters/telegram/outbound.ts

@@ -1,6 +1,11 @@
 import type { Env } from "../../shared/types/env";
 import { callTelegramApi } from "./api";
 import { resolveTelegramBotForAgent } from "./config";
+import {
+  normalizeTelegramParseMode,
+  stripTelegramMarkup,
+  telegramParseModePayload
+} from "./formatting";
 
 export type PlatformSendResult = {
   ok: boolean;
@@ -20,22 +25,64 @@ export async function sendTelegramText(
   }
 
   const chatId = conversationId.replace(/^telegram:/, "");
+  const parseMode = normalizeTelegramParseMode(bot.integration?.config.parseMode);
+  const requestBody: Record<string, unknown> = {
+    chat_id: chatId,
+    text,
+    disable_web_page_preview: true
+  };
+  const parseModePayload = telegramParseModePayload(parseMode);
+  if (parseModePayload) {
+    requestBody.parse_mode = parseModePayload;
+  }
+
   try {
     const payload = await callTelegramApi<{ message_id?: number }>(
       bot.token,
       "sendMessage",
-      {
-        chat_id: chatId,
-        text,
-        disable_web_page_preview: true
-      }
+      requestBody
     );
 
     return {
       ok: true,
       providerMessageId: payload.message_id ? String(payload.message_id) : undefined
     };
   } catch (error) {
+    if (parseMode !== "none") {
+      const fallback = await sendPlainTextFallback(bot.token, chatId, text).catch(
+        (fallbackError) => ({
+          ok: false as const,
+          error: fallbackError instanceof Error
+            ? fallbackError.message
+            : "Telegram fallback send failed"
+        })
+      );
+      if (fallback.ok) {
+        return fallback;
+      }
+    }
+
     return { ok: false, error: error instanceof Error ? error.message : "Telegram send failed" };
   }
 }
+
+async function sendPlainTextFallback(
+  token: string,
+  chatId: string,
+  text: string
+): Promise<PlatformSendResult> {
+  const payload = await callTelegramApi<{ message_id?: number }>(
+    token,
+    "sendMessage",
+    {
+      chat_id: chatId,
+      text: stripTelegramMarkup(text),
+      disable_web_page_preview: true
+    }
+  );
+
+  return {
+    ok: true,
+    providerMessageId: payload.message_id ? String(payload.message_id) : undefined
+  };
+}

src/core/agent-context.ts

@@ -2,6 +2,7 @@ import type { RegisteredTool } from "../tools/types";
 import type { InternalMessage } from "../shared/types/internal-message";
 import type { SelectedSkill } from "../skills/skill-selector";
 import type { ModelMessage, ModelTool } from "./model/types";
+import type { TelegramParseMode } from "../adapters/telegram/formatting";
 
 export type ConversationContextMessage = {
   id: string;
@@ -11,6 +12,7 @@ export type ConversationContextMessage = {
 
 export type AgentContextOptions = {
   timeZone?: string;
+  telegramParseMode?: TelegramParseMode;
 };
 
 export function createInitialModelMessages(
@@ -47,7 +49,7 @@ function createBaseInstructions(
     "Use tools when a task requires reading or writing the virtual filesystem, sending messages, or performing external actions.",
     "Use search.web to find candidate pages, then use web.fetch_page to read and verify pages when the user asks for details, latest information, or claims that need support.",
     "Do not force a search result count unless the user explicitly requests one; the system search settings control the normal result count.",
-    platformFormatInstruction(message.platform),
+    platformFormatInstruction(message.platform, options),
     "When the task is complete, answer concisely in the user's language.",
     "Do not claim a tool action succeeded unless a tool result confirms it."
   ].join("\n");
@@ -88,12 +90,32 @@ function normalizeTimeZone(timeZone?: string): string {
   return timeZone?.trim() || "UTC";
 }
 
-function platformFormatInstruction(platform: InternalMessage["platform"]): string {
+function platformFormatInstruction(
+  platform: InternalMessage["platform"],
+  options: AgentContextOptions
+): string {
   if (platform === "telegram") {
+    if (options.telegramParseMode === "none") {
+      return [
+        "Telegram formatting: messages are sent as plain text.",
+        "Avoid Markdown tables, HTML tags, and formatting that requires Telegram parse mode.",
+        "Use short sections, numbered lines, plain URLs, and compact text."
+      ].join("\n");
+    }
+
+    if (options.telegramParseMode === "MarkdownV2") {
+      return [
+        "Telegram formatting: messages are sent with Telegram parse_mode MarkdownV2.",
+        "MarkdownV2 requires escaping reserved characters: _ * [ ] ( ) ~ ` > # + - = | { } . !",
+        "Prefer simple bold/italic/code only when you can escape correctly; avoid tables and complex formatting."
+      ].join("\n");
+    }
+
     return [
-      "Telegram formatting: messages are currently sent as plain text without parse_mode.",
-      "Avoid Markdown tables, HTML tags, and formatting that requires Telegram Markdown parsing.",
-      "Use short sections, numbered lines, plain URLs, and compact text."
+      "Telegram formatting: messages are sent with Telegram parse_mode HTML by default.",
+      "Use only Telegram-supported HTML tags when useful: <b>, <i>, <u>, <s>, <code>, <pre>, <a href=\"https://...\">text</a>.",
+      "Escape literal <, >, and & when they are not part of supported tags.",
+      "Avoid Markdown tables and MarkdownV2-specific syntax; use short sections, numbered lines, plain URLs, and compact text."
     ].join("\n");
   }