fix(bot): retry MarkdownV2 send/edit with escaped reserved characters

Author: grinev

src/bot/utils/send-with-markdown-fallback.ts

@@ -31,6 +31,12 @@ const MARKDOWN_PARSE_ERROR_MARKERS = [
   "bad request: can't parse",
 ];
 
+const MARKDOWN_V2_RESERVED_CHARS = /([_\*\[\]\(\)~`>#+\-=|{}.!\\])/g;
+
+function escapeTelegramMarkdownV2(text: string): string {
+  return text.replace(MARKDOWN_V2_RESERVED_CHARS, "\\$1");
+}
+
 function stripMarkdownFormattingOptions<
   T extends TelegramSendMessageOptions | TelegramEditMessageOptions | undefined,
 >(options: T): T {
@@ -115,6 +121,30 @@ export async function sendMessageWithMarkdownFallback({
       throw error;
     }
 
+    if (parseMode === "MarkdownV2") {
+      const escapedText = escapeTelegramMarkdownV2(text);
+      if (escapedText !== text) {
+        logger.warn(
+          "[Bot] Markdown parse failed, retrying assistant message with escaped MarkdownV2",
+          error,
+        );
+
+        try {
+          return await api.sendMessage(chatId, escapedText, markdownOptions);
+        } catch (escapedError) {
+          if (!isTelegramMarkdownParseError(escapedError)) {
+            throw escapedError;
+          }
+
+          logger.warn(
+            "[Bot] Escaped Markdown parse failed, retrying assistant message in raw mode",
+            escapedError,
+          );
+          return api.sendMessage(chatId, text, stripMarkdownFormattingOptions(options));
+        }
+      }
+    }
+
     logger.warn("[Bot] Markdown parse failed, retrying assistant message in raw mode", error);
     return api.sendMessage(chatId, text, stripMarkdownFormattingOptions(options));
   }
@@ -146,6 +176,35 @@ export async function editMessageWithMarkdownFallback({
       throw error;
     }
 
+    if (parseMode === "MarkdownV2") {
+      const escapedText = escapeTelegramMarkdownV2(text);
+      if (escapedText !== text) {
+        logger.warn(
+          "[Bot] Markdown parse failed, retrying edited message with escaped MarkdownV2",
+          error,
+        );
+
+        try {
+          return await api.editMessageText(chatId, messageId, escapedText, markdownOptions);
+        } catch (escapedError) {
+          if (!isTelegramMarkdownParseError(escapedError)) {
+            throw escapedError;
+          }
+
+          logger.warn(
+            "[Bot] Escaped Markdown parse failed, retrying edited message in raw mode",
+            escapedError,
+          );
+          return api.editMessageText(
+            chatId,
+            messageId,
+            text,
+            stripMarkdownFormattingOptions(options),
+          );
+        }
+      }
+    }
+
     logger.warn("[Bot] Markdown parse failed, retrying edited message in raw mode", error);
     return api.editMessageText(chatId, messageId, text, stripMarkdownFormattingOptions(options));
   }

tests/bot/utils/send-with-markdown-fallback.test.ts

@@ -44,8 +44,9 @@ describe("bot/utils/send-with-markdown-fallback", () => {
       reply_markup: { keyboard: [] },
       parse_mode: "MarkdownV2",
     });
-    expect(sendMessage).toHaveBeenNthCalledWith(2, 123, "<broken>", {
+    expect(sendMessage).toHaveBeenNthCalledWith(2, 123, "<broken\\>", {
       reply_markup: { keyboard: [] },
+      parse_mode: "MarkdownV2",
     });
   });
 
@@ -55,6 +56,9 @@ describe("bot/utils/send-with-markdown-fallback", () => {
       .mockRejectedValueOnce(
         new Error("Bad Request: can't parse entities: Character '+' is reserved"),
       )
+      .mockRejectedValueOnce(
+        new Error("Bad Request: can't parse entities: Character '+' is reserved"),
+      )
       .mockResolvedValueOnce(undefined);
 
     await sendMessageWithMarkdownFallback({
@@ -69,17 +73,46 @@ describe("bot/utils/send-with-markdown-fallback", () => {
       parseMode: "MarkdownV2",
     });
 
-    expect(sendMessage).toHaveBeenCalledTimes(2);
+    expect(sendMessage).toHaveBeenCalledTimes(3);
     expect(sendMessage).toHaveBeenNthCalledWith(1, 777, "a+b", {
       reply_markup: { keyboard: [] },
       parse_mode: "MarkdownV2",
       entities: [],
     });
-    expect(sendMessage).toHaveBeenNthCalledWith(2, 777, "a+b", {
+    expect(sendMessage).toHaveBeenNthCalledWith(2, 777, "a\\+b", {
+      reply_markup: { keyboard: [] },
+      parse_mode: "MarkdownV2",
+      entities: [],
+    });
+    expect(sendMessage).toHaveBeenNthCalledWith(3, 777, "a+b", {
       reply_markup: { keyboard: [] },
     });
   });
 
+  it("retries with escaped MarkdownV2 for reserved parentheses", async () => {
+    const sendMessage = vi
+      .fn()
+      .mockRejectedValueOnce(
+        new Error("Bad Request: can't parse entities: Character '(' is reserved"),
+      )
+      .mockResolvedValueOnce(undefined);
+
+    await sendMessageWithMarkdownFallback({
+      api: { sendMessage },
+      chatId: 888,
+      text: "Cost (USD)",
+      parseMode: "MarkdownV2",
+    });
+
+    expect(sendMessage).toHaveBeenCalledTimes(2);
+    expect(sendMessage).toHaveBeenNthCalledWith(1, 888, "Cost (USD)", {
+      parse_mode: "MarkdownV2",
+    });
+    expect(sendMessage).toHaveBeenNthCalledWith(2, 888, "Cost \\(USD\\)", {
+      parse_mode: "MarkdownV2",
+    });
+  });
+
   it("does not swallow non-markdown Telegram errors", async () => {
     const sendMessage = vi
       .fn()
@@ -167,8 +200,9 @@ describe("bot/utils/send-with-markdown-fallback", () => {
       reply_markup: { inline_keyboard: [] },
       parse_mode: "MarkdownV2",
     });
-    expect(editMessageText).toHaveBeenNthCalledWith(2, 42, 8, "<broken>", {
+    expect(editMessageText).toHaveBeenNthCalledWith(2, 42, 8, "<broken\\>", {
       reply_markup: { inline_keyboard: [] },
+      parse_mode: "MarkdownV2",
     });
   });
 
@@ -178,6 +212,9 @@ describe("bot/utils/send-with-markdown-fallback", () => {
       .mockRejectedValueOnce(
         new Error("Bad Request: can't parse entities: Character '+' is reserved"),
       )
+      .mockRejectedValueOnce(
+        new Error("Bad Request: can't parse entities: Character '+' is reserved"),
+      )
       .mockResolvedValueOnce(undefined);
 
     await editMessageWithMarkdownFallback({
@@ -193,13 +230,18 @@ describe("bot/utils/send-with-markdown-fallback", () => {
       parseMode: "MarkdownV2",
     });
 
-    expect(editMessageText).toHaveBeenCalledTimes(2);
+    expect(editMessageText).toHaveBeenCalledTimes(3);
     expect(editMessageText).toHaveBeenNthCalledWith(1, 501, 902, "a+b", {
       reply_markup: { inline_keyboard: [] },
       parse_mode: "MarkdownV2",
       entities: [],
     });
-    expect(editMessageText).toHaveBeenNthCalledWith(2, 501, 902, "a+b", {
+    expect(editMessageText).toHaveBeenNthCalledWith(2, 501, 902, "a\\+b", {
+      reply_markup: { inline_keyboard: [] },
+      parse_mode: "MarkdownV2",
+      entities: [],
+    });
+    expect(editMessageText).toHaveBeenNthCalledWith(3, 501, 902, "a+b", {
       reply_markup: { inline_keyboard: [] },
     });
   });