@elizaos/plugin-telegram 1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shaw Walters, aka Moon aka @lalalune
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# Telegram Client Plugin for ElizaOS
+
+This plugin integrates a Telegram client with ElizaOS, allowing characters in ElizaOS to interact via Telegram. It provides an easy setup for starting the Telegram client using the provided bot token and includes basic lifecycle management.
+
+## Features
+
+- **Seamless Telegram Integration**: Connects ElizaOS characters to Telegram through the bot API.
+- **Configuration Validation**: Ensures required settings are properly configured before starting.
+- **Startup Logging**: Logs successful initialization of the Telegram client for better debugging.
+- **Future-proof Design**: Provides a basic structure for stopping the client (currently unsupported).
+
+## Configuration Options
+
+Here are the available configuration options for the `character.json` file:
+
+| Key                             | Type    | Default  | Description                                                                                         |
+| ------------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `clients`                       | Array   | Required | Specifies the client type (e.g., `["telegram"]`).                                                   |
+| `allowDirectMessages`           | Boolean | `false`  | Determines whether the bot should respond to direct messages (DMs).                                 |
+| `shouldOnlyJoinInAllowedGroups` | Boolean | `false`  | Ensures the bot only joins and responds in specified groups.                                        |
+| `allowedGroupIds`               | Array   | `[]`     | Lists the group IDs the bot is allowed to interact with (requires `shouldOnlyJoinInAllowedGroups`). |
+| `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.                         |
+
+## Example `<charactername>.character.json`
+
+Below is an example configuration file with all options:
+
+```json
+{
+  "clients": ["telegram"],
+  "allowDirectMessages": true,
+  "shouldOnlyJoinInAllowedGroups": true,
+  "allowedGroupIds": ["-123456789", "-987654321"],
+  "messageTrackingLimit": 100,
+  "templates": {
+    "telegramMessageHandlerTemplate": "Your custom template here"
+  },
+  "secrets": {
+    "key": "<your-bot-token>"
+  }
+}
+```
+
+## How to Modify Settings
+
+1. Locate the `character.json` file in your project directory.
+2. Update the file with the desired configuration options as shown in the example above.
+3. Save the file and restart the bot for the changes to take effect.
+
+## Best Practices
+
+- **Production**: Restrict bot access with `shouldOnlyJoinInAllowedGroups: true` and specify `allowedGroupIds` to ensure security.
+- **Token Management**: Always keep your bot token and backend tokens secure and never expose them in public repositories.
+
+## Pre-Requisites
+
+1. Add the bot token to the `.env` file in the project root:
+
+```env
+TELEGRAM_BOT_TOKEN=your-bot-token
+```
+
+2. Add the same token to your character configuration file:
+
+Create or modify `characters/your-character.json`:
+
+```json
+{
+  "clients": ["telegram"],
+  "secrets": {
+    "key": "<your-bot-token>"
+  }
+}
+```
+
+## From the project root:
+
+```bash
+npm run dev
+```
+
+## Or using pnpm:
+
+```bash
+pnpm start --character="characters/your-character.json"
+```
+

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { IAgentRuntime, Plugin, Service } from '@elizaos/core';
+import { Update } from '@telegraf/types';
+import { Telegraf, Context, NarrowedContext } from 'telegraf';
+
+declare class MessageManager {
+    bot: Telegraf<Context>;
+    protected runtime: IAgentRuntime;
+    constructor(bot: Telegraf<Context>, runtime: IAgentRuntime);
+    private processImage;
+    private sendMessageInChunks;
+    private sendMedia;
+    private splitMessage;
+    handleMessage(ctx: Context): Promise<void>;
+    handleReaction(ctx: NarrowedContext<Context<Update>, Update.MessageReactionUpdate>): Promise<void>;
+}
+
+declare class TelegramService extends Service {
+    static serviceType: string;
+    capabilityDescription: string;
+    private bot;
+    messageManager: MessageManager;
+    private options;
+    constructor(runtime: IAgentRuntime);
+    static start(runtime: IAgentRuntime): Promise<TelegramService>;
+    static stop(runtime: IAgentRuntime): Promise<void>;
+    stop(): Promise<void>;
+    private initializeBot;
+    private isGroupAuthorized;
+    private setupMessageHandlers;
+}
+declare const telegramPlugin: Plugin;
+
+export { TelegramService, telegramPlugin as default };