@elizaos/plugin-telegram 2.0.0-alpha.5 → 2.0.0-alpha.537

package/dist/index.js

@@ -0,0 +1,3157 @@
+import {
+  TelegramAccountAuthSession,
+  clearTelegramAccountAuthState,
+  clearTelegramAccountSession,
+  defaultTelegramAccountDeviceModel,
+  defaultTelegramAccountSystemVersion,
+  loadTelegramAccountSessionString,
+  resolveTelegramAccountSessionFile,
+  saveTelegramAccountSessionString,
+  telegramAccountAuthStateExists,
+  telegramAccountSessionExists
+} from "./chunk-ORNHNB7E.js";
+
+// src/account-setup-routes.ts
+function getSetupService(runtime) {
+  return runtime.getService("connector-setup");
+}
+var telegramAccountAuthSession = null;
+async function stopTelegramAccountAuthSession() {
+  if (telegramAccountAuthSession) {
+    try {
+      await telegramAccountAuthSession.stop();
+    } catch {
+    }
+    telegramAccountAuthSession = null;
+  }
+}
+function readConnectorConfig(config) {
+  const connectors = config.connectors;
+  const raw = connectors?.telegramAccount;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return {};
+  }
+  return raw;
+}
+function hasConfiguredTelegramAccount(connConfig) {
+  return Boolean(
+    typeof connConfig.phone === "string" && connConfig.phone.trim() && (typeof connConfig.appId === "string" || typeof connConfig.appId === "number") && typeof connConfig.appHash === "string" && connConfig.appHash.trim() && typeof connConfig.deviceModel === "string" && connConfig.deviceModel.trim() && typeof connConfig.systemVersion === "string" && connConfig.systemVersion.trim() && connConfig.enabled !== false
+  );
+}
+function resolveConfiguredPhone(runtime, connConfig) {
+  if (typeof connConfig.phone === "string" && connConfig.phone.trim().length > 0) {
+    return connConfig.phone.trim();
+  }
+  const setting = runtime.getSetting("TELEGRAM_ACCOUNT_PHONE");
+  return typeof setting === "string" && setting.trim().length > 0 ? setting.trim() : null;
+}
+function resolveService(runtime) {
+  const service = runtime.getService("telegram-account");
+  return service ?? null;
+}
+function isServiceConnected(service) {
+  if (!service) {
+    return false;
+  }
+  if (typeof service.isConnected === "function") {
+    return service.isConnected();
+  }
+  const withFlags = service;
+  if (typeof withFlags.isServiceConnected === "function") {
+    return withFlags.isServiceConnected();
+  }
+  return withFlags.connected === true;
+}
+function statusFromState(runtime, config) {
+  const connectorConfig = readConnectorConfig(config);
+  const configured = hasConfiguredTelegramAccount(connectorConfig);
+  const sessExists = telegramAccountSessionExists();
+  const authSnapshot = telegramAccountAuthSession?.getSnapshot() ?? null;
+  const service = resolveService(runtime);
+  const serviceConnected = isServiceConnected(service);
+  const serviceAccount = typeof service?.getAccountSummary === "function" ? service.getAccountSummary() : null;
+  const fallbackPhone = resolveConfiguredPhone(runtime, connectorConfig);
+  let status = authSnapshot?.status ?? (serviceConnected ? "connected" : configured || sessExists ? "configured" : "idle");
+  if (serviceConnected && status === "configured") {
+    status = "connected";
+  }
+  return {
+    available: true,
+    status,
+    configured,
+    sessionExists: sessExists,
+    serviceConnected,
+    restartRequired: status === "configured" && !serviceConnected,
+    hasAppCredentials: Boolean(
+      (typeof connectorConfig.appId === "string" || typeof connectorConfig.appId === "number") && typeof connectorConfig.appHash === "string" && connectorConfig.appHash.trim().length > 0
+    ),
+    phone: authSnapshot?.phone ?? fallbackPhone,
+    isCodeViaApp: authSnapshot?.isCodeViaApp ?? false,
+    account: authSnapshot?.account ?? serviceAccount ?? null,
+    error: authSnapshot?.error ?? null
+  };
+}
+function ensureConnectorBlock(config) {
+  if (!config.connectors) {
+    config.connectors = {};
+  }
+  const connectors = config.connectors;
+  if (!connectors.telegramAccount || typeof connectors.telegramAccount !== "object" || Array.isArray(connectors.telegramAccount)) {
+    connectors.telegramAccount = {};
+  }
+  return connectors.telegramAccount;
+}
+function createSessionOptions(config) {
+  const connectorConfig = readConnectorConfig(config);
+  return {
+    deviceModel: typeof connectorConfig.deviceModel === "string" && connectorConfig.deviceModel.trim().length > 0 ? connectorConfig.deviceModel.trim() : defaultTelegramAccountDeviceModel(),
+    systemVersion: typeof connectorConfig.systemVersion === "string" && connectorConfig.systemVersion.trim().length > 0 ? connectorConfig.systemVersion.trim() : defaultTelegramAccountSystemVersion()
+  };
+}
+function ensureAuthSession(config) {
+  if (telegramAccountAuthSession) {
+    return telegramAccountAuthSession;
+  }
+  if (!telegramAccountAuthStateExists()) {
+    return null;
+  }
+  telegramAccountAuthSession = new TelegramAccountAuthSession(
+    createSessionOptions(config)
+  );
+  return telegramAccountAuthSession;
+}
+async function handleStatus(_req, res, runtime) {
+  const setupService = getSetupService(runtime);
+  const config = setupService?.getConfig() ?? {};
+  ensureAuthSession(config);
+  res.status(200).json(statusFromState(runtime, config));
+}
+async function handleAuthStart(req, res, runtime) {
+  const body = req.body ?? {};
+  const setupService = getSetupService(runtime);
+  const config = setupService?.getConfig() ?? {};
+  const connectorConfig = readConnectorConfig(config);
+  const phone = typeof body.phone === "string" && body.phone.trim() || resolveConfiguredPhone(runtime, connectorConfig);
+  if (!phone) {
+    res.status(400).json({ error: "telegram phone number is required" });
+    return;
+  }
+  await telegramAccountAuthSession?.stop();
+  telegramAccountAuthSession = new TelegramAccountAuthSession(
+    createSessionOptions(config)
+  );
+  const credentials = hasConfiguredTelegramAccount(connectorConfig) && (typeof connectorConfig.appId === "string" || typeof connectorConfig.appId === "number") && typeof connectorConfig.appHash === "string" ? {
+    apiId: Number(connectorConfig.appId),
+    apiHash: connectorConfig.appHash
+  } : null;
+  try {
+    await telegramAccountAuthSession.start({ phone, credentials });
+    const resolved = telegramAccountAuthSession.getResolvedConnectorConfig();
+    if (resolved && setupService) {
+      setupService.updateConfig((cfg) => {
+        Object.assign(ensureConnectorBlock(cfg), resolved);
+      });
+    }
+    const freshConfig = setupService?.getConfig() ?? config;
+    res.status(200).json(statusFromState(runtime, freshConfig));
+  } catch (error) {
+    res.status(500).json({
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}
+async function handleAuthSubmit(req, res, runtime) {
+  const body = req.body ?? {};
+  const setupService = getSetupService(runtime);
+  const config = setupService?.getConfig() ?? {};
+  if (!ensureAuthSession(config)) {
+    res.status(400).json({ error: "telegram login session has not been started" });
+    return;
+  }
+  if (!telegramAccountAuthSession) {
+    res.status(400).json({ error: "telegram login session has not been started" });
+    return;
+  }
+  try {
+    await telegramAccountAuthSession.submit(body);
+    const resolved = telegramAccountAuthSession.getResolvedConnectorConfig();
+    if (resolved && setupService) {
+      setupService.updateConfig((cfg) => {
+        Object.assign(ensureConnectorBlock(cfg), resolved);
+      });
+    }
+    const freshConfig = setupService?.getConfig() ?? config;
+    res.status(200).json(statusFromState(runtime, freshConfig));
+  } catch (error) {
+    res.status(500).json({
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}
+async function handleDisconnect(_req, res, runtime) {
+  await telegramAccountAuthSession?.stop();
+  telegramAccountAuthSession = null;
+  clearTelegramAccountAuthState();
+  clearTelegramAccountSession();
+  const service = resolveService(runtime);
+  if (typeof service?.stop === "function") {
+    await service.stop();
+  }
+  const setupService = getSetupService(runtime);
+  if (setupService) {
+    setupService.updateConfig((cfg) => {
+      const connectors = cfg.connectors;
+      if (connectors?.telegramAccount) {
+        delete connectors.telegramAccount;
+      }
+    });
+  }
+  const config = setupService?.getConfig() ?? {};
+  res.status(200).json({
+    ok: true,
+    ...statusFromState(runtime, config)
+  });
+}
+var telegramAccountRoutes = [
+  {
+    type: "GET",
+    path: "/api/telegram-account/status",
+    handler: handleStatus,
+    rawPath: true
+  },
+  {
+    type: "POST",
+    path: "/api/telegram-account/auth/start",
+    handler: handleAuthStart,
+    rawPath: true
+  },
+  {
+    type: "POST",
+    path: "/api/telegram-account/auth/submit",
+    handler: handleAuthSubmit,
+    rawPath: true
+  },
+  {
+    type: "POST",
+    path: "/api/telegram-account/disconnect",
+    handler: handleDisconnect,
+    rawPath: true
+  }
+];
+
+// src/constants.ts
+var MESSAGE_CONSTANTS = {
+  MAX_MESSAGES: 50,
+  RECENT_MESSAGE_COUNT: 5,
+  CHAT_HISTORY_COUNT: 10,
+  DEFAULT_SIMILARITY_THRESHOLD: 0.6,
+  DEFAULT_SIMILARITY_THRESHOLD_FOLLOW_UPS: 0.4,
+  INTEREST_DECAY_TIME: 5 * 60 * 1e3,
+  // 5 minutes
+  PARTIAL_INTEREST_DECAY: 3 * 60 * 1e3
+  // 3 minutes
+};
+var TELEGRAM_SERVICE_NAME = "telegram";
+
+// src/messageManager.ts
+import {
+  ChannelType,
+  createUniqueUuid,
+  EventType,
+  lifeOpsPassiveConnectorsEnabled,
+  logger as logger2,
+  ModelType,
+  ServiceType
+} from "@elizaos/core";
+import fs from "fs";
+import { Markup as Markup2 } from "telegraf";
+
+// src/utils.ts
+import { logger } from "@elizaos/core";
+import { Markup } from "telegraf";
+var TELEGRAM_RESERVED_REGEX = /([_*[\]()~`>#+\-=|{}.!\\])/g;
+function escapePlainText(text) {
+  if (!text) {
+    return "";
+  }
+  return text.replace(TELEGRAM_RESERVED_REGEX, "\\$1");
+}
+function escapePlainTextPreservingBlockquote(text) {
+  if (!text) {
+    return "";
+  }
+  return text.split("\n").map((line) => {
+    const match = line.match(/^(>+\s?)(.*)$/);
+    if (match) {
+      return match[1] + escapePlainText(match[2]);
+    }
+    return escapePlainText(line);
+  }).join("\n");
+}
+function escapeCode(text) {
+  if (!text) {
+    return "";
+  }
+  return text.replace(/([`\\])/g, "\\$1");
+}
+function escapeUrl(url) {
+  if (!url) {
+    return "";
+  }
+  return url.replace(/([)\\])/g, "\\$1");
+}
+function convertMarkdownToTelegram(markdown) {
+  const replacements = [];
+  function storeReplacement(formatted) {
+    const placeholder = `\0${replacements.length}\0`;
+    replacements.push(formatted);
+    return placeholder;
+  }
+  let converted = markdown;
+  converted = converted.replace(
+    /```(\w+)?\n([\s\S]*?)```/g,
+    (_match, lang, code) => {
+      const escapedCode = escapeCode(code);
+      const formatted = `\`\`\`${lang || ""}
+${escapedCode}\`\`\``;
+      return storeReplacement(formatted);
+    }
+  );
+  converted = converted.replace(/`([^`]+)`/g, (_match, code) => {
+    const escapedCode = escapeCode(code);
+    const formatted = `\`${escapedCode}\``;
+    return storeReplacement(formatted);
+  });
+  converted = converted.replace(
+    /$begin:math:display$([^$end:math:display$]+)]$begin:math:text$([^)]+)$end:math:text$/g,
+    (_match, text, url) => {
+      const formattedText = escapePlainText(text);
+      const escapedURL = escapeUrl(url);
+      const formatted = `[${formattedText}](${escapedURL})`;
+      return storeReplacement(formatted);
+    }
+  );
+  converted = converted.replace(/\*\*([^*]+)\*\*/g, (_match, content) => {
+    const formattedContent = escapePlainText(content);
+    const formatted = `*${formattedContent}*`;
+    return storeReplacement(formatted);
+  });
+  converted = converted.replace(/~~([^~]+)~~/g, (_match, content) => {
+    const formattedContent = escapePlainText(content);
+    const formatted = `~${formattedContent}~`;
+    return storeReplacement(formatted);
+  });
+  converted = converted.replace(
+    /(?<!\*)\*([^*\n]+)\*(?!\*)/g,
+    (_match, content) => {
+      const formattedContent = escapePlainText(content);
+      const formatted = `_${formattedContent}_`;
+      return storeReplacement(formatted);
+    }
+  );
+  converted = converted.replace(/_([^_\n]+)_/g, (_match, content) => {
+    const formattedContent = escapePlainText(content);
+    const formatted = `_${formattedContent}_`;
+    return storeReplacement(formatted);
+  });
+  converted = converted.replace(
+    /^(#{1,6})\s*(.*)$/gm,
+    (_match, _hashes, headerContent) => {
+      const formatted = `*${escapePlainText(headerContent.trim())}*`;
+      return storeReplacement(formatted);
+    }
+  );
+  const NULL_CHAR = String.fromCharCode(0);
+  const PLACEHOLDER_PATTERN = new RegExp(`(${NULL_CHAR}\\d+${NULL_CHAR})`, "g");
+  const PLACEHOLDER_TEST = new RegExp(`^${NULL_CHAR}\\d+${NULL_CHAR}$`);
+  const PLACEHOLDER_REPLACE = new RegExp(`${NULL_CHAR}(\\d+)${NULL_CHAR}`, "g");
+  const finalEscaped = converted.split(PLACEHOLDER_PATTERN).map((segment) => {
+    if (PLACEHOLDER_TEST.test(segment)) {
+      return segment;
+    } else {
+      return escapePlainTextPreservingBlockquote(segment);
+    }
+  }).join("");
+  const finalResult = finalEscaped.replace(PLACEHOLDER_REPLACE, (_, index) => {
+    return replacements[Number.parseInt(index, 10)];
+  });
+  return finalResult;
+}
+function convertToTelegramButtons(buttons) {
+  if (!buttons) {
+    return [];
+  }
+  const telegramButtons = [];
+  for (const button of buttons) {
+    if (!button?.text || !button.url) {
+      logger.warn(
+        { src: "plugin:telegram", button },
+        "Invalid button configuration, skipping"
+      );
+      continue;
+    }
+    let telegramButton;
+    switch (button.kind) {
+      case "login":
+        telegramButton = Markup.button.login(button.text, button.url);
+        break;
+      case "url":
+        telegramButton = Markup.button.url(button.text, button.url);
+        break;
+      default:
+        logger.warn(
+          { src: "plugin:telegram", buttonKind: button.kind },
+          "Unknown button kind, treating as URL button"
+        );
+        telegramButton = Markup.button.url(button.text, button.url);
+        break;
+    }
+    telegramButtons.push(telegramButton);
+  }
+  return telegramButtons;
+}
+function cleanText(text) {
+  if (!text) {
+    return "";
+  }
+  return text.split("\0").join("");
+}
+
+// src/messageManager.ts
+var MAX_MESSAGE_LENGTH = 4096;
+var getChannelType = (chat) => {
+  const chatType = chat.type;
+  switch (chatType) {
+    case "private":
+      return ChannelType.DM;
+    case "group":
+    case "supergroup":
+    case "channel":
+      return ChannelType.GROUP;
+    default:
+      throw new Error(`Unrecognized Telegram chat type: ${String(chatType)}`);
+  }
+};
+var MessageManager = class {
+  bot;
+  runtime;
+  /**
+   * Constructor for creating a new instance of a BotAgent.
+   *
+   * @param {Telegraf<Context>} bot - The Telegraf instance used for interacting with the bot platform.
+   * @param {IAgentRuntime} runtime - The runtime environment for the agent.
+   */
+  constructor(bot, runtime) {
+    this.bot = bot;
+    this.runtime = runtime;
+  }
+  /**
+   * Process an image from a Telegram message to extract the image URL and description.
+   *
+   * @param {Message} message - The Telegram message object containing the image.
+   * @returns {Promise<{ description: string } | null>} The description of the processed image or null if no image found.
+   */
+  async processImage(message) {
+    try {
+      let imageUrl = null;
+      logger2.debug(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          messageId: message.message_id
+        },
+        "Processing image from message"
+      );
+      if ("photo" in message && message.photo?.length > 0) {
+        const photo = message.photo[message.photo.length - 1];
+        const fileLink = await this.bot.telegram.getFileLink(photo.file_id);
+        imageUrl = fileLink.toString();
+      } else if ("document" in message && message.document?.mime_type?.startsWith("image/") && !message.document?.mime_type?.startsWith("application/pdf")) {
+        const fileLink = await this.bot.telegram.getFileLink(
+          message.document.file_id
+        );
+        imageUrl = fileLink.toString();
+      }
+      if (imageUrl) {
+        const { title, description } = await this.runtime.useModel(
+          ModelType.IMAGE_DESCRIPTION,
+          imageUrl
+        );
+        return { description: `[Image: ${title}
+${description}]` };
+      }
+    } catch (error) {
+      logger2.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error processing image"
+      );
+    }
+    return null;
+  }
+  /**
+   * Process a document from a Telegram message to extract the document URL and description.
+   * Handles PDFs and other document types by converting them to text when possible.
+   *
+   * @param {Message} message - The Telegram message object containing the document.
+   * @returns {Promise<{ description: string } | null>} The description of the processed document or null if no document found.
+   */
+  async processDocument(message) {
+    try {
+      if (!("document" in message) || !message.document) {
+        return null;
+      }
+      const document = message.document;
+      const fileLink = await this.bot.telegram.getFileLink(document.file_id);
+      const documentUrl = fileLink.toString();
+      logger2.debug(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          fileName: document.file_name,
+          mimeType: document.mime_type,
+          fileSize: document.file_size
+        },
+        "Processing document"
+      );
+      const documentProcessor = this.getDocumentProcessor(document.mime_type);
+      if (documentProcessor) {
+        return await documentProcessor(document, documentUrl);
+      }
+      return {
+        title: `Document: ${document.file_name || "Unknown Document"}`,
+        fullText: "",
+        formattedDescription: `[Document: ${document.file_name || "Unknown Document"}
+Type: ${document.mime_type || "unknown"}
+Size: ${document.file_size || 0} bytes]`,
+        fileName: document.file_name || "Unknown Document",
+        mimeType: document.mime_type,
+        fileSize: document.file_size
+      };
+    } catch (error) {
+      logger2.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error processing document"
+      );
+      return null;
+    }
+  }
+  /**
+   * Get the appropriate document processor based on MIME type.
+   */
+  getDocumentProcessor(mimeType) {
+    if (!mimeType) {
+      return null;
+    }
+    const processors = {
+      "application/pdf": this.processPdfDocument.bind(this),
+      "text/": this.processTextDocument.bind(this),
+      // covers text/plain, text/csv, text/markdown, etc.
+      "application/json": this.processTextDocument.bind(this)
+    };
+    for (const [pattern, processor] of Object.entries(processors)) {
+      if (mimeType.startsWith(pattern)) {
+        return processor;
+      }
+    }
+    return null;
+  }
+  /**
+   * Process PDF documents by converting them to text.
+   */
+  async processPdfDocument(document, documentUrl) {
+    try {
+      const pdfService = this.runtime.getService(
+        ServiceType.PDF
+      );
+      if (!pdfService) {
+        logger2.warn(
+          { src: "plugin:telegram", agentId: this.runtime.agentId },
+          "PDF service not available, using fallback"
+        );
+        return {
+          title: `PDF Document: ${document.file_name || "Unknown Document"}`,
+          fullText: "",
+          formattedDescription: `[PDF Document: ${document.file_name || "Unknown Document"}
+Size: ${document.file_size || 0} bytes
+Unable to extract text content]`,
+          fileName: document.file_name || "Unknown Document",
+          mimeType: document.mime_type,
+          fileSize: document.file_size
+        };
+      }
+      const response = await fetch(documentUrl);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch PDF: ${response.status}`);
+      }
+      const pdfBuffer = await response.arrayBuffer();
+      const text = await pdfService.convertPdfToText(Buffer.from(pdfBuffer));
+      logger2.debug(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          fileName: document.file_name,
+          charactersExtracted: text.length
+        },
+        "PDF processed successfully"
+      );
+      return {
+        title: document.file_name || "Unknown Document",
+        fullText: text,
+        formattedDescription: `[PDF Document: ${document.file_name || "Unknown Document"}
+Size: ${document.file_size || 0} bytes
+Text extracted successfully: ${text.length} characters]`,
+        fileName: document.file_name || "Unknown Document",
+        mimeType: document.mime_type,
+        fileSize: document.file_size
+      };
+    } catch (error) {
+      logger2.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          fileName: document.file_name,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error processing PDF document"
+      );
+      return {
+        title: `PDF Document: ${document.file_name || "Unknown Document"}`,
+        fullText: "",
+        formattedDescription: `[PDF Document: ${document.file_name || "Unknown Document"}
+Size: ${document.file_size || 0} bytes
+Error: Unable to extract text content]`,
+        fileName: document.file_name || "Unknown Document",
+        mimeType: document.mime_type,
+        fileSize: document.file_size
+      };
+    }
+  }
+  /**
+   * Process text documents by fetching their content.
+   */
+  async processTextDocument(document, documentUrl) {
+    try {
+      const response = await fetch(documentUrl);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch text document: ${response.status}`);
+      }
+      const text = await response.text();
+      logger2.debug(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          fileName: document.file_name,
+          charactersExtracted: text.length
+        },
+        "Text document processed successfully"
+      );
+      return {
+        title: document.file_name || "Unknown Document",
+        fullText: text,
+        formattedDescription: `[Text Document: ${document.file_name || "Unknown Document"}
+Size: ${document.file_size || 0} bytes
+Text extracted successfully: ${text.length} characters]`,
+        fileName: document.file_name || "Unknown Document",
+        mimeType: document.mime_type,
+        fileSize: document.file_size
+      };
+    } catch (error) {
+      logger2.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          fileName: document.file_name,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error processing text document"
+      );
+      return {
+        title: `Text Document: ${document.file_name || "Unknown Document"}`,
+        fullText: "",
+        formattedDescription: `[Text Document: ${document.file_name || "Unknown Document"}
+Size: ${document.file_size || 0} bytes
+Error: Unable to read content]`,
+        fileName: document.file_name || "Unknown Document",
+        mimeType: document.mime_type,
+        fileSize: document.file_size
+      };
+    }
+  }
+  /**
+   * Processes the message content, documents, and images to generate
+   * processed content and media attachments.
+   *
+   * @param {Message} message The message to process
+   * @returns {Promise<{ processedContent: string; attachments: Media[] }>} Processed content and media attachments
+   */
+  async processMessage(message) {
+    let processedContent = "";
+    const attachments = [];
+    if ("text" in message && message.text) {
+      processedContent = message.text;
+    } else if ("caption" in message && message.caption) {
+      processedContent = message.caption;
+    }
+    if ("document" in message && message.document) {
+      const document = message.document;
+      const documentInfo = await this.processDocument(message);
+      if (documentInfo) {
+        try {
+          const fileLink = await this.bot.telegram.getFileLink(
+            document.file_id
+          );
+          const title = documentInfo.title;
+          const fullText = documentInfo.fullText;
+          if (fullText) {
+            const documentContent = `
+
+--- DOCUMENT CONTENT ---
+Title: ${title}
+
+Full Content:
+${fullText}
+--- END DOCUMENT ---
+
+`;
+            processedContent += documentContent;
+          }
+          attachments.push({
+            id: document.file_id,
+            url: fileLink.toString(),
+            title,
+            source: document.mime_type?.startsWith("application/pdf") ? "PDF" : "Document",
+            description: documentInfo.formattedDescription,
+            text: fullText
+          });
+          logger2.debug(
+            {
+              src: "plugin:telegram",
+              agentId: this.runtime.agentId,
+              fileName: documentInfo.fileName
+            },
+            "Document processed successfully"
+          );
+        } catch (error) {
+          logger2.error(
+            {
+              src: "plugin:telegram",
+              agentId: this.runtime.agentId,
+              fileName: documentInfo.fileName,
+              error: error instanceof Error ? error.message : String(error)
+            },
+            "Error processing document"
+          );
+          attachments.push({
+            id: document.file_id,
+            url: "",
+            title: `Document: ${documentInfo.fileName}`,
+            source: "Document",
+            description: `Document processing failed: ${documentInfo.fileName}`,
+            text: `Document: ${documentInfo.fileName}
+Size: ${documentInfo.fileSize || 0} bytes
+Type: ${documentInfo.mimeType || "unknown"}`
+          });
+        }
+      } else {
+        attachments.push({
+          id: document.file_id,
+          url: "",
+          title: `Document: ${document.file_name || "Unknown Document"}`,
+          source: "Document",
+          description: `Document: ${document.file_name || "Unknown Document"}`,
+          text: `Document: ${document.file_name || "Unknown Document"}
+Size: ${document.file_size || 0} bytes
+Type: ${document.mime_type || "unknown"}`
+        });
+      }
+    }
+    if ("photo" in message && message.photo?.length > 0) {
+      const imageInfo = await this.processImage(message);
+      if (imageInfo) {
+        const photo = message.photo[message.photo.length - 1];
+        const fileLink = await this.bot.telegram.getFileLink(photo.file_id);
+        attachments.push({
+          id: photo.file_id,
+          url: fileLink.toString(),
+          title: "Image Attachment",
+          source: "Image",
+          description: imageInfo.description,
+          text: imageInfo.description
+        });
+      }
+    }
+    logger2.debug(
+      {
+        src: "plugin:telegram",
+        agentId: this.runtime.agentId,
+        hasContent: !!processedContent,
+        attachmentsCount: attachments.length
+      },
+      "Message processed"
+    );
+    return { processedContent, attachments };
+  }
+  /**
+   * Sends a message in chunks, handling attachments and splitting the message if necessary
+   *
+   * @param {Context} ctx - The context object representing the current state of the bot
+   * @param {TelegramContent} content - The content of the message to be sent
+   * @param {number} [replyToMessageId] - The ID of the message to reply to, if any
+   * @returns {Promise<Message.TextMessage[]>} - An array of TextMessage objects representing the messages sent
+   */
+  async sendMessageInChunks(ctx, content, replyToMessageId) {
+    if (content.attachments && content.attachments.length > 0) {
+      content.attachments.map(async (attachment) => {
+        const typeMap = {
+          "image/gif": "animation" /* ANIMATION */,
+          image: "photo" /* PHOTO */,
+          doc: "document" /* DOCUMENT */,
+          video: "video" /* VIDEO */,
+          audio: "audio" /* AUDIO */
+        };
+        let mediaType;
+        for (const prefix in typeMap) {
+          if (attachment.contentType?.startsWith(prefix)) {
+            mediaType = typeMap[prefix];
+            break;
+          }
+        }
+        if (!mediaType) {
+          throw new Error(
+            `Unsupported Telegram attachment content type: ${attachment.contentType}`
+          );
+        }
+        await this.sendMedia(
+          ctx,
+          attachment.url,
+          mediaType,
+          attachment.description
+        );
+      });
+      return [];
+    } else {
+      const chunks = this.splitMessage(content.text ?? "");
+      const sentMessages = [];
+      const telegramButtons = convertToTelegramButtons(content.buttons ?? []);
+      if (!ctx.chat) {
+        logger2.error(
+          { src: "plugin:telegram", agentId: this.runtime.agentId },
+          "sendMessageInChunks: ctx.chat is undefined"
+        );
+        return [];
+      }
+      await ctx.telegram.sendChatAction(ctx.chat.id, "typing");
+      for (let i = 0; i < chunks.length; i++) {
+        const chunk = convertMarkdownToTelegram(chunks[i]);
+        if (!ctx.chat) {
+          logger2.error(
+            { src: "plugin:telegram", agentId: this.runtime.agentId },
+            "sendMessageInChunks loop: ctx.chat is undefined"
+          );
+          continue;
+        }
+        const sentMessage = await ctx.telegram.sendMessage(
+          ctx.chat.id,
+          chunk,
+          {
+            reply_parameters: i === 0 && replyToMessageId ? { message_id: replyToMessageId } : void 0,
+            parse_mode: "MarkdownV2",
+            ...Markup2.inlineKeyboard(telegramButtons)
+          }
+        );
+        sentMessages.push(sentMessage);
+      }
+      return sentMessages;
+    }
+  }
+  /**
+   * Sends media to a chat using the Telegram API.
+   *
+   * @param {Context} ctx - The context object containing information about the current chat.
+   * @param {string} mediaPath - The path to the media to be sent, either a URL or a local file path.
+   * @param {MediaType} type - The type of media being sent (PHOTO, VIDEO, DOCUMENT, AUDIO, or ANIMATION).
+   * @param {string} [caption] - Optional caption for the media being sent.
+   *
+   * @returns {Promise<void>} A Promise that resolves when the media is successfully sent.
+   */
+  async sendMedia(ctx, mediaPath, type, caption) {
+    try {
+      const isUrl = /^(http|https):\/\//.test(mediaPath);
+      const sendFunctionMap = {
+        ["photo" /* PHOTO */]: ctx.telegram.sendPhoto.bind(ctx.telegram),
+        ["video" /* VIDEO */]: ctx.telegram.sendVideo.bind(ctx.telegram),
+        ["document" /* DOCUMENT */]: ctx.telegram.sendDocument.bind(ctx.telegram),
+        ["audio" /* AUDIO */]: ctx.telegram.sendAudio.bind(ctx.telegram),
+        ["animation" /* ANIMATION */]: ctx.telegram.sendAnimation.bind(ctx.telegram)
+      };
+      const sendFunction = sendFunctionMap[type];
+      if (!sendFunction) {
+        throw new Error(`Unsupported media type: ${type}`);
+      }
+      if (!ctx.chat) {
+        throw new Error("sendMedia: ctx.chat is undefined");
+      }
+      if (isUrl) {
+        await sendFunction(ctx.chat.id, mediaPath, { caption });
+      } else {
+        if (!fs.existsSync(mediaPath)) {
+          throw new Error(`File not found at path: ${mediaPath}`);
+        }
+        const fileStream = fs.createReadStream(mediaPath);
+        try {
+          if (!ctx.chat) {
+            throw new Error("sendMedia (file): ctx.chat is undefined");
+          }
+          await sendFunction(ctx.chat.id, { source: fileStream }, { caption });
+        } finally {
+          fileStream.destroy();
+        }
+      }
+      logger2.debug(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          mediaType: type,
+          mediaPath
+        },
+        "Media sent successfully"
+      );
+    } catch (error) {
+      logger2.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          mediaType: type,
+          mediaPath,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Failed to send media"
+      );
+      throw error;
+    }
+  }
+  /**
+   * Splits a given text into an array of strings based on the maximum message length.
+   *
+   * @param {string} text - The text to split into chunks.
+   * @returns {string[]} An array of strings with each element representing a chunk of the original text.
+   */
+  splitMessage(text) {
+    const chunks = [];
+    if (!text) {
+      return chunks;
+    }
+    let currentChunk = "";
+    const lines = text.split("\n");
+    for (const line of lines) {
+      if (currentChunk.length + line.length + 1 <= MAX_MESSAGE_LENGTH) {
+        currentChunk += (currentChunk ? "\n" : "") + line;
+      } else {
+        if (currentChunk) {
+          chunks.push(currentChunk);
+        }
+        currentChunk = line;
+      }
+    }
+    if (currentChunk) {
+      chunks.push(currentChunk);
+    }
+    return chunks;
+  }
+  /**
+   * Handle incoming messages from Telegram and process them accordingly.
+   * @param {Context} ctx - The context object containing information about the message.
+   * @returns {Promise<void>}
+   */
+  async handleMessage(ctx) {
+    if (!ctx.message || !ctx.from) {
+      return;
+    }
+    const message = ctx.message;
+    try {
+      const telegramUserId = ctx.from.id.toString();
+      const entityId = createUniqueUuid(this.runtime, telegramUserId);
+      const threadId = "is_topic_message" in message && message.is_topic_message ? message.message_thread_id?.toString() : void 0;
+      if (!ctx.chat) {
+        logger2.error(
+          { src: "plugin:telegram", agentId: this.runtime.agentId },
+          "handleMessage: ctx.chat is undefined"
+        );
+        return;
+      }
+      const telegramRoomid = threadId ? `${ctx.chat.id}-${threadId}` : ctx.chat.id.toString();
+      const telegramChatId = ctx.chat.id.toString();
+      const roomId = createUniqueUuid(this.runtime, telegramRoomid);
+      const worldId = createUniqueUuid(this.runtime, telegramChatId);
+      const telegramMessageId = message.message_id.toString();
+      const messageId = createUniqueUuid(this.runtime, telegramMessageId);
+      const { processedContent, attachments } = await this.processMessage(message);
+      const cleanedContent = cleanText(processedContent);
+      const cleanedAttachments = attachments.map((att) => ({
+        ...att,
+        text: cleanText(att.text),
+        description: cleanText(att.description),
+        title: cleanText(att.title)
+      }));
+      if (!cleanedContent && cleanedAttachments.length === 0) {
+        return;
+      }
+      const chat = message.chat;
+      const channelType = getChannelType(chat);
+      await this.runtime.ensureConnection({
+        entityId,
+        roomId,
+        roomName: "title" in chat && typeof chat.title === "string" && chat.title || "first_name" in chat && typeof chat.first_name === "string" && chat.first_name || "username" in chat && typeof chat.username === "string" && chat.username || telegramRoomid,
+        userName: ctx.from.username,
+        name: ctx.from.first_name,
+        userId: telegramUserId,
+        source: "telegram",
+        channelId: telegramRoomid,
+        type: channelType,
+        worldId,
+        worldName: telegramRoomid
+      });
+      const memory = {
+        id: messageId,
+        entityId,
+        agentId: this.runtime.agentId,
+        roomId,
+        content: {
+          text: cleanedContent || " ",
+          attachments: cleanedAttachments,
+          source: "telegram",
+          channelType,
+          inReplyTo: "reply_to_message" in message && message.reply_to_message ? createUniqueUuid(
+            this.runtime,
+            message.reply_to_message.message_id.toString()
+          ) : void 0
+        },
+        metadata: {
+          type: "message",
+          source: "telegram",
+          provider: "telegram",
+          timestamp: message.date * 1e3,
+          entityName: ctx.from.first_name,
+          entityUserName: ctx.from.username,
+          fromBot: ctx.from.is_bot,
+          fromId: telegramUserId,
+          sourceId: entityId,
+          chatType: chat.type,
+          messageIdFull: telegramMessageId,
+          sender: {
+            id: telegramUserId,
+            name: ctx.from.first_name,
+            username: ctx.from.username
+          },
+          telegram: {
+            chatId: telegramChatId,
+            messageId: telegramMessageId,
+            threadId
+          },
+          telegramUserId,
+          telegramChatId
+        },
+        createdAt: message.date * 1e3
+      };
+      const callback = async (content, _actionName) => {
+        try {
+          if (!content.text) {
+            return [];
+          }
+          let sentMessages = false;
+          if (content?.channelType === "DM") {
+            sentMessages = [];
+            if (ctx.from) {
+              const res = await this.bot.telegram.sendMessage(
+                ctx.from.id,
+                content.text
+              );
+              sentMessages.push(res);
+            }
+          } else {
+            sentMessages = await this.sendMessageInChunks(
+              ctx,
+              content,
+              message.message_id
+            );
+          }
+          if (!Array.isArray(sentMessages)) {
+            return [];
+          }
+          const memories = [];
+          for (let i = 0; i < sentMessages.length; i++) {
+            const sentMessage = sentMessages[i];
+            const responseMemory = {
+              id: createUniqueUuid(
+                this.runtime,
+                sentMessage.message_id.toString()
+              ),
+              entityId: this.runtime.agentId,
+              agentId: this.runtime.agentId,
+              roomId,
+              content: {
+                ...content,
+                source: "telegram",
+                text: sentMessage.text,
+                inReplyTo: messageId,
+                channelType
+              },
+              metadata: {
+                type: "message",
+                source: "telegram",
+                provider: "telegram",
+                timestamp: sentMessage.date * 1e3,
+                fromBot: true,
+                fromId: this.runtime.agentId,
+                sourceId: this.runtime.agentId,
+                chatType: chat.type,
+                messageIdFull: sentMessage.message_id.toString(),
+                telegram: {
+                  chatId: sentMessage.chat.id,
+                  messageId: sentMessage.message_id.toString(),
+                  threadId
+                }
+              },
+              createdAt: sentMessage.date * 1e3
+            };
+            await this.runtime.createMemory(responseMemory, "messages");
+            memories.push(responseMemory);
+          }
+          return memories;
+        } catch (error) {
+          logger2.error(
+            {
+              src: "plugin:telegram",
+              agentId: this.runtime.agentId,
+              error: error instanceof Error ? error.message : String(error)
+            },
+            "Error in message callback"
+          );
+          return [];
+        }
+      };
+      const telegramAutoReplyRaw = this.runtime.getSetting(
+        "TELEGRAM_AUTO_REPLY"
+      );
+      const telegramAutoReply = !lifeOpsPassiveConnectorsEnabled(this.runtime) && (telegramAutoReplyRaw === true || telegramAutoReplyRaw === "true");
+      if (!telegramAutoReply) {
+        try {
+          await this.runtime.createMemory(memory, "messages");
+        } catch (persistError) {
+          logger2.warn(
+            {
+              src: "plugin:telegram",
+              agentId: this.runtime.agentId,
+              error: persistError instanceof Error ? persistError.message : String(persistError)
+            },
+            "Failed to persist inbound memory while auto-reply is disabled"
+          );
+        }
+        logger2.debug(
+          { src: "plugin:telegram", agentId: this.runtime.agentId },
+          "Auto-reply disabled (TELEGRAM_AUTO_REPLY=false); message ingested without response"
+        );
+      } else if (this.runtime.messageService) {
+        await this.runtime.messageService.handleMessage(
+          this.runtime,
+          memory,
+          callback
+        );
+      } else {
+        logger2.error(
+          { src: "plugin:telegram", agentId: this.runtime.agentId },
+          "Message service is not available"
+        );
+        throw new Error(
+          "Message service is not initialized. Ensure the message service is properly configured."
+        );
+      }
+    } catch (error) {
+      logger2.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          chatId: ctx.chat?.id,
+          messageId: ctx.message?.message_id,
+          from: ctx.from?.username || ctx.from?.id,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error handling Telegram message"
+      );
+      throw error;
+    }
+  }
+  /**
+   * Handles the reaction event triggered by a user reacting to a message.
+   * @param {NarrowedContext<Context<Update>, Update.MessageReactionUpdate>} ctx The context of the message reaction update
+   * @returns {Promise<void>} A Promise that resolves when the reaction handling is complete
+   */
+  async handleReaction(ctx) {
+    if (!ctx.update.message_reaction || !ctx.from) {
+      return;
+    }
+    const reaction = ctx.update.message_reaction;
+    const reactedToMessageId = reaction.message_id;
+    const originalMessagePlaceholder = {
+      message_id: reactedToMessageId,
+      chat: reaction.chat,
+      from: ctx.from,
+      date: Math.floor(Date.now() / 1e3)
+    };
+    const reactionType = reaction.new_reaction[0].type;
+    const reactionEmoji = reaction.new_reaction[0].type;
+    try {
+      const entityId = createUniqueUuid(
+        this.runtime,
+        ctx.from.id.toString()
+      );
+      const roomId = createUniqueUuid(this.runtime, ctx.chat.id.toString());
+      const reactionId = createUniqueUuid(
+        this.runtime,
+        `${reaction.message_id}-${ctx.from.id}-${Date.now()}`
+      );
+      const memory = {
+        id: reactionId,
+        entityId,
+        agentId: this.runtime.agentId,
+        roomId,
+        content: {
+          channelType: getChannelType(reaction.chat),
+          text: `Reacted with: ${reactionType === "emoji" ? reactionEmoji : reactionType}`,
+          source: "telegram",
+          inReplyTo: createUniqueUuid(
+            this.runtime,
+            reaction.message_id.toString()
+          )
+        },
+        createdAt: Date.now()
+      };
+      const callback = async (content) => {
+        try {
+          const replyText = content.text ?? "";
+          const sentMessage = await ctx.reply(replyText);
+          const responseMemory = {
+            id: createUniqueUuid(
+              this.runtime,
+              sentMessage.message_id.toString()
+            ),
+            entityId: this.runtime.agentId,
+            agentId: this.runtime.agentId,
+            roomId,
+            content: {
+              ...content,
+              inReplyTo: reactionId
+            },
+            createdAt: sentMessage.date * 1e3
+          };
+          return [responseMemory];
+        } catch (error) {
+          logger2.error(
+            {
+              src: "plugin:telegram",
+              agentId: this.runtime.agentId,
+              error: error instanceof Error ? error.message : String(error)
+            },
+            "Error in reaction callback"
+          );
+          return [];
+        }
+      };
+      this.runtime.emitEvent(EventType.REACTION_RECEIVED, {
+        runtime: this.runtime,
+        message: memory,
+        callback,
+        source: "telegram",
+        ctx,
+        originalMessage: originalMessagePlaceholder,
+        // Cast needed due to placeholder
+        reactionString: reactionType === "emoji" ? reactionEmoji : reactionType,
+        originalReaction: reaction.new_reaction[0]
+      });
+      this.runtime.emitEvent("TELEGRAM_REACTION_RECEIVED" /* REACTION_RECEIVED */, {
+        runtime: this.runtime,
+        message: memory,
+        callback,
+        source: "telegram",
+        ctx,
+        originalMessage: originalMessagePlaceholder,
+        // Cast needed due to placeholder
+        reactionString: reactionType === "emoji" ? reactionEmoji : reactionType,
+        originalReaction: reaction.new_reaction[0]
+      });
+    } catch (error) {
+      logger2.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error handling reaction"
+      );
+    }
+  }
+  /**
+   * Sends a message to a Telegram chat and emits appropriate events
+   * @param {number | string} chatId - The Telegram chat ID to send the message to
+   * @param {Content} content - The content to send
+   * @param {number} [replyToMessageId] - Optional message ID to reply to
+   * @returns {Promise<Message.TextMessage[]>} The sent messages
+   */
+  async sendMessage(chatId, content, replyToMessageId) {
+    try {
+      const ctx = {
+        chat: { id: chatId },
+        telegram: this.bot.telegram
+      };
+      const sentMessages = await this.sendMessageInChunks(
+        ctx,
+        content,
+        replyToMessageId
+      );
+      if (!sentMessages?.length) {
+        return [];
+      }
+      const roomId = createUniqueUuid(this.runtime, chatId.toString());
+      const memories = [];
+      for (const sentMessage of sentMessages) {
+        const memory = {
+          id: createUniqueUuid(this.runtime, sentMessage.message_id.toString()),
+          entityId: this.runtime.agentId,
+          agentId: this.runtime.agentId,
+          roomId,
+          content: {
+            ...content,
+            text: sentMessage.text,
+            source: "telegram",
+            channelType: getChannelType({
+              id: typeof chatId === "string" ? Number.parseInt(chatId, 10) : chatId,
+              type: "private"
+              // Default to private, will be overridden if in context
+            })
+          },
+          createdAt: sentMessage.date * 1e3
+        };
+        await this.runtime.createMemory(memory, "messages");
+        memories.push(memory);
+      }
+      if (memories.length > 0) {
+        const firstMemory = memories[0];
+        this.runtime.emitEvent(EventType.MESSAGE_SENT, {
+          runtime: this.runtime,
+          message: firstMemory,
+          source: "telegram"
+        });
+        const telegramMessageSentPayload = {
+          runtime: this.runtime,
+          source: "telegram",
+          originalMessages: sentMessages,
+          chatId,
+          message: firstMemory
+        };
+        this.runtime.emitEvent(
+          "TELEGRAM_MESSAGE_SENT" /* MESSAGE_SENT */,
+          telegramMessageSentPayload
+        );
+      }
+      return sentMessages;
+    } catch (error) {
+      logger2.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          chatId,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error sending message to Telegram"
+      );
+      return [];
+    }
+  }
+};
+
+// src/owner-pairing-service.ts
+import { logger as logger3, Service } from "@elizaos/core";
+var TELEGRAM_OWNER_PAIRING_SERVICE_TYPE = "OWNER_PAIRING_TELEGRAM";
+var RATE_LIMIT_MAX_ATTEMPTS = 5;
+var RATE_LIMIT_WINDOW_MS = 6e4;
+async function auditEmit(runtime, action, outcome, metadata) {
+  try {
+    await runtime.emitEvent(
+      ["AUTH_AUDIT"],
+      {
+        runtime,
+        action,
+        outcome,
+        metadata,
+        source: "telegram"
+      }
+    );
+  } catch {
+  }
+}
+var pairAttempts = /* @__PURE__ */ new Map();
+function isRateLimited(userId) {
+  const now = Date.now();
+  const windowStart = now - RATE_LIMIT_WINDOW_MS;
+  const attempts = (pairAttempts.get(userId) ?? []).filter(
+    (ts) => ts > windowStart
+  );
+  pairAttempts.set(userId, attempts);
+  if (attempts.length >= RATE_LIMIT_MAX_ATTEMPTS) {
+    return true;
+  }
+  attempts.push(now);
+  pairAttempts.set(userId, attempts);
+  return false;
+}
+function isValidPairCode(code) {
+  return /^\d{6}$/.test(code.trim());
+}
+function resolveVerifyService(runtime) {
+  try {
+    const svc = runtime.getService("OWNER_BIND_VERIFY");
+    if (svc && typeof svc === "object" && typeof svc.verifyOwnerBindFromConnector === "function") {
+      return svc;
+    }
+  } catch {
+  }
+  return null;
+}
+function resolveDisplayHandle(from) {
+  if (from.username) {
+    return `@${from.username}`;
+  }
+  if (from.first_name) {
+    return from.first_name;
+  }
+  return String(from.id);
+}
+async function handleElizaPairCommand(ctx, runtime) {
+  const from = ctx.from;
+  if (!from) {
+    return;
+  }
+  const userId = String(from.id);
+  const displayHandle = resolveDisplayHandle(from);
+  if (isRateLimited(userId)) {
+    logger3.warn(
+      { src: "plugin:telegram:owner-pairing", userId },
+      "Rate limit hit for /eliza_pair"
+    );
+    await auditEmit(
+      runtime,
+      "auth.owner.pair.telegram.rate_limited",
+      "failure",
+      { externalId: userId }
+    );
+    await ctx.reply(
+      "Too many pairing attempts. Please wait a moment before trying again."
+    );
+    return;
+  }
+  const message = ctx.message;
+  const rawText = message && "text" in message ? message.text : void 0;
+  let code = null;
+  if (typeof rawText === "string") {
+    const parts = rawText.trim().split(/\s+/);
+    if (parts.length >= 2) {
+      code = parts[1] ?? null;
+    }
+  }
+  if (!code?.trim()) {
+    await ctx.reply(
+      "Usage: /eliza\\_pair <code> \u2014 enter the 6-digit code shown in the Eliza dashboard."
+    );
+    return;
+  }
+  code = code.trim();
+  if (!isValidPairCode(code)) {
+    await ctx.reply(
+      "The pairing code must be exactly 6 digits. Check the Eliza dashboard and try again."
+    );
+    return;
+  }
+  const verifySvc = resolveVerifyService(runtime);
+  if (!verifySvc) {
+    logger3.error(
+      { src: "plugin:telegram:owner-pairing", userId },
+      "OWNER_BIND_VERIFY service not available \u2014 cannot complete pairing"
+    );
+    await auditEmit(
+      runtime,
+      "auth.owner.pair.telegram.service_unavailable",
+      "failure",
+      { externalId: userId }
+    );
+    await ctx.reply(
+      "Eliza could not reach the pairing service right now. Please try again in a moment."
+    );
+    return;
+  }
+  let result;
+  try {
+    result = await verifySvc.verifyOwnerBindFromConnector({
+      connector: "telegram",
+      externalId: userId,
+      displayHandle,
+      code
+    });
+  } catch (err) {
+    logger3.error(
+      {
+        src: "plugin:telegram:owner-pairing",
+        userId,
+        error: err instanceof Error ? err.message : String(err)
+      },
+      "verifyOwnerBindFromConnector threw unexpectedly"
+    );
+    await auditEmit(
+      runtime,
+      "auth.owner.pair.telegram.verify_error",
+      "failure",
+      { externalId: userId }
+    );
+    await ctx.reply(
+      "Something went wrong while verifying the pairing code. Please try again."
+    );
+    return;
+  }
+  if (result.success) {
+    logger3.info(
+      { src: "plugin:telegram:owner-pairing", userId, displayHandle },
+      "Owner pairing completed successfully"
+    );
+    await auditEmit(runtime, "auth.owner.pair.telegram.success", "success", {
+      externalId: userId,
+      displayHandle
+    });
+    await ctx.reply("Paired with Eliza. You can now log in via Telegram.");
+  } else {
+    logger3.warn(
+      {
+        src: "plugin:telegram:owner-pairing",
+        userId,
+        backendError: result.error
+      },
+      "Owner pairing rejected by backend"
+    );
+    await auditEmit(runtime, "auth.owner.pair.telegram.failure", "failure", {
+      externalId: userId
+    });
+    await ctx.reply(
+      "Pair code invalid or expired. Check the Eliza dashboard for a fresh code."
+    );
+  }
+}
+var TelegramOwnerPairingServiceImpl = class _TelegramOwnerPairingServiceImpl extends Service {
+  static serviceType = TELEGRAM_OWNER_PAIRING_SERVICE_TYPE;
+  capabilityDescription = "Handles Telegram-side owner pairing (command code verification) and DM login-link delivery for Eliza remote auth";
+  static async start(runtime) {
+    const service = new _TelegramOwnerPairingServiceImpl(runtime);
+    if (resolveVerifyService(runtime)) {
+      service.registerPairCommand(runtime);
+      logger3.info(
+        {
+          src: "plugin:telegram:owner-pairing",
+          agentId: runtime.agentId
+        },
+        "TelegramOwnerPairingService started; /eliza_pair command registered"
+      );
+    } else {
+      logger3.info(
+        {
+          src: "plugin:telegram:owner-pairing",
+          agentId: runtime.agentId
+        },
+        "TelegramOwnerPairingService started without /eliza_pair because OWNER_BIND_VERIFY is not registered"
+      );
+    }
+    return service;
+  }
+  async stop() {
+    pairAttempts.clear();
+  }
+  /**
+   * Registers the /eliza_pair command with the active Telegraf bot instance
+   * by looking up the TelegramService from the runtime service registry.
+   * Called during `start`; it is safe to call this before or after the bot
+   * has finished initialising because Telegraf accepts handler registration
+   * at any point before `launch()`.
+   *
+   * If the TelegramService is unavailable, the command is not registered.
+   */
+  registerPairCommand(runtime) {
+    const telegramSvc = runtime.getService(TELEGRAM_SERVICE_NAME);
+    if (!telegramSvc || typeof telegramSvc !== "object") {
+      logger3.warn(
+        { src: "plugin:telegram:owner-pairing", agentId: runtime.agentId },
+        "TelegramService unavailable during owner-pairing start; /eliza_pair command not registered"
+      );
+      return;
+    }
+    const bot = "bot" in telegramSvc ? telegramSvc.bot : null;
+    if (!bot || typeof bot.command !== "function") {
+      logger3.warn(
+        { src: "plugin:telegram:owner-pairing", agentId: runtime.agentId },
+        "Telegraf bot instance not available \u2014 /eliza_pair will not be registered"
+      );
+      return;
+    }
+    const telegrafBot = bot;
+    telegrafBot.command("eliza_pair", async (ctx) => {
+      await handleElizaPairCommand(ctx, runtime);
+    });
+    logger3.debug(
+      { src: "plugin:telegram:owner-pairing", agentId: runtime.agentId },
+      "/eliza_pair command registered with Telegraf bot"
+    );
+  }
+  async sendOwnerLoginDmLink(params) {
+    const { externalId, link } = params;
+    const telegramSvc = this.runtime.getService(
+      TELEGRAM_SERVICE_NAME
+    );
+    const bot = telegramSvc && typeof telegramSvc === "object" && "bot" in telegramSvc ? telegramSvc.bot : null;
+    if (!bot || typeof bot.telegram !== "object") {
+      throw new Error(
+        "Telegram bot is not available \u2014 cannot send DM login link"
+      );
+    }
+    const telegrafBot = bot;
+    const chatId = Number(externalId);
+    if (!Number.isFinite(chatId) || chatId <= 0) {
+      throw new Error(
+        `Invalid Telegram externalId "${externalId}" \u2014 must be a positive numeric user ID`
+      );
+    }
+    const message = `Click to log in to Eliza: ${link}
+
+_This link expires in 5 minutes. Do not share it._`;
+    try {
+      await telegrafBot.telegram.sendMessage(chatId, message, {
+        parse_mode: "Markdown"
+      });
+      logger3.info(
+        { src: "plugin:telegram:owner-pairing", externalId },
+        "Login DM link sent"
+      );
+    } catch (err) {
+      throw new Error(
+        `Failed to send DM login link to Telegram user ${externalId}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+};
+
+// src/service.ts
+import {
+  ChannelType as ChannelType2,
+  createUniqueUuid as createUniqueUuid2,
+  EventType as EventType2,
+  logger as logger4,
+  Role,
+  Service as Service2
+} from "@elizaos/core";
+import { Telegraf } from "telegraf";
+var CANONICAL_OWNER_SETTING_KEYS = ["ELIZA_ADMIN_ENTITY_ID"];
+function resolveTelegramBotToken(runtime) {
+  const fromRuntime = runtime.getSetting("TELEGRAM_BOT_TOKEN");
+  if (typeof fromRuntime === "string" && fromRuntime.trim()) {
+    return fromRuntime.trim();
+  }
+  const fromEnv = process.env.TELEGRAM_BOT_TOKEN;
+  return typeof fromEnv === "string" && fromEnv.trim() ? fromEnv.trim() : null;
+}
+var ACTIVE_TELEGRAM_POLLERS = /* @__PURE__ */ new Map();
+function getCanonicalOwnerId(runtime) {
+  for (const key of CANONICAL_OWNER_SETTING_KEYS) {
+    const value = runtime.getSetting(key);
+    if (typeof value !== "string") {
+      continue;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length > 0) {
+      return trimmed;
+    }
+  }
+  return null;
+}
+function getTelegramChatDisplayName(chat, fallback) {
+  if (!chat) {
+    return fallback;
+  }
+  if ("title" in chat && typeof chat.title === "string" && chat.title.trim()) {
+    return chat.title;
+  }
+  if ("first_name" in chat && typeof chat.first_name === "string" && chat.first_name.trim()) {
+    return chat.first_name;
+  }
+  if ("username" in chat && typeof chat.username === "string" && chat.username.trim()) {
+    return chat.username;
+  }
+  return fallback;
+}
+var TelegramService = class _TelegramService extends Service2 {
+  static serviceType = TELEGRAM_SERVICE_NAME;
+  capabilityDescription = "The agent is able to send and receive messages on telegram";
+  bot;
+  messageManager;
+  options;
+  knownChats = /* @__PURE__ */ new Map();
+  syncedEntityIds = /* @__PURE__ */ new Set();
+  botToken;
+  /**
+   * Constructor for TelegramService class.
+   * @param {IAgentRuntime} runtime - The runtime object for the agent.
+   */
+  constructor(runtime) {
+    super(runtime);
+    if (!runtime) {
+      this.bot = null;
+      this.messageManager = null;
+      this.botToken = null;
+      return;
+    }
+    logger4.debug(
+      { src: "plugin:telegram", agentId: runtime.agentId },
+      "Constructing TelegramService"
+    );
+    const botToken = resolveTelegramBotToken(runtime);
+    this.botToken = botToken;
+    if (!botToken) {
+      logger4.warn(
+        { src: "plugin:telegram", agentId: runtime.agentId },
+        "Bot token not provided, Telegram functionality unavailable"
+      );
+      this.bot = null;
+      this.messageManager = null;
+      return;
+    }
+    const configuredApiRoot = runtime.getSetting("TELEGRAM_API_ROOT");
+    const apiRoot = typeof configuredApiRoot === "string" && configuredApiRoot.length > 0 ? configuredApiRoot : process.env.TELEGRAM_API_ROOT || "https://api.telegram.org";
+    this.options = {
+      telegram: { apiRoot }
+    };
+    try {
+      this.bot = new Telegraf(botToken, this.options);
+      this.messageManager = new MessageManager(this.bot, this.runtime);
+      logger4.debug(
+        { src: "plugin:telegram", agentId: runtime.agentId },
+        "TelegramService constructor completed"
+      );
+    } catch (error) {
+      logger4.error(
+        {
+          src: "plugin:telegram",
+          agentId: runtime.agentId,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Failed to initialize Telegram bot"
+      );
+      this.bot = null;
+      this.messageManager = null;
+    }
+  }
+  /**
+   * Starts the Telegram service for the given runtime.
+   *
+   * @param {IAgentRuntime} runtime - The agent runtime to start the Telegram service for.
+   * @returns {Promise<TelegramService>} A promise that resolves with the initialized TelegramService.
+   */
+  static async start(runtime) {
+    const service = new _TelegramService(runtime);
+    if (!service.bot) {
+      logger4.warn(
+        { src: "plugin:telegram", agentId: runtime.agentId },
+        "Service started without bot functionality"
+      );
+      return service;
+    }
+    const maxRetries = 5;
+    let retryCount = 0;
+    let lastError = null;
+    while (retryCount < maxRetries) {
+      try {
+        logger4.info(
+          {
+            src: "plugin:telegram",
+            agentId: runtime.agentId,
+            agentName: runtime.character.name
+          },
+          "Starting Telegram bot"
+        );
+        await service.initializeBot();
+        service.setupMiddlewares();
+        service.setupMessageHandlers();
+        const bot = service.bot;
+        if (!bot) {
+          throw new Error("Telegram bot was not initialized");
+        }
+        await bot.telegram.getMe();
+        logger4.success(
+          {
+            src: "plugin:telegram",
+            agentId: runtime.agentId,
+            agentName: runtime.character.name
+          },
+          "Telegram bot started successfully"
+        );
+        return service;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        logger4.error(
+          {
+            src: "plugin:telegram",
+            agentId: runtime.agentId,
+            attempt: retryCount + 1,
+            error: lastError.message
+          },
+          "Initialization attempt failed"
+        );
+        retryCount++;
+        if (retryCount < maxRetries) {
+          const delay = 2 ** retryCount * 1e3;
+          logger4.info(
+            {
+              src: "plugin:telegram",
+              agentId: runtime.agentId,
+              delaySeconds: delay / 1e3
+            },
+            "Retrying initialization"
+          );
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    logger4.error(
+      {
+        src: "plugin:telegram",
+        agentId: runtime.agentId,
+        maxRetries,
+        error: lastError?.message
+      },
+      "Initialization failed after all attempts"
+    );
+    return service;
+  }
+  /**
+   * Stops the agent runtime.
+   * @param {IAgentRuntime} runtime - The agent runtime to stop
+   */
+  static async stop(runtime) {
+    const tgClient = await runtime.getService(TELEGRAM_SERVICE_NAME);
+    if (tgClient) {
+      await tgClient.stop();
+    }
+  }
+  /**
+   * Asynchronously stops the bot.
+   *
+   * @returns A Promise that resolves once the bot has stopped.
+   */
+  async stop() {
+    const bot = this.bot;
+    if (!bot) {
+      return;
+    }
+    bot.stop("service-stop");
+    if (this.botToken) {
+      const active = ACTIVE_TELEGRAM_POLLERS.get(this.botToken);
+      if (active?.bot === bot) {
+        ACTIVE_TELEGRAM_POLLERS.delete(this.botToken);
+      }
+    }
+  }
+  /**
+   * Initializes the Telegram bot by launching it, getting bot info, and setting up message manager.
+   * @returns {Promise<void>} A Promise that resolves when the initialization is complete.
+   */
+  async initializeBot() {
+    const bot = this.bot;
+    if (!bot) {
+      throw new Error("Telegram bot is not initialized");
+    }
+    const botToken = this.botToken;
+    if (botToken) {
+      const active = ACTIVE_TELEGRAM_POLLERS.get(botToken);
+      if (active && active.bot !== bot) {
+        logger4.warn(
+          {
+            src: "plugin:telegram",
+            agentId: this.runtime.agentId,
+            previousAgentId: active.agentId
+          },
+          "Stopping existing Telegram poller before launching a new one"
+        );
+        try {
+          active.bot.stop("replaced-by-new-runtime");
+        } catch (error) {
+          logger4.warn(
+            {
+              src: "plugin:telegram",
+              agentId: this.runtime.agentId,
+              error: error instanceof Error ? error.message : String(error)
+            },
+            "Failed to stop previous Telegram poller cleanly"
+          );
+        }
+        ACTIVE_TELEGRAM_POLLERS.delete(botToken);
+        await new Promise((resolve) => setTimeout(resolve, 300));
+      }
+    }
+    bot.start((ctx) => {
+      const slashStartPayload = {
+        ctx,
+        runtime: this.runtime,
+        source: "telegram"
+      };
+      this.runtime.emitEvent(
+        "TELEGRAM_SLASH_START" /* SLASH_START */,
+        slashStartPayload
+      );
+    });
+    await bot.launch({
+      dropPendingUpdates: true,
+      allowedUpdates: ["message", "message_reaction"]
+    });
+    if (botToken) {
+      ACTIVE_TELEGRAM_POLLERS.set(botToken, {
+        bot,
+        agentId: this.runtime.agentId
+      });
+    }
+    const botInfo = await bot.telegram.getMe();
+    logger4.debug(
+      {
+        src: "plugin:telegram",
+        agentId: this.runtime.agentId,
+        botId: botInfo.id,
+        botUsername: botInfo.username
+      },
+      "Bot info retrieved"
+    );
+    process.once("SIGINT", () => bot.stop("SIGINT"));
+    process.once("SIGTERM", () => bot.stop("SIGTERM"));
+  }
+  /**
+   * Sets up the middleware chain for preprocessing messages before they reach handlers.
+   * This critical method establishes a sequential processing pipeline that:
+   *
+   * 1. Authorization - Verifies if a chat is allowed to interact with the bot based on configured settings
+   * 2. Chat Discovery - Ensures chat entities and worlds exist in the runtime, creating them if needed
+   * 3. Forum Topics - Handles Telegram forum topics as separate rooms for better conversation management
+   * 4. Entity Synchronization - Ensures message senders are properly synchronized as entities
+   *
+   * The middleware chain runs in sequence for each message, with each step potentially
+   * enriching the context or stopping processing if conditions aren't met.
+   * This preprocessing is essential for maintaining consistent state before message handlers execute.
+   *
+   * @private
+   */
+  setupMiddlewares() {
+    this.bot?.use(this.authorizationMiddleware.bind(this));
+    this.bot?.use(this.chatAndEntityMiddleware.bind(this));
+  }
+  /**
+   * Authorization middleware - checks if chat is allowed to interact with the bot
+   * based on the TELEGRAM_ALLOWED_CHATS configuration.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @param {Function} next - The function to call to proceed to the next middleware
+   * @returns {Promise<void>}
+   * @private
+   */
+  async authorizationMiddleware(ctx, next) {
+    if (!await this.isGroupAuthorized(ctx)) {
+      logger4.debug(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          chatId: ctx.chat?.id
+        },
+        "Chat not authorized, skipping"
+      );
+      return;
+    }
+    await next();
+  }
+  /**
+   * Chat and entity management middleware - handles new chats, forum topics, and entity synchronization.
+   * This middleware implements decision logic to determine which operations are needed based on
+   * the chat type and whether we've seen this chat before.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @param {Function} next - The function to call to proceed to the next middleware
+   * @returns {Promise<void>}
+   * @private
+   */
+  async chatAndEntityMiddleware(ctx, next) {
+    if (!ctx.chat) {
+      return next();
+    }
+    const chatId = ctx.chat.id.toString();
+    if (!this.knownChats.has(chatId)) {
+      await this.handleNewChat(ctx);
+      return next();
+    }
+    await this.processExistingChat(ctx);
+    await next();
+  }
+  /**
+   * Process an existing chat based on chat type and message properties.
+   * Different chat types require different processing steps.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @returns {Promise<void>}
+   * @private
+   */
+  async processExistingChat(ctx) {
+    if (!ctx.chat) {
+      return;
+    }
+    const chat = ctx.chat;
+    if (chat.type === "supergroup" && chat.is_forum && ctx.message?.message_thread_id) {
+      try {
+        await this.handleForumTopic(ctx);
+      } catch (error) {
+        logger4.error(
+          {
+            src: "plugin:telegram",
+            agentId: this.runtime.agentId,
+            chatId: chat.id,
+            error: error instanceof Error ? error.message : String(error)
+          },
+          "Error handling forum topic"
+        );
+      }
+    }
+    if (ctx.from && ctx.chat.type !== "private") {
+      await this.syncEntity(ctx);
+    }
+  }
+  /**
+   * Sets up message and reaction handlers for the bot.
+   * Configures event handlers to process incoming messages and reactions.
+   *
+   * @private
+   */
+  setupMessageHandlers() {
+    this.bot?.on("message", async (ctx) => {
+      try {
+        await this.messageManager?.handleMessage(ctx);
+      } catch (error) {
+        logger4.error(
+          {
+            src: "plugin:telegram",
+            agentId: this.runtime.agentId,
+            error: error instanceof Error ? error.message : String(error)
+          },
+          "Error handling message"
+        );
+      }
+    });
+    this.bot?.on("message_reaction", async (ctx) => {
+      try {
+        await this.messageManager?.handleReaction(ctx);
+      } catch (error) {
+        logger4.error(
+          {
+            src: "plugin:telegram",
+            agentId: this.runtime.agentId,
+            error: error instanceof Error ? error.message : String(error)
+          },
+          "Error handling reaction"
+        );
+      }
+    });
+  }
+  /**
+   * Checks if a group is authorized, based on the TELEGRAM_ALLOWED_CHATS setting.
+   * @param {Context} ctx - The context of the incoming update.
+   * @returns {Promise<boolean>} A Promise that resolves with a boolean indicating if the group is authorized.
+   */
+  async isGroupAuthorized(ctx) {
+    const chatId = ctx.chat?.id.toString();
+    if (!chatId) {
+      return false;
+    }
+    const allowedChats = this.runtime.getSetting("TELEGRAM_ALLOWED_CHATS");
+    if (!allowedChats) {
+      return true;
+    }
+    try {
+      const allowedChatsList = JSON.parse(allowedChats);
+      return allowedChatsList.includes(chatId);
+    } catch (error) {
+      logger4.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error parsing TELEGRAM_ALLOWED_CHATS"
+      );
+      return false;
+    }
+  }
+  /**
+   * Synchronizes an entity from a message context with the runtime system.
+   * This method handles three cases:
+   * 1. Message sender - most common case
+   * 2. New chat member - when a user joins the chat
+   * 3. Left chat member - when a user leaves the chat
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @returns {Promise<void>}
+   * @private
+   */
+  async syncEntity(ctx) {
+    if (!ctx.chat) {
+      return;
+    }
+    const chat = ctx.chat;
+    const chatId = chat.id.toString();
+    const worldId = createUniqueUuid2(this.runtime, chatId);
+    const roomId = createUniqueUuid2(
+      this.runtime,
+      ctx.message?.message_thread_id ? `${ctx.chat.id}-${ctx.message.message_thread_id}` : ctx.chat.id.toString()
+    );
+    await this.syncMessageSender(ctx, worldId, roomId, chatId);
+    await this.syncNewChatMember(ctx, worldId, roomId, chatId);
+    await this.syncLeftChatMember(ctx);
+  }
+  /**
+   * Synchronizes the message sender entity with the runtime system.
+   * This is the most common entity sync case.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @param {UUID} worldId - The ID of the world
+   * @param {UUID} roomId - The ID of the room
+   * @param {string} chatId - The ID of the chat
+   * @returns {Promise<void>}
+   * @private
+   */
+  async syncMessageSender(ctx, worldId, roomId, chatId) {
+    if (ctx.from) {
+      const telegramId = ctx.from.id.toString();
+      const entityId = createUniqueUuid2(this.runtime, telegramId);
+      if (this.syncedEntityIds.has(entityId)) {
+        return;
+      }
+      await this.runtime.ensureConnection({
+        entityId,
+        roomId,
+        roomName: getTelegramChatDisplayName(ctx.chat, chatId),
+        userName: ctx.from.username,
+        userId: telegramId,
+        name: ctx.from.first_name || ctx.from.username || "Unknown User",
+        source: "telegram",
+        channelId: chatId,
+        type: ChannelType2.GROUP,
+        worldId
+      });
+      this.syncedEntityIds.add(entityId);
+    }
+  }
+  /**
+   * Synchronizes a new chat member entity with the runtime system.
+   * Triggered when a user joins the chat.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @param {UUID} worldId - The ID of the world
+   * @param {UUID} roomId - The ID of the room
+   * @param {string} chatId - The ID of the chat
+   * @returns {Promise<void>}
+   * @private
+   */
+  async syncNewChatMember(ctx, worldId, roomId, chatId) {
+    if (ctx.message && "new_chat_members" in ctx.message) {
+      for (const newMember of ctx.message.new_chat_members) {
+        const telegramId = newMember.id.toString();
+        const entityId = createUniqueUuid2(this.runtime, telegramId);
+        if (this.syncedEntityIds.has(entityId)) {
+          continue;
+        }
+        await this.runtime.ensureConnection({
+          entityId,
+          roomId,
+          roomName: getTelegramChatDisplayName(ctx.chat, chatId),
+          userName: newMember.username,
+          userId: telegramId,
+          name: newMember.first_name || newMember.username || "Unknown User",
+          source: "telegram",
+          channelId: chatId,
+          type: ChannelType2.GROUP,
+          worldId
+        });
+        this.syncedEntityIds.add(entityId);
+        const entityJoinedPayload = {
+          runtime: this.runtime,
+          entityId,
+          worldId,
+          source: "telegram",
+          telegramUser: {
+            id: newMember.id,
+            username: newMember.username,
+            first_name: newMember.first_name
+          }
+        };
+        this.runtime.emitEvent(
+          "TELEGRAM_ENTITY_JOINED" /* ENTITY_JOINED */,
+          entityJoinedPayload
+        );
+      }
+    }
+  }
+  /**
+   * Updates entity status when a user leaves the chat.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @returns {Promise<void>}
+   * @private
+   */
+  async syncLeftChatMember(ctx) {
+    if (ctx.message && "left_chat_member" in ctx.message) {
+      const leftMember = ctx.message.left_chat_member;
+      const telegramId = leftMember.id.toString();
+      const entityId = createUniqueUuid2(this.runtime, telegramId);
+      const existingEntity = await this.runtime.getEntityById(entityId);
+      if (existingEntity) {
+        existingEntity.metadata = {
+          ...existingEntity.metadata,
+          status: "INACTIVE",
+          leftAt: Date.now()
+        };
+        await this.runtime.updateEntity(existingEntity);
+      }
+    }
+  }
+  /**
+   * Handles forum topics by creating appropriate rooms in the runtime system.
+   * This enables proper conversation management for Telegram's forum feature.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @returns {Promise<void>}
+   * @private
+   */
+  async handleForumTopic(ctx) {
+    if (!ctx.chat || !ctx.message?.message_thread_id) {
+      return;
+    }
+    const chat = ctx.chat;
+    const chatId = chat.id.toString();
+    const worldId = createUniqueUuid2(this.runtime, chatId);
+    const room = await this.buildForumTopicRoom(ctx, worldId);
+    if (!room) {
+      return;
+    }
+    await this.runtime.ensureRoomExists(room);
+  }
+  /**
+   * Builds entity for message sender
+   */
+  buildMsgSenderEntity(from) {
+    if (!from) {
+      return null;
+    }
+    const userId = createUniqueUuid2(this.runtime, from.id.toString());
+    const telegramId = from.id.toString();
+    return {
+      id: userId,
+      agentId: this.runtime.agentId,
+      names: [from.first_name || from.username || "Unknown User"],
+      metadata: {
+        telegram: {
+          id: telegramId,
+          username: from.username,
+          name: from.first_name || from.username || "Unknown User"
+        }
+      }
+    };
+  }
+  /**
+   * Handles new chat discovery and emits WORLD_JOINED event.
+   * This is a critical function that ensures new chats are properly
+   * registered in the runtime system and appropriate events are emitted.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @returns {Promise<void>}
+   * @private
+   */
+  async handleNewChat(ctx) {
+    if (!ctx.chat) {
+      return;
+    }
+    const chat = ctx.chat;
+    const chatId = chat.id.toString();
+    this.knownChats.set(chatId, chat);
+    const { chatTitle, channelType } = this.getChatTypeInfo(chat);
+    const worldId = createUniqueUuid2(this.runtime, chatId);
+    const existingWorld = await this.runtime.getWorld(worldId);
+    if (existingWorld) {
+      return;
+    }
+    const userId = ctx.from ? createUniqueUuid2(this.runtime, ctx.from.id.toString()) : null;
+    let admins = [];
+    let owner = null;
+    if (chat.type === "group" || chat.type === "supergroup" || chat.type === "channel") {
+      try {
+        const chatAdmins = await ctx.getChatAdministrators();
+        admins = chatAdmins;
+        const foundOwner = admins.find(
+          (admin) => admin.status === "creator"
+        );
+        owner = foundOwner || null;
+      } catch (error) {
+        logger4.warn(
+          {
+            src: "plugin:telegram",
+            agentId: this.runtime.agentId,
+            chatId,
+            error: error instanceof Error ? error.message : String(error)
+          },
+          "Could not get chat administrators"
+        );
+      }
+    }
+    const canonicalOwnerId = getCanonicalOwnerId(this.runtime);
+    let ownerId = canonicalOwnerId ?? userId;
+    if (!canonicalOwnerId && owner) {
+      ownerId = createUniqueUuid2(this.runtime, String(owner.user.id));
+    }
+    const world = {
+      id: worldId,
+      name: chatTitle,
+      agentId: this.runtime.agentId,
+      messageServerId: chatId,
+      metadata: {
+        source: "telegram",
+        ...ownerId && { ownership: { ownerId } },
+        roles: ownerId ? {
+          [ownerId]: Role.OWNER
+        } : {},
+        chatType: chat.type,
+        isForumEnabled: chat.type === "supergroup" && chat.is_forum
+      }
+    };
+    await this.runtime.ensureWorldExists(world);
+    const generalRoom = {
+      id: createUniqueUuid2(this.runtime, chatId),
+      name: chatTitle,
+      source: "telegram",
+      type: channelType,
+      channelId: chatId,
+      serverId: chatId,
+      worldId
+    };
+    await this.runtime.ensureRoomExists(generalRoom);
+    const rooms = [generalRoom];
+    if (chat.type === "supergroup" && chat.is_forum && ctx.message?.message_thread_id) {
+      const topicRoom = await this.buildForumTopicRoom(ctx, worldId);
+      if (topicRoom) {
+        rooms.push(topicRoom);
+        await this.runtime.ensureRoomExists(topicRoom);
+      }
+    }
+    const entities = await this.buildStandardizedEntities(chat);
+    if (ctx.from) {
+      const senderEntity = this.buildMsgSenderEntity(ctx.from);
+      if (senderEntity?.id && !entities.some((e) => e.id === senderEntity.id)) {
+        entities.push(senderEntity);
+        this.syncedEntityIds.add(senderEntity.id);
+      }
+    }
+    await this.batchProcessEntities(
+      entities,
+      generalRoom.id,
+      generalRoom.name || generalRoom.channelId || chatId,
+      generalRoom.channelId || chatId,
+      generalRoom.type,
+      worldId
+    );
+    const telegramWorldPayload = {
+      runtime: this.runtime,
+      world,
+      rooms,
+      entities,
+      source: "telegram",
+      chat,
+      botUsername: this.bot?.botInfo?.username
+    };
+    if (chat.type !== "private") {
+      await this.runtime.emitEvent(
+        "TELEGRAM_WORLD_JOINED" /* WORLD_JOINED */,
+        telegramWorldPayload
+      );
+    }
+    await this.runtime.emitEvent(EventType2.WORLD_JOINED, {
+      runtime: this.runtime,
+      world,
+      rooms,
+      entities,
+      source: "telegram"
+    });
+  }
+  /**
+   * Processes entities in batches to prevent overwhelming the system.
+   *
+   * @param {Entity[]} entities - The entities to process
+   * @param {UUID} roomId - The ID of the room to connect entities to
+   * @param {string} channelId - The channel ID
+   * @param {ChannelType} roomType - The type of the room
+   * @param {UUID} worldId - The ID of the world
+   * @returns {Promise<void>}
+   * @private
+   */
+  async batchProcessEntities(entities, roomId, roomName, channelId, roomType, worldId) {
+    const batchSize = 50;
+    for (let i = 0; i < entities.length; i += batchSize) {
+      const entityBatch = entities.slice(i, i + batchSize);
+      await Promise.all(
+        entityBatch.map(async (entity) => {
+          try {
+            if (entity.id) {
+              const telegramMetadata = entity.metadata?.telegram;
+              await this.runtime.ensureConnection({
+                entityId: entity.id,
+                roomId,
+                roomName,
+                userName: telegramMetadata?.username,
+                name: telegramMetadata?.name,
+                userId: telegramMetadata?.id,
+                source: "telegram",
+                channelId,
+                type: roomType,
+                worldId
+              });
+            } else {
+              logger4.warn(
+                {
+                  src: "plugin:telegram",
+                  agentId: this.runtime.agentId,
+                  entityNames: entity.names
+                },
+                "Skipping entity sync due to missing ID"
+              );
+            }
+          } catch (err) {
+            const telegramMetadata = entity.metadata?.telegram;
+            logger4.warn(
+              {
+                src: "plugin:telegram",
+                agentId: this.runtime.agentId,
+                username: telegramMetadata?.username,
+                error: err instanceof Error ? err.message : String(err)
+              },
+              "Failed to sync user"
+            );
+          }
+        })
+      );
+      if (i + batchSize < entities.length) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
+    }
+  }
+  /**
+   * Gets chat title and channel type based on Telegram chat type.
+   * Maps Telegram-specific chat types to standardized system types.
+   *
+   * @param {any} chat - The Telegram chat object
+   * @returns {Object} Object containing chatTitle and channelType
+   * @private
+   */
+  getChatTypeInfo(chat) {
+    const chatType = chat.type;
+    let chatTitle;
+    let channelType;
+    switch (chatType) {
+      case "private":
+        chatTitle = `Chat with ${chat.first_name || "Unknown User"}`;
+        channelType = ChannelType2.DM;
+        break;
+      case "group":
+        chatTitle = chat.title || "Unknown Group";
+        channelType = ChannelType2.GROUP;
+        break;
+      case "supergroup":
+        chatTitle = chat.title || "Unknown Supergroup";
+        channelType = ChannelType2.GROUP;
+        break;
+      case "channel":
+        chatTitle = chat.title || "Unknown Channel";
+        channelType = ChannelType2.FEED;
+        break;
+      default:
+        throw new Error(`Unrecognized Telegram chat type: ${String(chatType)}`);
+    }
+    return { chatTitle, channelType };
+  }
+  /**
+   * Builds standardized entity representations from Telegram chat data.
+   * Transforms Telegram-specific user data into system-standard Entity objects.
+   *
+   * @param {any} chat - The Telegram chat object
+   * @returns {Promise<Entity[]>} Array of standardized Entity objects
+   * @private
+   */
+  async buildStandardizedEntities(chat) {
+    const entities = [];
+    try {
+      if (chat.type === "private" && chat.id) {
+        const userId = createUniqueUuid2(
+          this.runtime,
+          chat.id.toString()
+        );
+        entities.push({
+          id: userId,
+          names: [chat.first_name || "Unknown User"],
+          agentId: this.runtime.agentId,
+          metadata: {
+            telegram: {
+              id: chat.id.toString(),
+              username: chat.username || "unknown",
+              name: chat.first_name || "Unknown User"
+            },
+            source: "telegram"
+          }
+        });
+        this.syncedEntityIds.add(userId);
+      } else if (chat.type === "group" || chat.type === "supergroup") {
+        try {
+          const admins = await this.bot?.telegram.getChatAdministrators(
+            chat.id
+          );
+          if (admins && admins.length > 0) {
+            for (const admin of admins) {
+              const userId = createUniqueUuid2(
+                this.runtime,
+                admin.user.id.toString()
+              );
+              entities.push({
+                id: userId,
+                names: [
+                  admin.user.first_name || admin.user.username || "Unknown Admin"
+                ],
+                agentId: this.runtime.agentId,
+                metadata: {
+                  telegram: {
+                    id: admin.user.id.toString(),
+                    username: admin.user.username || "unknown",
+                    name: admin.user.first_name || "Unknown Admin",
+                    isAdmin: true,
+                    adminTitle: admin.custom_title || (admin.status === "creator" ? "Owner" : "Admin")
+                  },
+                  source: "telegram",
+                  roles: [admin.status === "creator" ? Role.OWNER : Role.ADMIN]
+                }
+              });
+              this.syncedEntityIds.add(userId);
+            }
+          }
+        } catch (error) {
+          logger4.warn(
+            {
+              src: "plugin:telegram",
+              agentId: this.runtime.agentId,
+              chatId: chat.id,
+              error: error instanceof Error ? error.message : String(error)
+            },
+            "Could not fetch administrators"
+          );
+        }
+      }
+    } catch (error) {
+      logger4.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error building standardized entities"
+      );
+    }
+    return entities;
+  }
+  /**
+   * Extracts and builds the room object for a forum topic from a message context.
+   * This refactored method can be used both in middleware and when handling new chats.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @param {UUID} worldId - The ID of the world the topic belongs to
+   * @returns {Promise<Room | null>} A Promise that resolves with the room or null if not a topic
+   * @private
+   */
+  async buildForumTopicRoom(ctx, worldId) {
+    if (!ctx.chat || !ctx.message?.message_thread_id) {
+      return null;
+    }
+    if (ctx.chat.type !== "supergroup" || !ctx.chat.is_forum) {
+      return null;
+    }
+    const chat = ctx.chat;
+    const chatId = chat.id.toString();
+    const threadId = ctx.message.message_thread_id.toString();
+    const roomId = createUniqueUuid2(
+      this.runtime,
+      `${chatId}-${threadId}`
+    );
+    try {
+      const replyMessage = JSON.parse(JSON.stringify(ctx.message));
+      let topicName = `Topic #${threadId}`;
+      if (replyMessage && typeof replyMessage === "object" && "forum_topic_created" in replyMessage && replyMessage.forum_topic_created) {
+        const topicCreated = replyMessage.forum_topic_created;
+        if (topicCreated && typeof topicCreated === "object" && "name" in topicCreated) {
+          topicName = topicCreated.name;
+        }
+      } else if (replyMessage && typeof replyMessage === "object" && "reply_to_message" in replyMessage && replyMessage.reply_to_message && typeof replyMessage.reply_to_message === "object" && "forum_topic_created" in replyMessage.reply_to_message && replyMessage.reply_to_message.forum_topic_created) {
+        const topicCreated = replyMessage.reply_to_message.forum_topic_created;
+        if (topicCreated && typeof topicCreated === "object" && "name" in topicCreated) {
+          topicName = topicCreated.name;
+        }
+      }
+      const room = {
+        id: roomId,
+        name: topicName,
+        source: "telegram",
+        type: ChannelType2.GROUP,
+        channelId: `${chatId}-${threadId}`,
+        serverId: chatId,
+        worldId,
+        metadata: {
+          threadId,
+          isForumTopic: true,
+          parentChatId: chatId
+        }
+      };
+      return room;
+    } catch (error) {
+      logger4.error(
+        {
+          src: "plugin:telegram",
+          agentId: this.runtime.agentId,
+          chatId,
+          threadId,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error building forum topic room"
+      );
+      return null;
+    }
+  }
+  static registerSendHandlers(runtime, serviceInstance) {
+    if (serviceInstance?.bot) {
+      runtime.registerSendHandler(
+        "telegram",
+        serviceInstance.handleSendMessage.bind(serviceInstance)
+      );
+      logger4.info(
+        { src: "plugin:telegram", agentId: runtime.agentId },
+        "Registered send handler"
+      );
+    } else {
+      logger4.warn(
+        { src: "plugin:telegram", agentId: runtime.agentId },
+        "Cannot register send handler, bot not initialized"
+      );
+    }
+  }
+  async handleSendMessage(runtime, target, content) {
+    if (!this.bot || !this.messageManager) {
+      logger4.error(
+        { src: "plugin:telegram", agentId: runtime.agentId },
+        "Bot not initialized, cannot send messages"
+      );
+      throw new Error(
+        "Telegram bot is not initialized. Please provide TELEGRAM_BOT_TOKEN."
+      );
+    }
+    let chatId;
+    if (target.channelId) {
+      chatId = target.channelId;
+    } else if (target.roomId) {
+      const room = await runtime.getRoom(target.roomId);
+      chatId = room?.channelId;
+      if (!chatId) {
+        throw new Error(
+          `Could not resolve Telegram chat ID from roomId ${target.roomId}`
+        );
+      }
+    } else if (target.entityId) {
+      const entity = await runtime.getEntityById(target.entityId);
+      if (!entity) {
+        throw new Error(`Entity ${target.entityId} not found`);
+      }
+      const telegramMeta = entity.metadata?.telegram;
+      const telegramId = telegramMeta?.id;
+      if (!telegramId) {
+        logger4.error(
+          {
+            src: "plugin:telegram",
+            agentId: runtime.agentId,
+            entityId: target.entityId
+          },
+          "Entity has no telegram.id in metadata \u2014 cannot send DM without Telegram user ID"
+        );
+        throw new Error(
+          `Entity ${target.entityId} has no telegram.id in metadata \u2014 cannot send DM without Telegram user ID`
+        );
+      }
+      chatId = telegramId;
+    } else {
+      throw new Error(
+        "Telegram SendHandler requires channelId, roomId, or entityId."
+      );
+    }
+    if (!chatId) {
+      throw new Error(
+        `Could not determine target Telegram chat ID for target: ${JSON.stringify(target)}`
+      );
+    }
+    try {
+      await this.messageManager.sendMessage(chatId, content);
+      logger4.info(
+        { src: "plugin:telegram", agentId: runtime.agentId, chatId },
+        "Message sent"
+      );
+    } catch (error) {
+      logger4.error(
+        {
+          src: "plugin:telegram",
+          agentId: runtime.agentId,
+          chatId,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error sending message"
+      );
+      throw error;
+    }
+  }
+};
+
+// src/setup-routes.ts
+import { logger as logger5 } from "@elizaos/core";
+var TELEGRAM_API_BASE = "https://api.telegram.org";
+function getSetupService2(runtime) {
+  return runtime.getService("connector-setup");
+}
+async function readJsonBody(req) {
+  return req.body ?? null;
+}
+async function handleValidateToken(req, res, runtime) {
+  const body = await readJsonBody(req);
+  const token = typeof body?.token === "string" ? body.token.trim() : "";
+  if (!token) {
+    res.status(200).json({ ok: false, error: "token is required" });
+    return;
+  }
+  if (!/^\d+:[A-Za-z0-9_-]{30,}$/.test(token)) {
+    res.status(200).json({
+      ok: false,
+      error: "Token format invalid. Expected format: 123456:ABC-DEF..."
+    });
+    return;
+  }
+  try {
+    const apiRes = await fetch(`${TELEGRAM_API_BASE}/bot${token}/getMe`, {
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!apiRes.ok) {
+      res.status(200).json({
+        ok: false,
+        error: `Telegram API returned ${apiRes.status}. Check that the token is correct.`
+      });
+      return;
+    }
+    const data = await apiRes.json();
+    if (!data.ok || !data.result) {
+      res.status(200).json({
+        ok: false,
+        error: "Telegram API returned unexpected response"
+      });
+      return;
+    }
+    const bot = data.result;
+    const setupService = getSetupService2(runtime);
+    if (setupService) {
+      setupService.updateConfig((config) => {
+        if (!config.connectors) {
+          config.connectors = {};
+        }
+        const connectors = config.connectors;
+        if (!connectors.telegram || typeof connectors.telegram !== "object") {
+          connectors.telegram = {};
+        }
+        connectors.telegram.botToken = token;
+      });
+      setupService.setOwnerContact({
+        source: "telegram",
+        channelId: String(bot.id)
+      });
+      setupService.registerEscalationChannel("telegram");
+    } else {
+      logger5.warn(
+        "[telegram-setup] connector-setup service not available \u2014 token saved to runtime only"
+      );
+    }
+    res.status(200).json({
+      ok: true,
+      bot: {
+        id: bot.id,
+        username: bot.username,
+        firstName: bot.first_name
+      }
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    res.status(200).json({
+      ok: false,
+      error: `Failed to reach Telegram API: ${message}`
+    });
+  }
+}
+async function handleStatus2(_req, res, runtime) {
+  const setupService = getSetupService2(runtime);
+  let hasToken = false;
+  if (setupService) {
+    const config = setupService.getConfig();
+    const connectors = config.connectors ?? {};
+    const tgConfig = connectors.telegram;
+    hasToken = Boolean(tgConfig?.botToken);
+  }
+  if (!hasToken) {
+    hasToken = Boolean(runtime.getSetting("TELEGRAM_BOT_TOKEN"));
+  }
+  const service = runtime.getService("telegram");
+  const connected = Boolean(service);
+  res.status(200).json({
+    available: true,
+    hasToken,
+    connected
+  });
+}
+async function handleDisconnect2(_req, res, runtime) {
+  const setupService = getSetupService2(runtime);
+  if (setupService) {
+    setupService.updateConfig((config) => {
+      const connectors = config.connectors ?? {};
+      const tgConfig = connectors.telegram;
+      if (tgConfig) {
+        delete tgConfig.botToken;
+      }
+    });
+  }
+  res.status(200).json({ ok: true });
+}
+var telegramSetupRoutes = [
+  {
+    type: "POST",
+    path: "/api/telegram-setup/validate-token",
+    handler: handleValidateToken,
+    rawPath: true
+  },
+  {
+    type: "GET",
+    path: "/api/telegram-setup/status",
+    handler: handleStatus2,
+    rawPath: true
+  },
+  {
+    type: "POST",
+    path: "/api/telegram-setup/disconnect",
+    handler: handleDisconnect2,
+    rawPath: true
+  }
+];
+
+// src/tests.ts
+import { logger as logger6 } from "@elizaos/core";
+var TEST_IMAGE_URL = "https://github.com/elizaOS/awesome-eliza/blob/main/assets/eliza-logo.jpg?raw=true";
+var TelegramTestSuite = class {
+  name = "telegram";
+  telegramClient = null;
+  bot = null;
+  messageManager = null;
+  tests;
+  /**
+   * Constructor for initializing a set of test cases for a Telegram bot.
+   *
+   * @constructor
+   * @property {Array<Object>} tests - An array of test cases with name and corresponding test functions.
+   * @property {string} tests.name - The name of the test case.
+   * @property {function} tests.fn - The test function to be executed.
+   */
+  constructor() {
+    this.tests = [
+      {
+        name: "Initialize and Validate Telegram Bot Connection",
+        fn: this.testCreatingTelegramBot.bind(this)
+      },
+      {
+        name: "Send Basic Text Message to Telegram Chat",
+        fn: this.testSendingTextMessage.bind(this)
+      },
+      {
+        name: "Send Text Message with an Image Attachment",
+        fn: this.testSendingMessageWithAttachment.bind(this)
+      },
+      {
+        name: "Handle and Process Incoming Telegram Messages",
+        fn: this.testHandlingMessage.bind(this)
+      },
+      {
+        name: "Process and Validate Image Attachments in Incoming Messages",
+        fn: this.testProcessingImages.bind(this)
+      }
+    ];
+  }
+  /**
+   * Retrieves the Telegram test chat ID from environment variables.
+   *
+   * Reference on getting the Telegram chat ID:
+   * https://stackoverflow.com/a/32572159
+   */
+  /**
+   * Validates the chat ID by checking if it is set in the runtime settings or environment variables.
+   * If not set, an error is thrown with a message instructing to provide a valid chat ID.
+   * @param {IAgentRuntime} runtime - The runtime object that provides access to the settings and environment variables.
+   * @throws {Error} If TELEGRAM_TEST_CHAT_ID is not set in the runtime settings or environment variables.
+   * @returns {string} The validated chat ID.
+   */
+  validateChatId(runtime) {
+    const testChatId = runtime.getSetting("TELEGRAM_TEST_CHAT_ID") || process.env.TELEGRAM_TEST_CHAT_ID;
+    if (!testChatId || typeof testChatId === "boolean") {
+      throw new Error(
+        "TELEGRAM_TEST_CHAT_ID is not set. Please provide a valid chat ID in the environment variables."
+      );
+    }
+    return testChatId;
+  }
+  async getChatInfo(runtime) {
+    try {
+      const chatId = this.validateChatId(runtime);
+      if (!this.bot) {
+        throw new Error("Bot is not initialized.");
+      }
+      const chat = await this.bot.telegram.getChat(chatId);
+      logger6.debug({ src: "plugin:telegram", chatId }, "Fetched real chat");
+      return chat;
+    } catch (error) {
+      throw new Error(`Error fetching real Telegram chat: ${error}`);
+    }
+  }
+  async testCreatingTelegramBot(runtime) {
+    this.telegramClient = runtime.getService("telegram");
+    if (!this.telegramClient?.messageManager) {
+      throw new Error(
+        "Telegram service or message manager not initialized - check TELEGRAM_BOT_TOKEN"
+      );
+    }
+    this.bot = this.telegramClient.messageManager.bot;
+    this.messageManager = this.telegramClient.messageManager;
+    logger6.debug(
+      { src: "plugin:telegram" },
+      "Telegram bot initialized successfully"
+    );
+  }
+  async testSendingTextMessage(runtime) {
+    try {
+      if (!this.bot) {
+        throw new Error("Bot not initialized.");
+      }
+      const chatId = this.validateChatId(runtime);
+      await this.bot.telegram.sendMessage(chatId, "Testing Telegram message!");
+      logger6.debug(
+        { src: "plugin:telegram", chatId },
+        "Message sent successfully"
+      );
+    } catch (error) {
+      throw new Error(`Error sending Telegram message: ${error}`);
+    }
+  }
+  async testSendingMessageWithAttachment(runtime) {
+    try {
+      if (!this.messageManager) {
+        throw new Error("MessageManager not initialized.");
+      }
+      if (!this.bot) {
+        throw new Error("Bot not initialized.");
+      }
+      const chat = await this.getChatInfo(runtime);
+      const mockContext = {
+        chat,
+        from: { id: 123, username: "TestUser" },
+        telegram: this.bot.telegram
+      };
+      const messageContent = {
+        text: "Here is an image attachment:",
+        attachments: [
+          {
+            id: "123",
+            title: "Sample Image",
+            source: TEST_IMAGE_URL,
+            text: "Sample Image",
+            url: TEST_IMAGE_URL,
+            contentType: "image/png",
+            description: "Sample Image"
+          }
+        ]
+      };
+      await this.messageManager.sendMessageInChunks(
+        mockContext,
+        messageContent
+      );
+      logger6.success(
+        { src: "plugin:telegram" },
+        "Message with image attachment sent successfully"
+      );
+    } catch (error) {
+      throw new Error(
+        `Error sending Telegram message with attachment: ${error}`
+      );
+    }
+  }
+  async testHandlingMessage(runtime) {
+    try {
+      if (!this.bot) {
+        throw new Error("Bot not initialized.");
+      }
+      if (!this.messageManager) {
+        throw new Error("MessageManager not initialized.");
+      }
+      const chat = await this.getChatInfo(runtime);
+      const mockContext = {
+        chat,
+        from: {
+          id: 123,
+          username: "TestUser",
+          is_bot: false,
+          first_name: "Test",
+          last_name: "User"
+        },
+        message: {
+          message_id: 12345,
+          text: `@${this.bot.botInfo?.username}! Hello!`,
+          date: Math.floor(Date.now() / 1e3),
+          chat
+        },
+        telegram: this.bot.telegram
+      };
+      try {
+        await this.messageManager.handleMessage(mockContext);
+      } catch (error) {
+        throw new Error(`Error handling Telegram message: ${error}`);
+      }
+    } catch (error) {
+      throw new Error(`Error handling Telegram message: ${error}`);
+    }
+  }
+  async testProcessingImages(runtime) {
+    try {
+      if (!this.bot) {
+        throw new Error("Bot not initialized.");
+      }
+      if (!this.messageManager) {
+        throw new Error("MessageManager not initialized.");
+      }
+      const chatId = this.validateChatId(runtime);
+      const fileId = await this.getFileId(String(chatId), TEST_IMAGE_URL);
+      const mockMessage = {
+        message_id: 12345,
+        chat: { id: chatId, type: "private" },
+        date: Math.floor(Date.now() / 1e3),
+        photo: [
+          {
+            file_id: fileId,
+            file_unique_id: `unique_${fileId}`,
+            width: 100,
+            height: 100
+          }
+        ],
+        text: `@${this.bot.botInfo?.username}!`
+      };
+      const result = await this.messageManager.processImage(
+        mockMessage
+      );
+      if (!result?.description) {
+        throw new Error(
+          "Error processing Telegram image or description not found"
+        );
+      }
+      const { description } = result;
+      logger6.debug(
+        { src: "plugin:telegram", description },
+        "Processing Telegram image successfully"
+      );
+    } catch (error) {
+      throw new Error(`Error processing Telegram image: ${error}`);
+    }
+  }
+  async getFileId(chatId, imageUrl) {
+    try {
+      if (!this.bot) {
+        throw new Error("Bot is not initialized.");
+      }
+      const message = await this.bot.telegram.sendPhoto(chatId, imageUrl);
+      if (message.photo.length === 0) {
+        throw new Error("No photo received in the message response.");
+      }
+      return message.photo[message.photo.length - 1].file_id;
+    } catch (error) {
+      logger6.error(
+        {
+          src: "plugin:telegram",
+          chatId,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        "Error sending image"
+      );
+      throw error;
+    }
+  }
+};
+
+// src/index.ts
+var telegramPlugin = {
+  name: TELEGRAM_SERVICE_NAME,
+  description: "Telegram client plugin",
+  // TelegramService must come before TelegramOwnerPairingServiceImpl so the
+  // bot instance exists when the pairing service registers its command.
+  services: [TelegramService, TelegramOwnerPairingServiceImpl],
+  routes: [...telegramSetupRoutes, ...telegramAccountRoutes],
+  tests: [new TelegramTestSuite()],
+  // Self-declared auto-enable: activate when the "telegram" connector is
+  // configured in eliza.json / eliza.json. The hardcoded CONNECTOR_PLUGINS
+  // map in plugin-auto-enable.ts still serves as a fallback.
+  autoEnable: {
+    connectorKeys: ["telegram"]
+  }
+};
+var index_default = telegramPlugin;
+export {
+  MessageManager,
+  TELEGRAM_OWNER_PAIRING_SERVICE_TYPE,
+  TelegramAccountAuthSession,
+  TelegramOwnerPairingServiceImpl,
+  TelegramService,
+  clearTelegramAccountAuthState,
+  clearTelegramAccountSession,
+  index_default as default,
+  defaultTelegramAccountDeviceModel,
+  defaultTelegramAccountSystemVersion,
+  loadTelegramAccountSessionString,
+  resolveTelegramAccountSessionFile,
+  saveTelegramAccountSessionString,
+  stopTelegramAccountAuthSession,
+  telegramAccountAuthStateExists,
+  telegramAccountSessionExists
+};
+//# sourceMappingURL=index.js.map