@elizaos/plugin-telegram 2.0.0-alpha.9 → 2.0.3-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +86 -105
  2. package/package.json +39 -24
  3. package/dist/index.d.ts +0 -1
  4. package/dist/index.js +0 -1820
  5. package/dist/index.js.map +0 -1
package/README.md CHANGED
@@ -1,143 +1,124 @@
1
- # Telegram Client Plugin for ElizaOS
1
+ # @elizaos/plugin-telegram
2
2
 
3
- 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.
3
+ Telegram connector for elizaOS. Gives an Eliza agent the ability to send and receive messages across Telegram private chats, groups, supergroups, channels, and forum topics.
4
4
 
5
- ## Features
5
+ ## What it does
6
6
 
7
- - **Seamless Telegram Integration**: Connects ElizaOS characters to Telegram through the bot API.
8
- - **Configuration Validation**: Ensures required settings are properly configured before starting.
9
- - **Startup Logging**: Logs successful initialization of the Telegram client for better debugging.
10
- - **Future-proof Design**: Provides a basic structure for stopping the client (currently unsupported).
7
+ - Runs a Telegraf long-poll bot connected to the Telegram Bot API.
8
+ - Routes incoming messages and reactions through the elizaOS runtime so configured actions, providers, and evaluators can respond.
9
+ - Syncs Telegram chats, users, and group membership into the runtime as Worlds, Rooms, and Entities.
10
+ - Handles forum topics as separate Rooms (channelId format: `<chatId>-<threadId>`).
11
+ - Supports outgoing buttons (`login` and `url` kinds) via the `TelegramContent.buttons` field.
12
+ - Provides HTTP setup routes for bot-token configuration and GramJS user-account login.
13
+ - Supports multiple bot accounts per agent via `character.settings.telegram.accounts`.
11
14
 
12
- ## Configuration Options
15
+ ## Prerequisites
13
16
 
14
- Here are the available configuration options for the `character.json` file:
17
+ Create a bot via [@BotFather](https://t.me/BotFather) and copy the token it provides.
15
18
 
16
- | Key | Type | Default | Description |
17
- | ------------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------- |
18
- | `clients` | Array | Required | Specifies the client type (e.g., `["telegram"]`). |
19
- | `allowDirectMessages` | Boolean | `false` | Determines whether the bot should respond to direct messages (DMs). |
20
- | `shouldOnlyJoinInAllowedGroups` | Boolean | `false` | Ensures the bot only joins and responds in specified groups. |
21
- | `allowedGroupIds` | Array | `[]` | Lists the group IDs the bot is allowed to interact with (requires `shouldOnlyJoinInAllowedGroups`). |
22
- | `messageTrackingLimit` | Integer | `100` | Sets the maximum number of messages to track in memory for each chat. |
23
- | `templates` | Object | `{}` | Allows customization of response templates for different message scenarios. |
19
+ ## Configuration
24
20
 
25
- ## Error 409: Conflict in Multiple Agents Environment
21
+ ### Minimal (single bot, environment variable)
26
22
 
27
- When you encounter this error in your logs:
28
-
29
- ```
30
- error: 409: Conflict: terminated by other getUpdates request; make sure that only one bot instance is running
23
+ ```env
24
+ TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
31
25
  ```
32
26
 
33
- 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.
34
-
35
- In ElizaOS multi-agent environments, this error commonly occurs when:
27
+ The plugin reads the token from the runtime setting `TELEGRAM_BOT_TOKEN` or `process.env.TELEGRAM_BOT_TOKEN`.
36
28
 
37
- 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
38
- 2. **Simultaneous Initialization**: Each agent independently attempts to initialize its own Telegram service during startup
39
- 3. **Token Collision**: All agents use the same `TELEGRAM_BOT_TOKEN` from your environment configuration
40
- 4. **Connection Rejection**: When a second agent tries to establish a connection while another is already active, Telegram rejects it with a 409 error
29
+ ### Via character settings
41
30
 
42
- 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.
43
-
44
- ## Example `<charactername>.character.json`
31
+ ```json
32
+ {
33
+ "name": "MyAgent",
34
+ "settings": {
35
+ "telegram": {
36
+ "botToken": "123456:ABC-DEF...",
37
+ "apiRoot": "https://api.telegram.org"
38
+ }
39
+ }
40
+ }
41
+ ```
45
42
 
46
- Below is an example configuration file with all options:
43
+ ### Multi-account
47
44
 
48
45
  ```json
49
46
  {
50
- "clients": ["telegram"],
51
- "allowDirectMessages": true,
52
- "shouldOnlyJoinInAllowedGroups": true,
53
- "allowedGroupIds": ["-123456789", "-987654321"],
54
- "messageTrackingLimit": 100,
55
- "templates": {
56
- "telegramMessageHandlerTemplate": "Your custom template here"
57
- },
58
- "secrets": {
59
- "key": "<your-bot-token>"
47
+ "settings": {
48
+ "telegram": {
49
+ "accounts": {
50
+ "supportBot": { "botToken": "111:aaa", "allowedChats": ["-100123456"] },
51
+ "announcementsBot": { "botToken": "222:bbb" }
52
+ }
53
+ }
60
54
  }
61
55
  }
62
56
  ```
63
57
 
64
- ## How to Modify Settings
58
+ ## Environment variables
65
59
 
66
- 1. Locate the `character.json` file in your project directory.
67
- 2. Update the file with the desired configuration options as shown in the example above.
68
- 3. Save the file and restart the bot for the changes to take effect.
60
+ | Variable | Required | Description |
61
+ |---|---|---|
62
+ | `TELEGRAM_BOT_TOKEN` | Yes (default account) | Bot token from @BotFather |
63
+ | `TELEGRAM_API_ROOT` | No | Override Bot API base URL (e.g. local Bot API server). Default: `https://api.telegram.org` |
64
+ | `TELEGRAM_ALLOWED_CHATS` | No | JSON array of chat ID strings the bot will respond to. If absent, all chats are allowed. Example: `["-100123456789"]` |
65
+ | `TELEGRAM_TEST_CHAT_ID` | No | Chat ID used by the live smoke-test suite |
69
66
 
70
- ## Best Practices
67
+ ## Enabling the plugin
71
68
 
72
- - **Production**: Restrict bot access with `shouldOnlyJoinInAllowedGroups: true` and specify `allowedGroupIds` to ensure security.
73
- - **Token Management**: Always keep your bot token and backend tokens secure and never expose them in public repositories.
69
+ The plugin auto-enables when the `telegram` connector key is present in the agent connector config. To load it explicitly, add it to the agent's plugin list:
74
70
 
75
- ## Pre-Requisites
71
+ ```json
72
+ {
73
+ "plugins": ["@elizaos/plugin-telegram"]
74
+ }
75
+ ```
76
76
 
77
- 1. Add the bot token to the `.env` file in the project root:
77
+ ## Setup UI routes
78
78
 
79
- ```env
80
- TELEGRAM_BOT_TOKEN=your-bot-token
81
- ```
79
+ The plugin mounts these HTTP routes (no plugin-name prefix) for the dashboard setup wizard:
82
80
 
83
- 2. Add the same token to your character configuration file:
81
+ | Method | Path | Purpose |
82
+ |---|---|---|
83
+ | GET | `/api/setup/telegram/status` | Current pairing state |
84
+ | POST | `/api/setup/telegram/start` | Validate + save bot token |
85
+ | POST | `/api/setup/telegram/cancel` | Remove saved token |
86
+ | GET | `/api/setup/telegram-account/status` | GramJS user-account auth state |
87
+ | POST | `/api/setup/telegram-account/start` | Begin GramJS login |
88
+ | POST | `/api/setup/telegram-account/submit-code` | Submit OTP or 2FA password |
89
+ | POST | `/api/setup/telegram-account/cancel` | Tear down GramJS session |
84
90
 
85
- Create or modify `characters/your-character.json`:
91
+ ## Sending buttons
86
92
 
87
- ```json
88
- {
89
- "clients": ["telegram"],
90
- "secrets": {
91
- "key": "<your-bot-token>"
92
- }
93
- }
93
+ Include a `buttons` array in any `Content` object returned to Telegram:
94
+
95
+ ```typescript
96
+ callback({
97
+ text: "Welcome! Click below to authenticate.",
98
+ buttons: [
99
+ {
100
+ kind: "login",
101
+ text: "Authenticate",
102
+ url: "https://your-app.example.com/auth",
103
+ },
104
+ ],
105
+ });
94
106
  ```
95
107
 
96
- ## From the project root:
108
+ Supported `kind` values: `"login"` (Telegram login widget), `"url"` (plain URL button).
97
109
 
98
- ```bash
99
- npm run dev
100
- ```
110
+ ## Owner pairing
101
111
 
102
- ## Or using bun:
112
+ The plugin registers a `/eliza_pair <code>` bot command that lets the Telegram user matching a 6-digit code shown in the agent dashboard bind their Telegram identity to the owner account. Rate-limited to 5 attempts per minute per user.
103
113
 
104
- ```bash
105
- bun start --character="characters/your-character.json"
106
- ```
114
+ ## 409 Conflict errors
107
115
 
108
- ## Utilizing Telegram Buttons
116
+ The Telegram Bot API permits only one active long-poll connection per token. If two agent processes share the same token simultaneously, Telegram rejects the second with a 409 error. The plugin stops the previous poller before launching a new one within the same process, but across separate processes you must ensure only one uses a given token at a time.
109
117
 
110
- 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.
118
+ ## Development
111
119
 
112
- ```typescript
113
- export const initAuthHandshakeAction: Action = {
114
- name: 'INIT_AUTH_HANDSHAKE',
115
- description: 'Initiates the identity linking and authentication flow for new users.',
116
- validate: async (_runtime, _message, _state) => {
117
- return _message.content.source === 'telegram';
118
- },
119
- handler: async (runtime, message, _state, _options, callback): Promise<boolean> => {
120
- try {
121
- const user = await getUser(message.userId);
122
- if (user) return false;
123
-
124
- callback({
125
- text: "Let's get you set up with a new account",
126
- buttons: [
127
- {
128
- text: '🔑 Authenticate with Telegram',
129
- url: `${FRONTEND_URL}/integrations/telegram`,
130
- kind: 'login',
131
- },
132
- ],
133
- }).catch((error) => {
134
- console.error('Error sending callback:', error);
135
- });
136
-
137
- return true;
138
- } catch (error) {
139
- ...
140
- }
141
- },
142
- };
120
+ ```bash
121
+ bun run --cwd plugins/plugin-telegram build
122
+ bun run --cwd plugins/plugin-telegram test
123
+ bun run --cwd plugins/plugin-telegram lint
143
124
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elizaos/plugin-telegram",
3
- "version": "2.0.0-alpha.9",
3
+ "version": "2.0.3-beta.2",
4
4
  "type": "module",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.js",
@@ -8,49 +8,64 @@
8
8
  "exports": {
9
9
  "./package.json": "./package.json",
10
10
  ".": {
11
- "import": {
12
- "types": "./dist/index.d.ts",
13
- "default": "./dist/index.js"
14
- }
11
+ "types": "./dist/index.d.ts",
12
+ "eliza-source": {
13
+ "types": "./src/index.ts",
14
+ "import": "./src/index.ts",
15
+ "default": "./src/index.ts"
16
+ },
17
+ "import": "./dist/index.js",
18
+ "default": "./dist/index.js"
19
+ },
20
+ "./*.css": "./dist/*.css",
21
+ "./*": {
22
+ "types": "./dist/*.d.ts",
23
+ "eliza-source": {
24
+ "types": "./src/*.ts",
25
+ "import": "./src/*.ts",
26
+ "default": "./src/*.ts"
27
+ },
28
+ "import": "./dist/*.js",
29
+ "default": "./dist/*.js"
15
30
  }
16
31
  },
17
32
  "files": [
18
33
  "dist"
19
34
  ],
20
35
  "dependencies": {
21
- "@elizaos/core": "next",
22
- "@telegraf/types": "7.1.0",
36
+ "@elizaos/core": "2.0.3-beta.2",
37
+ "@elizaos/plugin-commands": "2.0.3-beta.2",
38
+ "@telegraf/types": "^7.1.0",
23
39
  "@types/node": "^24.0.10",
24
40
  "strip-literal": "^3.0.0",
25
41
  "telegraf": "4.16.3",
26
- "type-detect": "^4.1.0",
27
- "typescript": "^5.8.3"
42
+ "telegram": "^2.26.22",
43
+ "type-detect": "^4.1.0"
28
44
  },
29
45
  "devDependencies": {
30
- "@elizaos/config": "^1.7.2",
31
- "@eslint/js": "^9.17.0",
32
- "@typescript-eslint/eslint-plugin": "^8.22.0",
33
- "@typescript-eslint/parser": "^8.22.0",
34
- "eslint": "^9.17.0",
35
- "prettier": "3.5.3",
36
- "tsup": "8.4.0",
37
- "vitest": "1.6.1"
46
+ "@biomejs/biome": "^2.4.14",
47
+ "@elizaos/config": "latest",
48
+ "tsup": "^8.5.1",
49
+ "typescript": "^6.0.3",
50
+ "vitest": "^4.0.0"
38
51
  },
39
52
  "scripts": {
40
- "build": "tsup",
53
+ "build": "tsup && tsc --project tsconfig.build.json",
41
54
  "dev": "tsup --watch",
42
55
  "test": "vitest run",
43
56
  "test:watch": "vitest",
44
- "lint": "eslint ./src --fix && prettier --write ./src",
45
- "lint:check": "eslint ./src",
46
- "clean": "rm -rf dist .turbo node_modules .turbo-tsconfig.json tsconfig.tsbuildinfo",
47
- "format": "prettier --write ./src",
48
- "format:check": "prettier --check ./src"
57
+ "lint": "bunx @biomejs/biome check --write --unsafe .",
58
+ "lint:check": "bunx @biomejs/biome check .",
59
+ "clean": "rm -rf dist .turbo .turbo-tsconfig.json tsconfig.tsbuildinfo",
60
+ "format": "bunx @biomejs/biome format --write .",
61
+ "format:check": "bunx @biomejs/biome format .",
62
+ "test:e2e": "node ../../packages/app-core/scripts/run-local-plugin-live-smoke.mjs",
63
+ "test:live": "bun run test:e2e"
49
64
  },
50
65
  "publishConfig": {
51
66
  "access": "public"
52
67
  },
53
- "gitHead": "646c632924826e2b75c2304a75ee56959fe4a460",
68
+ "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc",
54
69
  "repository": {
55
70
  "type": "git",
56
71
  "url": "git+https://github.com/elizaos-plugins/plugin-telegram.git"
package/dist/index.d.ts DELETED
@@ -1 +0,0 @@
1
- export * from "@elizaos/core";