@elizaos/plugin-telegram 1.0.0-beta.4 → 1.0.0-beta.41

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Shaw Walters, aka Moon aka @lalalune
+Copyright (c) 2025 Shaw Walters and elizaOS Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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) {
+      ...
+    }
+  },
+};
+```