@elizaos/plugin-telegram 1.0.4 → 1.0.9

package/dist/service.d.ts

@@ -0,0 +1,219 @@
+import { type Content, type IAgentRuntime, Service, type TargetInfo } from '@elizaos/core';
+import { MessageManager } from './messageManager';
+/**
+ * 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
+ */
+export declare class TelegramService extends Service {
+    static serviceType: string;
+    capabilityDescription: string;
+    private bot;
+    messageManager: MessageManager | null;
+    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>;
+}

package/dist/tests.d.ts

@@ -0,0 +1,52 @@
+import { type IAgentRuntime, type TestSuite } from '@elizaos/core';
+import type { Context } from 'telegraf';
+/**
+ * Represents a test suite for testing Telegram functionality.
+ *
+ * This test suite includes methods to initialize and validate a Telegram bot connection,
+ * send basic text messages to a Telegram chat, send text messages with image attachments,
+ * handle and process incoming Telegram messages, and process and validate image attachments
+ * in incoming messages.
+ *
+ * @implements {TestSuite}
+ */
+export declare class TelegramTestSuite implements TestSuite {
+    name: string;
+    private telegramClient;
+    private bot;
+    private messageManager;
+    tests: {
+        name: string;
+        fn: (runtime: IAgentRuntime) => Promise<void>;
+    }[];
+    /**
+     * 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();
+    /**
+     * 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: IAgentRuntime): any;
+    getChatInfo(runtime: IAgentRuntime): Promise<Context['chat']>;
+    testCreatingTelegramBot(runtime: IAgentRuntime): Promise<void>;
+    testSendingTextMessage(runtime: IAgentRuntime): Promise<void>;
+    testSendingMessageWithAttachment(runtime: IAgentRuntime): Promise<void>;
+    testHandlingMessage(runtime: IAgentRuntime): Promise<void>;
+    testProcessingImages(runtime: IAgentRuntime): Promise<void>;
+    getFileId(chatId: string, imageUrl: string): Promise<string>;
+}

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+import type { Content, EntityPayload, MessagePayload, WorldPayload } from '@elizaos/core';
+import type { Chat, Message, ReactionType } from '@telegraf/types';
+import type { Context } from 'telegraf';
+/**
+ * Extention of the core Content type just for Telegram
+ */
+export interface TelegramContent extends Content {
+    /** Array of buttons */
+    buttons?: Button[];
+}
+/**
+ * Represents a flexible button configuration
+ */
+export 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;
+};
+/**
+ * Telegram-specific event types
+ */
+export declare enum TelegramEventTypes {
+    WORLD_JOINED = "TELEGRAM_WORLD_JOINED",
+    WORLD_CONNECTED = "TELEGRAM_WORLD_CONNECTED",
+    WORLD_LEFT = "TELEGRAM_WORLD_LEFT",
+    ENTITY_JOINED = "TELEGRAM_ENTITY_JOINED",
+    ENTITY_LEFT = "TELEGRAM_ENTITY_LEFT",
+    ENTITY_UPDATED = "TELEGRAM_ENTITY_UPDATED",
+    MESSAGE_RECEIVED = "TELEGRAM_MESSAGE_RECEIVED",
+    MESSAGE_SENT = "TELEGRAM_MESSAGE_SENT",
+    REACTION_RECEIVED = "TELEGRAM_REACTION_RECEIVED",
+    INTERACTION_RECEIVED = "TELEGRAM_INTERACTION_RECEIVED",
+    SLASH_START = "TELEGRAM_SLASH_START"
+}
+/**
+ * Telegram-specific event payload map
+ */
+export interface TelegramEventPayloadMap {
+    [TelegramEventTypes.MESSAGE_RECEIVED]: TelegramMessageReceivedPayload;
+    [TelegramEventTypes.MESSAGE_SENT]: TelegramMessageSentPayload;
+    [TelegramEventTypes.REACTION_RECEIVED]: TelegramReactionReceivedPayload;
+    [TelegramEventTypes.WORLD_JOINED]: TelegramWorldPayload;
+    [TelegramEventTypes.WORLD_CONNECTED]: TelegramWorldPayload;
+    [TelegramEventTypes.WORLD_LEFT]: TelegramWorldPayload;
+    [TelegramEventTypes.SLASH_START]: {
+        ctx: Context;
+    };
+    [TelegramEventTypes.ENTITY_JOINED]: TelegramEntityPayload;
+    [TelegramEventTypes.ENTITY_LEFT]: TelegramEntityPayload;
+    [TelegramEventTypes.ENTITY_UPDATED]: TelegramEntityPayload;
+    [TelegramEventTypes.INTERACTION_RECEIVED]: TelegramReactionReceivedPayload;
+}
+/**
+ * Telegram-specific message received payload
+ */
+export interface TelegramMessageReceivedPayload extends MessagePayload {
+    /** The original Telegram context */
+    ctx: Context;
+    /** The original Telegram message */
+    originalMessage: Message;
+}
+/**
+ * Telegram-specific message sent payload
+ */
+export interface TelegramMessageSentPayload extends MessagePayload {
+    /** The original Telegram messages */
+    originalMessages: Message[];
+    /** The chat ID where the message was sent */
+    chatId: number | string;
+}
+/**
+ * Telegram-specific reaction received payload
+ */
+export interface TelegramReactionReceivedPayload extends TelegramMessageReceivedPayload {
+    /** The reaction type as a string */
+    reactionString: string;
+    /** The original reaction object */
+    originalReaction: ReactionType;
+}
+/**
+ * Telegram-specific world payload
+ */
+export interface TelegramWorldPayload extends WorldPayload {
+    chat: Chat;
+    botUsername?: string;
+}
+/**
+ * Telegram-specific entity payload
+ */
+export interface TelegramEntityPayload extends EntityPayload {
+    telegramUser: {
+        id: number;
+        username?: string;
+        first_name?: string;
+    };
+}

package/dist/utils.d.ts

@@ -0,0 +1,29 @@
+import { InlineKeyboardButton } from '@telegraf/types';
+import { Button } from './types';
+/**
+ * This function converts standard markdown to Telegram MarkdownV2.
+ *
+ * In addition to processing code blocks, inline code, links, bold, strikethrough, and italic,
+ * it converts any header lines (those starting with one or more `#`) to bold text.
+ *
+ * Note: This solution uses a sequence of regex‐replacements and placeholders.
+ * It makes assumptions about non–nested formatting and does not cover every edge case.
+ */
+export declare function convertMarkdownToTelegram(markdown: string): string;
+/**
+ * Splits a message into chunks that fit within Telegram's message length limit
+ */
+/**
+ * Splits a text message into chunks based on a maximum length for each chunk.
+ *
+ * @param {string} text - The text message to split.
+ * @param {number} maxLength - The maximum length for each chunk (default is 4096).
+ * @returns {string[]} An array containing the text message split into chunks.
+ */
+export declare function splitMessage(text: string, maxLength?: number): string[];
+/**
+ * Converts Eliza buttons into Telegram buttons
+ * @param {Button[]} buttons - The buttons from Eliza content
+ * @returns {InlineKeyboardButton[]} Array of Telegram buttons
+ */
+export declare function convertToTelegramButtons(buttons?: Button[] | null): InlineKeyboardButton[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/plugin-telegram",
-  "version": "1.0.4",
+  "version": "1.0.9",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -18,8 +18,9 @@
     "dist"
   ],
   "dependencies": {
-    "@elizaos/core": "^1.0.0",
+    "@elizaos/core": "^1.0.19",
     "@telegraf/types": "7.1.0",
+    "@types/node": "^24.0.10",
     "strip-literal": "^3.0.0",
     "telegraf": "4.16.3",
     "type-detect": "^4.1.0",
@@ -31,7 +32,7 @@
     "vitest": "1.6.1"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc",
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",