@elizaos/plugin-telegram 1.0.4 → 1.0.9

package/dist/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const MESSAGE_CONSTANTS: {
+    readonly MAX_MESSAGES: 50;
+    readonly RECENT_MESSAGE_COUNT: 5;
+    readonly CHAT_HISTORY_COUNT: 10;
+    readonly DEFAULT_SIMILARITY_THRESHOLD: 0.6;
+    readonly DEFAULT_SIMILARITY_THRESHOLD_FOLLOW_UPS: 0.4;
+    readonly INTEREST_DECAY_TIME: number;
+    readonly PARTIAL_INTEREST_DECAY: number;
+};
+export declare const TELEGRAM_SERVICE_NAME = "telegram";

package/dist/environment.d.ts

@@ -0,0 +1,21 @@
+import type { IAgentRuntime } from '@elizaos/core';
+import { z } from 'zod';
+export declare const telegramEnvSchema: z.ZodObject<{
+    TELEGRAM_BOT_TOKEN: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    TELEGRAM_BOT_TOKEN: string;
+}, {
+    TELEGRAM_BOT_TOKEN: string;
+}>;
+/**
+ * Represents the type definition for configuring a Telegram bot based on the inferred schema.
+ */
+export type TelegramConfig = z.infer<typeof telegramEnvSchema>;
+/**
+ * Validates the Telegram configuration by retrieving the Telegram bot token from the runtime settings or environment variables.
+ * Returns null if validation fails instead of throwing an error.
+ *
+ * @param {IAgentRuntime} runtime - The agent runtime used to get the setting.
+ * @returns {Promise<TelegramConfig | null>} A promise that resolves with the validated Telegram configuration or null if invalid.
+ */
+export declare function validateTelegramConfig(runtime: IAgentRuntime): Promise<TelegramConfig | null>;

package/dist/index.d.ts

@@ -1,328 +1,6 @@
-import { Content, IAgentRuntime, Service, TargetInfo, Plugin } from '@elizaos/core';
-import { Message, Update } from '@telegraf/types';
-import { Telegraf, Context, NarrowedContext } from 'telegraf';
-
-/**
- * Extention of the core Content type just for Telegram
- */
-interface TelegramContent extends Content {
-    /** Array of buttons */
-    buttons?: Button[];
-}
-/**
- * Represents a flexible button configuration
- */
-type Button = {
-    /** The type of button */
-    kind: 'login' | 'url';
-    /** The text to display on the button */
-    text: string;
-    /** The URL or endpoint the button should link to */
-    url: string;
-};
-
-/**
- * Enum representing different types of media.
- * @enum { string }
- * @readonly
- */
-declare enum MediaType {
-    PHOTO = "photo",
-    VIDEO = "video",
-    DOCUMENT = "document",
-    AUDIO = "audio",
-    ANIMATION = "animation"
-}
-/**
- * Class representing a message manager.
- * @class
- */
-declare class MessageManager {
-    bot: Telegraf<Context>;
-    protected runtime: IAgentRuntime;
-    /**
-     * 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: Telegraf<Context>, runtime: IAgentRuntime);
-    /**
-     * 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.
-     */
-    processImage(message: Message): Promise<{
-        description: string;
-    } | null>;
-    /**
-     * 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
-     */
-    sendMessageInChunks(ctx: Context, content: TelegramContent, replyToMessageId?: number): Promise<Message.TextMessage[]>;
-    /**
-     * 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.
-     */
-    sendMedia(ctx: Context, mediaPath: string, type: MediaType, caption?: string): Promise<void>;
-    /**
-     * 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.
-     */
-    private splitMessage;
-    /**
-     * Handle incoming messages from Telegram and process them accordingly.
-     * @param {Context} ctx - The context object containing information about the message.
-     * @returns {Promise<void>}
-     */
-    handleMessage(ctx: Context): Promise<void>;
-    /**
-     * 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
-     */
-    handleReaction(ctx: NarrowedContext<Context<Update>, Update.MessageReactionUpdate>): Promise<void>;
-    /**
-     * 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
-     */
-    sendMessage(chatId: number | string, content: Content, replyToMessageId?: number): Promise<Message.TextMessage[]>;
-}
-
-/**
- * Class representing a Telegram service that allows the agent to send and receive messages on Telegram.
- * This service handles all Telegram-specific functionality including:
- * - Initializing and managing the Telegram bot
- * - Setting up middleware for preprocessing messages
- * - Handling message and reaction events
- * - Synchronizing Telegram chats, users, and entities with the agent runtime
- * - Managing forum topics as separate rooms
- *
- * @extends Service
- */
-declare class TelegramService extends Service {
-    static serviceType: string;
-    capabilityDescription: string;
-    private bot;
-    messageManager: MessageManager;
-    private options;
-    private knownChats;
-    private syncedEntityIds;
-    /**
-     * Constructor for TelegramService class.
-     * @param {IAgentRuntime} runtime - The runtime object for the agent.
-     */
-    constructor(runtime: IAgentRuntime);
-    /**
-     * 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 start(runtime: IAgentRuntime): Promise<TelegramService>;
-    /**
-     * Stops the agent runtime.
-     * @param {IAgentRuntime} runtime - The agent runtime to stop
-     */
-    static stop(runtime: IAgentRuntime): Promise<void>;
-    /**
-     * Asynchronously stops the bot.
-     *
-     * @returns A Promise that resolves once the bot has stopped.
-     */
-    stop(): Promise<void>;
-    /**
-     * 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.
-     */
-    private initializeBot;
-    /**
-     * 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
-     */
-    private setupMiddlewares;
-    /**
-     * 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
-     */
-    private authorizationMiddleware;
-    /**
-     * 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
-     */
-    private chatAndEntityMiddleware;
-    /**
-     * 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
-     */
-    private processExistingChat;
-    /**
-     * Sets up message and reaction handlers for the bot.
-     * Configures event handlers to process incoming messages and reactions.
-     *
-     * @private
-     */
-    private setupMessageHandlers;
-    /**
-     * 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.
-     */
-    private isGroupAuthorized;
-    /**
-     * 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
-     */
-    private syncEntity;
-    /**
-     * 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
-     */
-    private syncMessageSender;
-    /**
-     * 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
-     */
-    private syncNewChatMember;
-    /**
-     * Updates entity status when a user leaves the chat.
-     *
-     * @param {Context} ctx - The context of the incoming update
-     * @returns {Promise<void>}
-     * @private
-     */
-    private syncLeftChatMember;
-    /**
-     * 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
-     */
-    private handleForumTopic;
-    /**
-     * Builds entity for message sender
-     */
-    private buildMsgSenderEntity;
-    /**
-     * 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
-     */
-    private handleNewChat;
-    /**
-     * 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
-     */
-    private batchProcessEntities;
-    /**
-     * 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
-     */
-    private getChatTypeInfo;
-    /**
-     * 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
-     */
-    private buildStandardizedEntities;
-    /**
-     * 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
-     */
-    private buildForumTopicRoom;
-    static registerSendHandlers(runtime: IAgentRuntime, serviceInstance: TelegramService): void;
-    handleSendMessage(runtime: IAgentRuntime, target: TargetInfo, content: Content): Promise<void>;
-}
-
+import type { Plugin } from '@elizaos/core';
+import { TelegramService } from './service';
+import { MessageManager } from './messageManager';
 declare const telegramPlugin: Plugin;
-
-export { MessageManager, TelegramService, telegramPlugin as default };
+export { TelegramService, MessageManager };
+export default telegramPlugin;

package/dist/index.js

@@ -23,27 +23,6 @@ import {
 } from "@elizaos/core";
 import { Telegraf } from "telegraf";
 
-// src/environment.ts
-import { z } from "zod";
-var telegramEnvSchema = z.object({
-  TELEGRAM_BOT_TOKEN: z.string().min(1, "Telegram bot token is required")
-});
-async function validateTelegramConfig(runtime) {
-  try {
-    const config = {
-      TELEGRAM_BOT_TOKEN: runtime.getSetting("TELEGRAM_BOT_TOKEN") || process.env.TELEGRAM_BOT_TOKEN
-    };
-    return telegramEnvSchema.parse(config);
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      const errorMessages = error.errors.map((err) => `${err.path.join(".")}: ${err.message}`).join("\n");
-      throw new Error(`Telegram configuration validation failed:
-${errorMessages}`);
-    }
-    throw error;
-  }
-}
-
 // src/messageManager.ts
 import {
   ChannelType,
@@ -87,46 +66,46 @@ function convertMarkdownToTelegram(markdown) {
     return placeholder;
   }
   let converted = markdown;
-  converted = converted.replace(/```(\w+)?\n([\s\S]*?)```/g, (match, lang, code) => {
+  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) => {
+  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) => {
+    (_match, text, url) => {
       const formattedText = escapePlainText(text);
       const escapedURL = escapeUrl(url);
       const formatted = `[${formattedText}](${escapedURL})`;
       return storeReplacement(formatted);
     }
   );
-  converted = converted.replace(/\*\*([^*]+)\*\*/g, (match, content) => {
+  converted = converted.replace(/\*\*([^*]+)\*\*/g, (_match, content) => {
     const formattedContent = escapePlainText(content);
     const formatted = `*${formattedContent}*`;
     return storeReplacement(formatted);
   });
-  converted = converted.replace(/~~([^~]+)~~/g, (match, content) => {
+  converted = converted.replace(/~~([^~]+)~~/g, (_match, content) => {
     const formattedContent = escapePlainText(content);
     const formatted = `~${formattedContent}~`;
     return storeReplacement(formatted);
   });
-  converted = converted.replace(/(?<!\*)\*([^*\n]+)\*(?!\*)/g, (match, content) => {
+  converted = converted.replace(/(?<!\*)\*([^*\n]+)\*(?!\*)/g, (_match, content) => {
     const formattedContent = escapePlainText(content);
     const formatted = `_${formattedContent}_`;
     return storeReplacement(formatted);
   });
-  converted = converted.replace(/_([^_\n]+)_/g, (match, content) => {
+  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) => {
+  converted = converted.replace(/^(#{1,6})\s*(.*)$/gm, (_match, _hashes, headerContent) => {
     const formatted = `*${escapePlainText(headerContent.trim())}*`;
     return storeReplacement(formatted);
   });
@@ -384,6 +363,7 @@ ${description}]` };
       if (!fullText) return;
       const chat = message.chat;
       const channelType = getChannelType(chat);
+      const sourceId = createUniqueUuid(this.runtime, "" + chat.id);
       await this.runtime.ensureConnection({
         entityId,
         roomId,
@@ -405,6 +385,7 @@ ${description}]` };
           text: fullText,
           // attachments?
           source: "telegram",
+          // url?
           channelType,
           inReplyTo: "reply_to_message" in message && message.reply_to_message ? createUniqueUuid(this.runtime, message.reply_to_message.message_id.toString()) : void 0
         },
@@ -415,9 +396,12 @@ ${description}]` };
           // 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?
+          // what are the other types? see MemoryType
           type: "message"
+          // MemoryType.MESSAGE
+          // scope: `shared`, `private`, or `room`
         },
         createdAt: message.date * 1e3
       };
@@ -425,7 +409,7 @@ ${description}]` };
         try {
           if (!content.text) return [];
           let sentMessages = false;
-          if (content?.target === "DM") {
+          if (content?.channelType === "DM") {
             sentMessages = [];
             if (ctx.from) {
               const res = await this.bot.telegram.sendMessage(ctx.from.id, content.text);
@@ -438,7 +422,6 @@ ${description}]` };
           const memories = [];
           for (let i = 0; i < sentMessages.length; i++) {
             const sentMessage = sentMessages[i];
-            const _isLastMessage = i === sentMessages.length - 1;
             const responseMemory = {
               id: createUniqueUuid(this.runtime, sentMessage.message_id.toString()),
               entityId: this.runtime.agentId,
@@ -653,15 +636,27 @@ var TelegramService = class _TelegramService extends Service {
   constructor(runtime) {
     super(runtime);
     logger2.log("\u{1F4F1} Constructing new TelegramService...");
+    const botToken = runtime.getSetting("TELEGRAM_BOT_TOKEN");
+    if (!botToken || botToken.trim() === "") {
+      logger2.warn("Telegram Bot Token not provided - Telegram functionality will be 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"
       }
     };
-    const botToken = runtime.getSetting("TELEGRAM_BOT_TOKEN");
-    this.bot = new Telegraf(botToken, this.options);
-    this.messageManager = new MessageManager(this.bot, this.runtime);
-    logger2.log("\u2705 TelegramService constructor completed");
+    try {
+      this.bot = new Telegraf(botToken, this.options);
+      this.messageManager = new MessageManager(this.bot, this.runtime);
+      logger2.log("\u2705 TelegramService constructor completed");
+    } catch (error) {
+      logger2.error(`Error initializing Telegram bot: ${error instanceof Error ? error.message : String(error)}`);
+      this.bot = null;
+      this.messageManager = null;
+    }
   }
   /**
    * Starts the Telegram service for the given runtime.
@@ -670,13 +665,16 @@ var TelegramService = class _TelegramService extends Service {
    * @returns {Promise<TelegramService>} A promise that resolves with the initialized TelegramService.
    */
   static async start(runtime) {
-    await validateTelegramConfig(runtime);
+    const service = new _TelegramService(runtime);
+    if (!service.bot) {
+      logger2.warn("Telegram service started without bot functionality - no bot token provided");
+      return service;
+    }
     const maxRetries = 5;
     let retryCount = 0;
     let lastError = null;
     while (retryCount < maxRetries) {
       try {
-        const service = new _TelegramService(runtime);
         logger2.success(
           `\u2705 Telegram client successfully started for character ${runtime.character.name}`
         );
@@ -699,9 +697,10 @@ var TelegramService = class _TelegramService extends Service {
         }
       }
     }
-    throw new Error(
-      `Telegram initialization failed after ${maxRetries} attempts. Last error: ${lastError?.message}`
+    logger2.error(
+      `Telegram initialization failed after ${maxRetries} attempts. Last error: ${lastError?.message}. Service will continue without Telegram functionality.`
     );
+    return service;
   }
   /**
    * Stops the agent runtime.
@@ -719,21 +718,27 @@ var TelegramService = class _TelegramService extends Service {
    * @returns A Promise that resolves once the bot has stopped.
    */
   async stop() {
-    this.bot.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.launch({
+    this.bot?.start((ctx) => {
+      this.runtime.emitEvent(["TELEGRAM_SLASH_START" /* SLASH_START */], {
+        // we don't need this
+        ctx
+      });
+    });
+    this.bot?.launch({
       dropPendingUpdates: true,
       allowedUpdates: ["message", "message_reaction"]
     });
     const botInfo = await this.bot.telegram.getMe();
     logger2.log(`Bot info: ${JSON.stringify(botInfo)}`);
-    process.once("SIGINT", () => this.bot.stop("SIGINT"));
-    process.once("SIGTERM", () => this.bot.stop("SIGTERM"));
+    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.
@@ -751,8 +756,8 @@ var TelegramService = class _TelegramService extends Service {
    * @private
    */
   setupMiddlewares() {
-    this.bot.use(this.authorizationMiddleware.bind(this));
-    this.bot.use(this.chatAndEntityMiddleware.bind(this));
+    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
@@ -819,14 +824,14 @@ var TelegramService = class _TelegramService extends Service {
    * @private
    */
   setupMessageHandlers() {
-    this.bot.on("message", async (ctx) => {
+    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) => {
+    this.bot?.on("message_reaction", async (ctx) => {
       try {
         await this.messageManager.handleReaction(ctx);
       } catch (error) {
@@ -1105,7 +1110,7 @@ var TelegramService = class _TelegramService extends Service {
       entities,
       source: "telegram",
       chat,
-      botUsername: this.bot.botInfo.username
+      botUsername: this.bot?.botInfo?.username
     };
     if (chat.type !== "private") {
       await this.runtime.emitEvent("TELEGRAM_WORLD_JOINED" /* WORLD_JOINED */, telegramWorldPayload);
@@ -1230,7 +1235,7 @@ var TelegramService = class _TelegramService extends Service {
         this.syncedEntityIds.add(userId);
       } else if (chat.type === "group" || chat.type === "supergroup") {
         try {
-          const admins = await this.bot.telegram.getChatAdministrators(chat.id);
+          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());
@@ -1317,15 +1322,21 @@ var TelegramService = class _TelegramService extends Service {
     }
   }
   static registerSendHandlers(runtime, serviceInstance) {
-    if (serviceInstance) {
+    if (serviceInstance && serviceInstance.bot) {
       runtime.registerSendHandler(
         "telegram",
         serviceInstance.handleSendMessage.bind(serviceInstance)
       );
       logger2.info("[Telegram] Registered send handler.");
+    } else {
+      logger2.warn("[Telegram] Cannot register send handler - bot not initialized.");
     }
   }
   async handleSendMessage(runtime, target, content) {
+    if (!this.bot || !this.messageManager) {
+      logger2.error("[Telegram SendHandler] 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;
@@ -1439,6 +1450,9 @@ var TelegramTestSuite = class {
   }
   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;
     logger3.debug("Telegram bot initialized successfully.");