@elizaos/plugin-telegram 1.0.0-beta.7 → 1.0.0

package/dist/index.js

@@ -52,29 +52,126 @@ import {
   createUniqueUuid,
   logger
 } from "@elizaos/core";
+import { Markup as Markup2 } from "telegraf";
 
 // src/utils.ts
-function escapeMarkdown(text) {
-  if (text.startsWith("```") && text.endsWith("```")) {
-    return text;
+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;
   }
-  const parts = text.split(/(```[\s\S]*?```)/g);
-  return parts.map((part, index) => {
-    if (index % 2 === 1) {
-      return part;
+  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);
     }
-    return part.replace(/`.*?`/g, (match) => match).replace(/([*_`\\])/g, "\\$1");
   }).join("");
+  const finalResult = finalEscaped.replace(PLACEHOLDER_REPLACE, (_, index) => {
+    return replacements[parseInt(index)];
+  });
+  return finalResult;
+}
+function convertToTelegramButtons(buttons) {
+  if (!buttons) return [];
+  return buttons.map((button) => {
+    switch (button.kind) {
+      case "login":
+        return Markup.button.login(button.text, button.url);
+      case "url":
+        return Markup.button.url(button.text, button.url);
+    }
+  });
 }
 
 // src/messageManager.ts
 import fs from "node:fs";
 var MAX_MESSAGE_LENGTH = 4096;
 var getChannelType = (chat) => {
-  if (chat.type === "private") return ChannelType.DM;
-  if (chat.type === "supergroup") return ChannelType.GROUP;
-  if (chat.type === "channel") return ChannelType.GROUP;
-  if (chat.type === "group") return ChannelType.GROUP;
+  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;
@@ -97,15 +194,14 @@ var MessageManager = class {
    * @returns {Promise<{ description: string } | null>} The description of the processed image or null if no image found.
    */
   async processImage(message) {
-    var _a, _b, _c;
     try {
       let imageUrl = null;
       logger.info(`Telegram Message: ${message}`);
-      if ("photo" in message && ((_a = message.photo) == null ? void 0 : _a.length) > 0) {
+      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 && ((_c = (_b = message.document) == null ? void 0 : _b.mime_type) == null ? void 0 : _c.startsWith("image/"))) {
+      } else if ("document" in message && message.document?.mime_type?.startsWith("image/")) {
         const fileLink = await this.bot.telegram.getFileLink(message.document.file_id);
         imageUrl = fileLink.toString();
       }
@@ -127,7 +223,7 @@ ${description}]` };
    * 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 {Content} content - The content of the message to be sent
+   * @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
    */
@@ -143,7 +239,7 @@ ${description}]` };
         };
         let mediaType = void 0;
         for (const prefix in typeMap) {
-          if (attachment.contentType.startsWith(prefix)) {
+          if (attachment.contentType?.startsWith(prefix)) {
             mediaType = typeMap[prefix];
             break;
           }
@@ -155,14 +251,26 @@ ${description}]` };
         }
         await this.sendMedia(ctx, attachment.url, mediaType, attachment.description);
       });
+      return [];
     } else {
-      const chunks = this.splitMessage(content.text);
+      const chunks = this.splitMessage(content.text ?? "");
       const sentMessages = [];
+      const telegramButtons = convertToTelegramButtons(content.buttons ?? []);
+      if (!ctx.chat) {
+        logger.error("sendMessageInChunks: ctx.chat is undefined");
+        return [];
+      }
+      await ctx.telegram.sendChatAction(ctx.chat.id, "typing");
       for (let i = 0; i < chunks.length; i++) {
-        const chunk = escapeMarkdown(chunks[i]);
+        const chunk = convertMarkdownToTelegram(chunks[i]);
+        if (!ctx.chat) {
+          logger.error("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: "Markdown"
+          parse_mode: "MarkdownV2",
+          ...Markup2.inlineKeyboard(telegramButtons)
         });
         sentMessages.push(sentMessage);
       }
@@ -193,6 +301,9 @@ ${description}]` };
       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 {
@@ -201,6 +312,9 @@ ${description}]` };
         }
         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();
@@ -210,8 +324,10 @@ ${description}]` };
         `${type.charAt(0).toUpperCase() + type.slice(1)} sent successfully: ${mediaPath}`
       );
     } catch (error) {
-      logger.error(`Failed to send ${type}. Path: ${mediaPath}. Error: ${error.message}`);
-      logger.debug(error.stack);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.error(`Failed to send ${type}. Path: ${mediaPath}. Error: ${errorMessage}`, {
+        originalError: error
+      });
       throw error;
     }
   }
@@ -224,6 +340,7 @@ ${description}]` };
    */
   splitMessage(text) {
     const chunks = [];
+    if (!text) return chunks;
     let currentChunk = "";
     const lines = text.split("\n");
     for (const line of lines) {
@@ -244,14 +361,20 @@ ${description}]` };
    * @returns {Promise<void>}
    */
   async handleMessage(ctx) {
-    var _a, _b, _c, _d, _e, _f;
     if (!ctx.message || !ctx.from) return;
     const message = ctx.message;
     try {
       const entityId = createUniqueUuid(this.runtime, ctx.from.id.toString());
-      const userName = ctx.from.username || ctx.from.first_name || "Unknown User";
-      const roomId = createUniqueUuid(this.runtime, (_a = ctx.chat) == null ? void 0 : _a.id.toString());
-      const messageId = createUniqueUuid(this.runtime, (_b = message == null ? void 0 : message.message_id) == null ? void 0 : _b.toString());
+      const threadId = "is_topic_message" in message && message.is_topic_message ? message.message_thread_id?.toString() : void 0;
+      if (!ctx.chat) {
+        logger.error("handleMessage: ctx.chat is undefined");
+        return;
+      }
+      const roomId = createUniqueUuid(
+        this.runtime,
+        threadId ? `${ctx.chat.id}-${threadId}` : ctx.chat.id.toString()
+      );
+      const messageId = createUniqueUuid(this.runtime, message?.message_id?.toString());
       const imageInfo = await this.processImage(message);
       let messageText = "";
       if ("text" in message && message.text) {
@@ -263,34 +386,6 @@ ${description}]` };
       if (!fullText) return;
       const chat = message.chat;
       const channelType = getChannelType(chat);
-      const worldId = createUniqueUuid(
-        this.runtime,
-        chat.type === "private" ? `private_${chat.id}` : chat.id.toString()
-      );
-      const worldName = chat.type === "supergroup" ? chat.title : chat.type === "channel" ? chat.title : chat.type === "private" ? `Chat with ${chat.first_name || "Unknown"}` : "Telegram";
-      const roomName = chat.type === "private" ? chat.first_name : chat.type === "supergroup" ? chat.title : chat.type === "channel" ? chat.title : chat.type === "group" ? chat.title : "Unknown Group";
-      await this.runtime.ensureConnection({
-        entityId,
-        roomId,
-        userName,
-        name: userName,
-        source: "telegram",
-        channelId: ctx.chat.id.toString(),
-        serverId: chat.type === "private" ? void 0 : chat.id.toString(),
-        // Only set serverId for non-private chats
-        type: channelType,
-        worldId
-      });
-      const room = {
-        id: roomId,
-        name: roomName,
-        source: "telegram",
-        type: channelType,
-        channelId: ctx.chat.id.toString(),
-        serverId: chat.type === "private" ? void 0 : chat.id.toString(),
-        worldId
-      };
-      await this.runtime.ensureRoomExists(room);
       const memory = {
         id: messageId,
         entityId,
@@ -306,6 +401,7 @@ ${description}]` };
       };
       const callback = async (content, _files) => {
         try {
+          if (!content.text) return [];
           const sentMessages = await this.sendMessageInChunks(ctx, content, message.message_id);
           if (!sentMessages) return [];
           const memories = [];
@@ -319,6 +415,7 @@ ${description}]` };
               roomId,
               content: {
                 ...content,
+                source: "telegram",
                 text: sentMessage.text,
                 inReplyTo: messageId,
                 channelType
@@ -351,27 +448,33 @@ ${description}]` };
     } catch (error) {
       logger.error("Error handling Telegram message:", {
         error,
-        chatId: (_c = ctx.chat) == null ? void 0 : _c.id,
-        messageId: (_d = ctx.message) == null ? void 0 : _d.message_id,
-        from: ((_e = ctx.from) == null ? void 0 : _e.username) || ((_f = ctx.from) == null ? void 0 : _f.id)
+        chatId: ctx.chat?.id,
+        messageId: ctx.message?.message_id,
+        from: ctx.from?.username || ctx.from?.id
       });
       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
+   * @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 worldId = createUniqueUuid(this.runtime, ctx.chat.id.toString());
       const reactionId = createUniqueUuid(
         this.runtime,
         `${reaction.message_id}-${ctx.from.id}-${Date.now()}`
@@ -391,7 +494,8 @@ ${description}]` };
       };
       const callback = async (content) => {
         try {
-          const sentMessage = await ctx.reply(content.text);
+          const replyText = content.text ?? "";
+          const sentMessage = await ctx.reply(replyText);
           const responseMemory = {
             id: createUniqueUuid(this.runtime, sentMessage.message_id.toString()),
             entityId: this.runtime.agentId,
@@ -413,7 +517,12 @@ ${description}]` };
         runtime: this.runtime,
         message: memory,
         callback,
-        source: "telegram"
+        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,
@@ -421,11 +530,14 @@ ${description}]` };
         callback,
         source: "telegram",
         ctx,
+        originalMessage: originalMessagePlaceholder,
+        // Cast needed due to placeholder
         reactionString: reactionType === "emoji" ? reactionEmoji : reactionType,
         originalReaction: reaction.new_reaction[0]
       });
     } catch (error) {
-      logger.error("Error handling reaction:", error);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.error("Error handling reaction:", { error: errorMessage, originalError: error });
     }
   }
   /**
@@ -446,7 +558,7 @@ ${description}]` };
         content,
         replyToMessageId
       );
-      if (!(sentMessages == null ? void 0 : sentMessages.length)) return [];
+      if (!sentMessages?.length) return [];
       const roomId = createUniqueUuid(this.runtime, chatId.toString());
       const memories = [];
       for (const sentMessage of sentMessages) {
@@ -472,7 +584,9 @@ ${description}]` };
       }
       this.runtime.emitEvent(EventType.MESSAGE_SENT, {
         runtime: this.runtime,
-        messages: memories,
+        message: {
+          content
+        },
         roomId,
         source: "telegram"
       });
@@ -482,7 +596,11 @@ ${description}]` };
       });
       return sentMessages;
     } catch (error) {
-      logger.error("Error sending message to Telegram:", error);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.error("Error sending message to Telegram:", {
+        error: errorMessage,
+        originalError: error
+      });
       return [];
     }
   }
@@ -496,6 +614,7 @@ var TelegramService = class _TelegramService extends Service {
   messageManager;
   options;
   knownChats = /* @__PURE__ */ new Map();
+  syncedEntityIds = /* @__PURE__ */ new Set();
   /**
    * Constructor for TelegramService class.
    * @param {IAgentRuntime} runtime - The runtime object for the agent.
@@ -532,6 +651,7 @@ var TelegramService = class _TelegramService extends Service {
         );
         logger2.log("\u{1F680} Starting Telegram bot...");
         await service.initializeBot();
+        service.setupMiddlewares();
         service.setupMessageHandlers();
         await service.bot.telegram.getMe();
         return service;
@@ -549,7 +669,7 @@ var TelegramService = class _TelegramService extends Service {
       }
     }
     throw new Error(
-      `Telegram initialization failed after ${maxRetries} attempts. Last error: ${lastError == null ? void 0 : lastError.message}`
+      `Telegram initialization failed after ${maxRetries} attempts. Last error: ${lastError?.message}`
     );
   }
   /**
@@ -584,18 +704,113 @@ var TelegramService = class _TelegramService extends Service {
     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)) {
+      logger2.debug("Chat not authorized, skipping message processing");
+      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) {
+        logger2.error(`Error handling forum topic: ${error}`);
+      }
+    }
+    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) {
+        logger2.error("Error handling message:", error);
+      }
+    });
+    this.bot.on("message_reaction", async (ctx) => {
+      try {
+        await this.messageManager.handleReaction(ctx);
+      } catch (error) {
+        logger2.error("Error handling reaction:", error);
+      }
+    });
+  }
   /**
    * 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) {
-    var _a;
-    const chatId = (_a = ctx.chat) == null ? void 0 : _a.id.toString();
+    const chatId = ctx.chat?.id.toString();
     if (!chatId) return false;
-    if (!this.knownChats.has(chatId)) {
-      await this.handleNewChat(ctx);
-    }
     const allowedChats = this.runtime.getSetting("TELEGRAM_ALLOWED_CHATS");
     if (!allowedChats) {
       return true;
@@ -609,39 +824,199 @@ var TelegramService = class _TelegramService extends Service {
     }
   }
   /**
-   * Handles new chat discovery and emits WORLD_JOINED event
+   * 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,
+        serverId: 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,
+        serverId: chatId,
+        type: ChannelType2.GROUP,
+        worldId
+      });
+      this.syncedEntityIds.add(entityId);
+      this.runtime.emitEvent(["TELEGRAM_ENTITY_JOINED" /* ENTITY_JOINED */], {
+        runtime: this.runtime,
+        entityId,
+        worldId,
+        newMember,
+        ctx
+      });
+    }
+  }
+  /**
+   * 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);
-    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;
-    }
+    const { chatTitle, channelType } = this.getChatTypeInfo(chat);
     const worldId = createUniqueUuid2(this.runtime, chatId);
-    const roomId = 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) {
+        logger2.warn(
+          `Could not get chat administrators: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    let ownerId = userId;
+    if (owner) {
+      ownerId = createUniqueUuid2(this.runtime, String(owner.user.id));
+    }
     const world = {
       id: worldId,
       name: chatTitle,
@@ -649,14 +1024,17 @@ var TelegramService = class _TelegramService extends Service {
       serverId: chatId,
       metadata: {
         source: "telegram",
-        ownership: { ownerId: chatId },
-        roles: {
-          [chatId]: Role.OWNER
-        }
+        ...ownerId && { ownership: { ownerId } },
+        roles: ownerId ? {
+          [ownerId]: Role.OWNER
+        } : {},
+        chatType: chat.type,
+        isForumEnabled: chat.type === "supergroup" && chat.is_forum
       }
     };
-    const room = {
-      id: roomId,
+    await this.runtime.ensureWorldExists(world);
+    const generalRoom = {
+      id: createUniqueUuid2(this.runtime, chatId),
       name: chatTitle,
       source: "telegram",
       type: channelType,
@@ -664,204 +1042,289 @@ var TelegramService = class _TelegramService extends Service {
       serverId: chatId,
       worldId
     };
-    const users = [];
-    if (chat.type === "private" && chat.id) {
-      const userId = createUniqueUuid2(this.runtime, chat.id.toString());
-      users.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"
-        }
-      });
-    } 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());
-            users.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]
-              }
-            });
-          }
-        }
-        try {
-          const chatInfo = await this.bot.telegram.getChat(chat.id);
-          if (chatInfo && "member_count" in chatInfo) {
-            world.metadata.memberCount = chatInfo.member_count;
-          }
-        } catch (countError) {
-          logger2.warn(`Could not get member count for chat ${chatId}: ${countError}`);
-        }
-      } catch (error) {
-        logger2.warn(`Could not fetch administrators for chat ${chatId}: ${error}`);
+    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 worldPayload = {
+    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.serverId,
+      generalRoom.type,
+      worldId
+    );
+    const telegramWorldPayload = {
       runtime: this.runtime,
       world,
-      rooms: [room],
-      entities: users,
-      source: "telegram"
-    };
-    const telegramWorldPayload = {
-      ...worldPayload,
-      chat
+      rooms,
+      entities,
+      source: "telegram",
+      chat,
+      botUsername: this.bot.botInfo.username
     };
-    this.runtime.emitEvent(EventType2.WORLD_JOINED, worldPayload);
-    this.runtime.emitEvent("TELEGRAM_WORLD_JOINED" /* WORLD_JOINED */, telegramWorldPayload);
-    if (chat.type === "group" || chat.type === "supergroup") {
-      this.setupEntityTracking(chat.id);
+    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"
+    });
   }
   /**
-   * Sets up message and reaction handlers for the bot.
+   * 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 {string} serverId - The server ID
+   * @param {ChannelType} roomType - The type of the room
+   * @param {UUID} worldId - The ID of the world
+   * @returns {Promise<void>}
    * @private
-   * @returns {void}
    */
-  setupMessageHandlers() {
-    this.bot.on("message", async (ctx) => {
-      try {
-        if (!await this.isGroupAuthorized(ctx)) return;
-        await this.messageManager.handleMessage(ctx);
-      } catch (error) {
-        logger2.error("Error handling message:", error);
-      }
-    });
-    this.bot.on("message_reaction", async (ctx) => {
-      try {
-        if (!await this.isGroupAuthorized(ctx)) return;
-        await this.messageManager.handleReaction(ctx);
-      } catch (error) {
-        logger2.error("Error handling reaction:", error);
+  async batchProcessEntities(entities, roomId, channelId, serverId, 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) {
+              await this.runtime.ensureConnection({
+                entityId: entity.id,
+                roomId,
+                userName: entity.metadata?.telegram?.username,
+                name: entity.metadata?.telegram?.name,
+                userId: entity.metadata?.telegram?.id,
+                source: "telegram",
+                channelId,
+                serverId,
+                type: roomType,
+                worldId
+              });
+            } else {
+              logger2.warn(
+                `Skipping entity sync due to missing ID: ${JSON.stringify(entity.names)}`
+              );
+            }
+          } catch (err) {
+            logger2.warn(`Failed to sync user ${entity.metadata?.telegram?.username}: ${err}`);
+          }
+        })
+      );
+      if (i + batchSize < entities.length) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
       }
-    });
+    }
   }
   /**
-   * Sets up tracking for new entities in a group chat to sync them as entities
-   * @param {number} chatId - The Telegram chat ID to track entities for
+   * 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
    */
-  setupEntityTracking(chatId) {
-    const syncedEntityIds = /* @__PURE__ */ new Set();
-    this.bot.on("message", async (ctx) => {
-      if (!ctx.chat || ctx.chat.id !== chatId || !ctx.from) return;
-      const entityId = ctx.from.id.toString();
-      if (syncedEntityIds.has(entityId)) return;
-      syncedEntityIds.add(entityId);
-      const entityUuid = createUniqueUuid2(this.runtime, entityId);
-      const worldId = createUniqueUuid2(this.runtime, chatId.toString());
-      const chatIdStr = chatId.toString();
-      try {
-        await this.runtime.ensureConnection({
-          entityId: entityUuid,
-          roomId: createUniqueUuid2(this.runtime, chatIdStr),
-          userName: ctx.from.username || ctx.from.first_name || "Unknown Entity",
-          name: ctx.from.first_name || ctx.from.username || "Unknown Entity",
-          source: "telegram",
-          channelId: chatIdStr,
-          serverId: chatIdStr,
-          type: ChannelType2.GROUP,
-          worldId
-        });
-        const entityJoinedPayload = {
-          runtime: this.runtime,
-          entityId: entityUuid,
-          entity: {
-            id: entityId,
-            username: ctx.from.username || ctx.from.first_name || "Unknown Entity",
-            displayName: ctx.from.first_name || ctx.from.username || "Unknown Entity"
-          },
-          worldId,
-          source: "telegram",
+  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: {
-            joinedAt: Date.now()
+            telegram: {
+              id: chat.id.toString(),
+              username: chat.username || "unknown",
+              name: chat.first_name || "Unknown User"
+            },
+            source: "telegram"
           }
-        };
-        const telegramEntityJoinedPayload = {
-          ...entityJoinedPayload,
-          telegramUser: {
-            id: ctx.from.id,
-            username: ctx.from.username,
-            first_name: ctx.from.first_name
+        });
+        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);
+            }
           }
-        };
-        this.runtime.emitEvent(EventType2.ENTITY_JOINED, entityJoinedPayload);
-        this.runtime.emitEvent("TELEGRAM_ENTITY_JOINED" /* ENTITY_JOINED */, telegramEntityJoinedPayload);
-        logger2.info(
-          `Tracked new Telegram entity: ${ctx.from.username || ctx.from.first_name || entityId}`
-        );
-      } catch (error) {
-        logger2.error(`Error syncing new Telegram entity ${entityId} from chat ${chatId}:`, error);
+        } catch (error) {
+          logger2.warn(`Could not fetch administrators for chat ${chat.id}: ${error}`);
+        }
       }
-    });
-    this.bot.on("left_chat_member", async (ctx) => {
-      var _a, _b;
-      if (!((_a = ctx.message) == null ? void 0 : _a.left_chat_member) || ((_b = ctx.chat) == null ? void 0 : _b.id) !== chatId) return;
-      const leftUser = ctx.message.left_chat_member;
-      const entityId = createUniqueUuid2(this.runtime, leftUser.id.toString());
-      const chatIdStr = chatId.toString();
-      const worldId = createUniqueUuid2(this.runtime, chatIdStr);
-      try {
-        const entity = await this.runtime.getEntityById(entityId);
-        if (entity) {
-          entity.metadata = {
-            ...entity.metadata,
-            status: "INACTIVE",
-            leftAt: Date.now()
-          };
-          await this.runtime.updateEntity(entity);
-          const entityLeftPayload = {
-            runtime: this.runtime,
-            entityId,
-            entity: {
-              id: leftUser.id.toString(),
-              username: leftUser.username || leftUser.first_name || "Unknown Entity",
-              displayName: leftUser.first_name || leftUser.username || "Unknown Entity"
-            },
-            worldId,
-            source: "telegram",
-            metadata: {
-              leftAt: Date.now()
-            }
-          };
-          const telegramEntityLeftPayload = {
-            ...entityLeftPayload,
-            telegramUser: {
-              id: leftUser.id,
-              username: leftUser.username,
-              first_name: leftUser.first_name
-            }
-          };
-          this.runtime.emitEvent(EventType2.ENTITY_LEFT, entityLeftPayload);
-          this.runtime.emitEvent("TELEGRAM_ENTITY_LEFT" /* ENTITY_LEFT */, telegramEntityLeftPayload);
-          logger2.info(
-            `Entity ${leftUser.username || leftUser.first_name || leftUser.id} left chat ${chatId}`
-          );
+    } catch (error) {
+      logger2.error(
+        `Error building standardized entities: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    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;
         }
-      } catch (error) {
-        logger2.error(`Error handling Telegram entity leaving chat ${chatId}:`, error);
       }
-    });
+      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) {
+      logger2.error(
+        `Error building forum topic room: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return null;
+    }
+  }
+  static registerSendHandlers(runtime, serviceInstance) {
+    if (serviceInstance) {
+      runtime.registerSendHandler(
+        "telegram",
+        serviceInstance.handleSendMessage.bind(serviceInstance)
+      );
+      logger2.info("[Telegram] Registered send handler.");
+    }
+  }
+  async handleSendMessage(runtime, target, content) {
+    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) {
+      logger2.error("[Telegram SendHandler] Sending DMs via entityId not implemented yet.");
+      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);
+      logger2.info(`[Telegram SendHandler] Message sent to chat ID: ${chatId}`);
+    } catch (error) {
+      logger2.error(
+        `[Telegram SendHandler] Error sending message: ${error instanceof Error ? error.message : String(error)}`,
+        {
+          target,
+          content
+        }
+      );
+      throw error;
+    }
   }
 };
 
@@ -931,6 +1394,9 @@ var TelegramTestSuite = class {
   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);
       logger3.log(`Fetched real chat: ${JSON.stringify(chat)}`);
       return chat;
@@ -957,6 +1423,7 @@ var TelegramTestSuite = class {
   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,
@@ -984,8 +1451,9 @@ var TelegramTestSuite = class {
     }
   }
   async testHandlingMessage(runtime) {
-    var _a;
     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,
@@ -998,7 +1466,7 @@ var TelegramTestSuite = class {
         },
         message: {
           message_id: void 0,
-          text: `@${(_a = this.bot.botInfo) == null ? void 0 : _a.username}! Hello!`,
+          text: `@${this.bot.botInfo?.username}! Hello!`,
           date: Math.floor(Date.now() / 1e3),
           chat
         },
@@ -1014,21 +1482,30 @@ var TelegramTestSuite = class {
     }
   }
   async testProcessingImages(runtime) {
-    var _a;
     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(chatId, TEST_IMAGE_URL);
       const mockMessage = {
-        message_id: void 0,
-        chat: { id: chatId },
+        message_id: 12345,
+        chat: { id: chatId, type: "private" },
         date: Math.floor(Date.now() / 1e3),
-        photo: [{ file_id: fileId }],
-        text: `@${(_a = this.bot.botInfo) == null ? void 0 : _a.username}!`
+        photo: [
+          {
+            file_id: fileId,
+            file_unique_id: `unique_${fileId}`,
+            width: 100,
+            height: 100
+          }
+        ],
+        text: `@${this.bot.botInfo?.username}!`
       };
-      const { description } = await this.messageManager.processImage(mockMessage);
-      if (!description) {
-        throw new Error("Error processing Telegram image");
+      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;
       logger3.log(`Processing Telegram image successfully: ${description}`);
     } catch (error) {
       throw new Error(`Error processing Telegram image: ${error}`);
@@ -1036,7 +1513,13 @@ var TelegramTestSuite = class {
   }
   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) {
       logger3.error(`Error sending image: ${error}`);
@@ -1054,6 +1537,8 @@ var telegramPlugin = {
 };
 var index_default = telegramPlugin;
 export {
+  MessageManager,
+  TelegramService,
   index_default as default
 };
 //# sourceMappingURL=index.js.map