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

package/README.md

@@ -22,6 +22,25 @@ Here are the available configuration options for the `character.json` file:
 | `messageTrackingLimit`          | Integer | `100`    | Sets the maximum number of messages to track in memory for each chat.                               |
 | `templates`                     | Object  | `{}`     | Allows customization of response templates for different message scenarios.                         |
 
+## Error 409: Conflict in Multiple Agents Environment
+
+When you encounter this error in your logs:
+
+```
+error: 409: Conflict: terminated by other getUpdates request; make sure that only one bot instance is running
+```
+
+This indicates a fundamental architectural limitation with the Telegram Bot API. The Telegram API strictly enforces that only one active connection can exist per bot token at any given time. This is by design to ensure reliable message delivery and prevent message duplication or loss.
+
+In ElizaOS multi-agent environments, this error commonly occurs when:
+
+1. **Multiple Agents Using Same Token**: Two or more agents (such as "Eliza" and another character) each have the `@elizaos/plugin-telegram` plugin enabled in their configuration
+2. **Simultaneous Initialization**: Each agent independently attempts to initialize its own Telegram service during startup
+3. **Token Collision**: All agents use the same `TELEGRAM_BOT_TOKEN` from your environment configuration
+4. **Connection Rejection**: When a second agent tries to establish a connection while another is already active, Telegram rejects it with a 409 error
+
+This is not a bug in ElizaOS or the Telegram plugin, but rather a result of using a shared resource (the bot token) that can only accept one connection at a time.
+
 ## Example `<charactername>.character.json`
 
 Below is an example configuration file with all options:
@@ -85,3 +104,40 @@ npm run dev
 ```bash
 bun start --character="characters/your-character.json"
 ```
+
+## Utilizing Telegram Buttons
+
+To send a message with native Telegram buttons, include an array of buttons in the message content. The following action demonstrates how to initiate a login flow using a Telegram button.
+
+```typescript
+export const initAuthHandshakeAction: Action = {
+  name: 'INIT_AUTH_HANDSHAKE',
+  description: 'Initiates the identity linking and authentication flow for new users.',
+  validate: async (_runtime, _message, _state) => {
+    return _message.content.source === 'telegram';
+  },
+  handler: async (runtime, message, _state, _options, callback): Promise<boolean> => {
+    try {
+      const user = await getUser(message.userId);
+      if (user) return false;
+
+      callback({
+        text: "Let's get you set up with a new account",
+        buttons: [
+          {
+            text: '🔑 Authenticate with Telegram',
+            url: `${FRONTEND_URL}/integrations/telegram`,
+            kind: 'login',
+          },
+        ],
+      }).catch((error) => {
+        console.error('Error sending callback:', error);
+      });
+
+      return true;
+    } catch (error) {
+      ...
+    }
+  },
+};
+```

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+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>;
+}
+
+declare const telegramPlugin: Plugin;
+
+export { MessageManager, TelegramService, telegramPlugin as default };