@elizaos/plugin-telegram 2.0.0-alpha.7 → 2.0.0-alpha.9

package/dist/index.js

@@ -0,0 +1,1820 @@
+// 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/service.ts
+import {
+  ChannelType as ChannelType2,
+  EventType as EventType2,
+  Role,
+  Service,
+  createUniqueUuid as createUniqueUuid2,
+  logger as logger3
+} from "@elizaos/core";
+import { Telegraf } from "telegraf";
+
+// src/messageManager.ts
+import {
+  ChannelType,
+  EventType,
+  ModelType,
+  ServiceType,
+  createUniqueUuid,
+  logger as logger2
+} from "@elizaos/core";
+import { Markup as Markup2 } from "telegraf";
+
+// src/utils.ts
+import { Markup } from "telegraf";
+import { logger } from "@elizaos/core";
+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 || "") + "\n" + 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[parseInt(index)];
+  });
+  return finalResult;
+}
+function convertToTelegramButtons(buttons) {
+  if (!buttons) return [];
+  const telegramButtons = [];
+  for (const button of buttons) {
+    if (!button || !button.text || !button.url) {
+      logger.warn({ 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
+import fs from "fs";
+var MAX_MESSAGE_LENGTH = 4096;
+var getChannelType = (chat) => {
+  switch (chat.type) {
+    case "private":
+      return ChannelType.DM;
+    case "group":
+    case "supergroup":
+    case "channel":
+      return ChannelType.GROUP;
+    default:
+      throw new Error(`Unrecognized Telegram chat type: ${chat.type}`);
+  }
+};
+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 = "";
+    let 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 = void 0;
+        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 entityId = createUniqueUuid(this.runtime, ctx.from.id.toString());
+      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 roomId = createUniqueUuid(this.runtime, telegramRoomid);
+      const messageId = createUniqueUuid(this.runtime, message?.message_id?.toString());
+      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);
+      const sourceId = createUniqueUuid(this.runtime, "" + chat.id);
+      await this.runtime.ensureConnection({
+        entityId,
+        roomId,
+        userName: ctx.from.username,
+        name: ctx.from.first_name,
+        source: "telegram",
+        channelId: telegramRoomid,
+        type: channelType,
+        worldId: createUniqueUuid(this.runtime, roomId),
+        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: {
+          entityName: ctx.from.first_name,
+          entityUserName: ctx.from.username,
+          fromBot: ctx.from.is_bot,
+          // include very technical/exact reference to this user for security reasons
+          // don't remove or change this, spartan needs this
+          fromId: chat.id,
+          sourceId,
+          // why message? all Memories contain content (which is basically a message)
+          // what are the other types? see MemoryType
+          type: "message"
+          // MemoryType.MESSAGE
+          // scope: `shared`, `private`, or `room`
+        },
+        createdAt: message.date * 1e3
+      };
+      const callback = async (content, _files) => {
+        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
+              },
+              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 [];
+        }
+      };
+      if (this.runtime.hasElizaOS()) {
+        await this.runtime.elizaOS.handleMessage(this.runtime.agentId, memory, {
+          onResponse: async (content) => {
+            await callback(content);
+          }
+        });
+      } 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) {
+        this.runtime.emitEvent(EventType.MESSAGE_SENT, {
+          runtime: this.runtime,
+          message: memories[0],
+          source: "telegram"
+        });
+      }
+      this.runtime.emitEvent(
+        "TELEGRAM_MESSAGE_SENT" /* MESSAGE_SENT */,
+        {
+          runtime: this.runtime,
+          source: "telegram",
+          originalMessages: sentMessages,
+          chatId,
+          message: memories[0]
+        }
+      );
+      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/service.ts
+var TelegramService = class _TelegramService extends Service {
+  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();
+  /**
+   * 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;
+      return;
+    }
+    logger3.debug({ src: "plugin:telegram", agentId: runtime.agentId }, "Constructing TelegramService");
+    const botToken = runtime.getSetting("TELEGRAM_BOT_TOKEN");
+    if (!botToken || botToken.trim() === "") {
+      logger3.warn({ src: "plugin:telegram", agentId: runtime.agentId }, "Bot token not provided, Telegram functionality unavailable");
+      this.bot = null;
+      this.messageManager = null;
+      return;
+    }
+    this.options = {
+      telegram: {
+        apiRoot: runtime.getSetting("TELEGRAM_API_ROOT") || process.env.TELEGRAM_API_ROOT || "https://api.telegram.org"
+      }
+    };
+    try {
+      this.bot = new Telegraf(botToken, this.options);
+      this.messageManager = new MessageManager(this.bot, this.runtime);
+      logger3.debug({ src: "plugin:telegram", agentId: runtime.agentId }, "TelegramService constructor completed");
+    } catch (error) {
+      logger3.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) {
+      logger3.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 {
+        logger3.info({ src: "plugin:telegram", agentId: runtime.agentId, agentName: runtime.character.name }, "Starting Telegram bot");
+        await service.initializeBot();
+        service.setupMiddlewares();
+        service.setupMessageHandlers();
+        await service.bot.telegram.getMe();
+        logger3.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));
+        logger3.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;
+          logger3.info({ src: "plugin:telegram", agentId: runtime.agentId, delaySeconds: delay / 1e3 }, "Retrying initialization");
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    logger3.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 = 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() {
+    this.bot?.stop();
+  }
+  /**
+   * 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() {
+    this.bot?.start((ctx) => {
+      this.runtime.emitEvent(
+        "TELEGRAM_SLASH_START" /* SLASH_START */,
+        {
+          ctx,
+          runtime: this.runtime,
+          source: "telegram"
+        }
+      );
+    });
+    this.bot?.launch({
+      dropPendingUpdates: true,
+      allowedUpdates: ["message", "message_reaction"]
+    });
+    const botInfo = await this.bot.telegram.getMe();
+    logger3.debug({ src: "plugin:telegram", agentId: this.runtime.agentId, botId: botInfo.id, botUsername: botInfo.username }, "Bot info retrieved");
+    process.once("SIGINT", () => this.bot?.stop("SIGINT"));
+    process.once("SIGTERM", () => this.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)) {
+      logger3.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) {
+        logger3.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) {
+        logger3.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) {
+        logger3.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) {
+      logger3.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 && !this.syncedEntityIds.has(ctx.from.id.toString())) {
+      const telegramId = ctx.from.id.toString();
+      const entityId = createUniqueUuid2(this.runtime, telegramId);
+      await this.runtime.ensureConnection({
+        entityId,
+        roomId,
+        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_member" in ctx.message) {
+      const newMember = ctx.message.new_chat_member;
+      const telegramId = newMember.id.toString();
+      const entityId = createUniqueUuid2(this.runtime, telegramId);
+      if (this.syncedEntityIds.has(telegramId)) return;
+      await this.runtime.ensureConnection({
+        entityId,
+        roomId,
+        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);
+      this.runtime.emitEvent(
+        "TELEGRAM_ENTITY_JOINED" /* ENTITY_JOINED */,
+        {
+          runtime: this.runtime,
+          entityId,
+          worldId,
+          source: "telegram",
+          telegramUser: {
+            id: newMember.id,
+            username: newMember.username,
+            first_name: newMember.first_name
+          }
+        }
+      );
+    }
+  }
+  /**
+   * 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) {
+        logger3.warn({ src: "plugin:telegram", agentId: this.runtime.agentId, chatId, error: error instanceof Error ? error.message : String(error) }, "Could not get chat administrators");
+      }
+    }
+    let ownerId = userId;
+    if (owner) {
+      ownerId = createUniqueUuid2(this.runtime, String(owner.user.id));
+    }
+    const world = {
+      id: worldId,
+      name: chatTitle,
+      agentId: this.runtime.agentId,
+      serverId: 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 && senderEntity.id && !entities.some((e) => e.id === senderEntity.id)) {
+        entities.push(senderEntity);
+        this.syncedEntityIds.add(senderEntity.id);
+      }
+    }
+    await this.batchProcessEntities(
+      entities,
+      generalRoom.id,
+      generalRoom.channelId,
+      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, 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,
+                userName: telegramMetadata?.username,
+                name: telegramMetadata?.name,
+                userId: telegramMetadata?.id,
+                source: "telegram",
+                channelId,
+                type: roomType,
+                worldId
+              });
+            } else {
+              logger3.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;
+            logger3.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) {
+    let chatTitle;
+    let channelType;
+    switch (chat.type) {
+      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:
+        chatTitle = "Unknown Chat";
+        channelType = ChannelType2.GROUP;
+    }
+    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) {
+          logger3.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) {
+      logger3.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) {
+      logger3.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 && serviceInstance.bot) {
+      runtime.registerSendHandler(
+        "telegram",
+        serviceInstance.handleSendMessage.bind(serviceInstance)
+      );
+      logger3.info({ src: "plugin:telegram", agentId: runtime.agentId }, "Registered send handler");
+    } else {
+      logger3.warn({ src: "plugin:telegram", agentId: runtime.agentId }, "Cannot register send handler, bot not initialized");
+    }
+  }
+  async handleSendMessage(runtime, target, content) {
+    if (!this.bot || !this.messageManager) {
+      logger3.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) {
+      logger3.error({ src: "plugin:telegram", agentId: runtime.agentId, entityId: target.entityId }, "Sending DMs via entityId not implemented");
+      throw new Error("Sending DMs via entityId is not yet supported for Telegram.");
+    } 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);
+      logger3.info({ src: "plugin:telegram", agentId: runtime.agentId, chatId }, "Message sent");
+    } catch (error) {
+      logger3.error({ src: "plugin:telegram", agentId: runtime.agentId, chatId, error: error instanceof Error ? error.message : String(error) }, "Error sending message");
+      throw error;
+    }
+  }
+};
+
+// src/tests.ts
+import { logger as logger4 } 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);
+      logger4.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 || !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;
+    logger4.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!");
+      logger4.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
+      );
+      logger4.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: void 0,
+          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 || !result.description) {
+        throw new Error("Error processing Telegram image or description not found");
+      }
+      const { description } = result;
+      logger4.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 || 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) {
+      logger4.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",
+  services: [TelegramService],
+  tests: [new TelegramTestSuite()]
+};
+var index_default = telegramPlugin;
+export {
+  MessageManager,
+  TelegramService,
+  index_default as default
+};
+//# sourceMappingURL=index.js.map