agent-messenger 2.12.0 → 2.12.1

package/examples/telegrambot-listen.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+// Run `agent-telegrambot auth set <token>` first so login() can pick up stored creds.
+import { TelegramBotClient } from '../src/platforms/telegrambot/client'
+import { TelegramBotListener } from '../src/platforms/telegrambot/listener'
+
+async function main() {
+  const client = await new TelegramBotClient().login()
+
+  const listener = new TelegramBotListener(client, {
+    allowedUpdates: ['message', 'edited_message', 'callback_query', 'my_chat_member'],
+  })
+
+  listener.on('connected', ({ user }) => {
+    console.log(`Connected as @${user.username ?? user.first_name} (id: ${user.id})`)
+    console.log('Listening for events. Press Ctrl+C to stop.\n')
+  })
+
+  listener.on('disconnected', () => {
+    console.log('[disconnected] retrying...')
+  })
+
+  listener.on('message', (message) => {
+    if (message.from?.is_bot) return
+    const time = new Date(message.date * 1000).toLocaleTimeString()
+    const sender = message.from?.username ?? message.from?.first_name ?? 'unknown'
+    console.log(`[${time}] message in ${message.chat.id} <${sender}>: ${message.text ?? '(non-text)'}`)
+  })
+
+  listener.on('edited_message', (message) => {
+    console.log(`[edit] message ${message.message_id} in ${message.chat.id}`)
+  })
+
+  listener.on('callback_query', (query) => {
+    console.log(`[callback] data=${query.data ?? '(none)'} from ${query.from.username ?? query.from.id}`)
+  })
+
+  listener.on('my_chat_member', (event) => {
+    console.log(`[my_chat_member] ${event.chat.id}: ${event.old_chat_member.status} -> ${event.new_chat_member.status}`)
+  })
+
+  listener.on('error', (err) => {
+    console.error(`[error] ${err.message}`)
+  })
+
+  process.on('SIGINT', () => {
+    console.log('\nStopping...')
+    listener.stop()
+    process.exit(130)
+  })
+
+  await listener.start()
+}
+
+main()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-messenger",
-  "version": "2.12.0",
-  "description": "Multi-platform messaging CLI for AI agents (Slack, Discord, Teams, Webex, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, Channel Talk)",
+  "version": "2.12.1",
+  "description": "Multi-platform messaging CLI for AI agents (Slack, Discord, Teams, Webex, Telegram, Telegram Bot, WhatsApp, LINE, Instagram, KakaoTalk, Channel Talk)",
   "repository": {
     "type": "git",
     "url": "https://github.com/agent-messenger/agent-messenger"
@@ -19,6 +19,7 @@
     "agent-slackbot": "dist/src/platforms/slackbot/cli.js",
     "agent-teams": "dist/src/platforms/teams/cli.js",
     "agent-telegram": "dist/src/platforms/telegram/cli.js",
+    "agent-telegrambot": "dist/src/platforms/telegrambot/cli.js",
     "agent-webex": "dist/src/platforms/webex/cli.js",
     "agent-wechatbot": "dist/src/platforms/wechatbot/cli.js",
     "agent-whatsapp": "dist/src/platforms/whatsapp/cli.js",
@@ -71,6 +72,9 @@
       ],
       "channeltalkbot": [
         "./dist/src/platforms/channeltalkbot/index.d.ts"
+      ],
+      "telegrambot": [
+        "./dist/src/platforms/telegrambot/index.d.ts"
       ]
     }
   },
@@ -135,6 +139,10 @@
     "./channeltalkbot": {
       "types": "./dist/src/platforms/channeltalkbot/index.d.ts",
       "default": "./dist/src/platforms/channeltalkbot/index.js"
+    },
+    "./telegrambot": {
+      "types": "./dist/src/platforms/telegrambot/index.d.ts",
+      "default": "./dist/src/platforms/telegrambot/index.js"
     }
   },
   "scripts": {

package/scripts/postbuild.ts

@@ -9,6 +9,7 @@ const cliFiles = [
   'dist/src/platforms/channeltalk/cli.js',
   'dist/src/platforms/channeltalkbot/cli.js',
   'dist/src/platforms/telegram/cli.js',
+  'dist/src/platforms/telegrambot/cli.js',
 ]
 
 for (const file of cliFiles) {

package/skills/agent-channeltalk/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-channeltalk
 description: Interact with Channel Talk using extracted desktop app or browser credentials - read chats, send messages, search messages, manage groups
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-channeltalk:*)
 metadata:
   openclaw:

package/skills/agent-channeltalkbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-channeltalkbot
 description: Interact with Channel Talk workspaces using API credentials - send messages, read chats, manage groups and bots
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-channeltalkbot:*)
 metadata:
   openclaw:

package/skills/agent-discord/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-discord
 description: Interact with Discord servers - send messages, read channels, manage reactions
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-discord:*)
 metadata:
   openclaw:

package/skills/agent-discordbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-discordbot
 description: Interact with Discord servers using bot tokens - send messages, read channels, manage reactions
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-discordbot:*)
 metadata:
   openclaw:

package/skills/agent-instagram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-instagram
 description: Interact with Instagram DMs - send messages, read conversations, manage accounts
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-instagram:*)
 metadata:
   openclaw:

package/skills/agent-kakaotalk/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-kakaotalk
 description: Interact with KakaoTalk - send messages, read chats, manage conversations
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-kakaotalk:*)
 metadata:
   openclaw:
@@ -56,7 +56,7 @@ Registers the CLI as a sub-device (tablet slot by default). Your desktop app kee
 agent-kakaotalk auth login
 ```
 
-In interactive mode, this prompts for email and password. The CLI first tries to extract cached credentials from the desktop app so you may not need to type anything.
+In interactive mode, this prompts for email and password. On macOS and Windows, the CLI first tries to extract cached credentials from the desktop app so you may not need to type anything. On Linux there is no desktop app, so always pass credentials explicitly via `--email` and `--password` (or `--password-file`).
 
 For AI agents (non-interactive), provide credentials via flags:
 
@@ -488,8 +488,7 @@ See the [KakaoTalk SDK documentation](https://agent-messenger.dev/docs/sdk/kakao
 
 ## Limitations
 
-- macOS and Windows only (desktop app needed for auto-extracting email/password during login)
-- No Linux support (KakaoTalk desktop not available on Linux)
+- Auto-extraction of email/password from the desktop app is **macOS and Windows only** (KakaoTalk desktop is not available on Linux). Linux users must pass `--email` and `--password` (or `--password-file`) explicitly — the LOCO protocol, login flow, and all messaging features work on Linux.
 - No file upload or download
 - No channel/chat room creation or management
 - No friend list management
@@ -526,7 +525,15 @@ pnpm dlx --package agent-messenger agent-kakaotalk chat list --pretty
 
 ### Password prompt on fresh install
 
-On fresh installs, the desktop app (macOS or Windows) may hash or omit the password from its cache, so the CLI cannot extract it automatically. The CLI will prompt for the password once to register the device — via a native dialog on macOS (AppKit) and Windows (PowerShell WinForms), or via a TTY prompt if a terminal is available. After registration, the password is never needed again.
+On fresh installs, the desktop app (macOS or Windows) may hash or omit the password from its cache, so the CLI cannot extract it automatically. The CLI will prompt for the password once to register the device — via a native dialog on macOS (AppKit), Windows (PowerShell WinForms), or Linux (`zenity` / `kdialog`), or via a TTY prompt if a terminal is available. After registration, the password is never needed again.
+
+On Linux there is no desktop app to extract from, so always provide credentials explicitly:
+
+```bash
+agent-kakaotalk auth login --email user@example.com --password-file /tmp/.kakao-pw
+```
+
+`--password-file` reads the file then immediately deletes it, so the password never appears in shell history or process listings.
 
 When the CLI returns `{"next_action": "run_interactive", ...}`, use a tmux session to let the user type their password securely. See "Handling `run_interactive`" above for the exact steps.
 

package/skills/agent-line/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-line
 description: Interact with LINE - send messages, read chats, manage conversations
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-line:*)
 metadata:
   openclaw:

package/skills/agent-slack/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slack
 description: Interact with Slack workspaces - send messages, read channels, manage reactions
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-slack:*)
 metadata:
   openclaw:

package/skills/agent-slackbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slackbot
 description: Interact with Slack workspaces using bot tokens - send messages, read channels, manage reactions
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-slackbot:*)
 metadata:
   openclaw:

package/skills/agent-teams/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-teams
 description: Interact with Microsoft Teams - send messages, read channels, manage reactions
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-teams:*)
 metadata:
   openclaw:

package/skills/agent-telegram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegram
 description: Interact with Telegram through TDLib - authenticate, inspect chats, and send messages
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-telegram:*)
 ---
 

package/skills/agent-telegrambot/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: agent-telegrambot
+description: Interact with Telegram using bot tokens - send messages, read chats, manage reactions
+version: 2.12.1
+allowed-tools: Bash(agent-telegrambot:*)
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - agent-telegrambot
+    install:
+      - kind: node
+        package: agent-messenger
+        bins: [agent-telegrambot]
+---
+
+# Agent TelegramBot
+
+A TypeScript CLI tool that enables AI agents and humans to interact with Telegram using **Bot API tokens** (the kind issued by [@BotFather](https://t.me/BotFather)). Unlike `agent-telegram` which authenticates as a real user account via TDLib, `agent-telegrambot` uses Telegram's HTTP Bot API — designed for server-side and CI/CD integrations.
+
+## Key Concepts
+
+Before diving in, a few things about Telegram Bot integration:
+
+- **Bot tokens** — Issued by talking to [@BotFather](https://t.me/BotFather) inside Telegram. Format: `123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`. Bot acts as its own bot account, with a username ending in `bot`.
+- **Bot ≠ User** — Bots cannot initiate DMs. The user must `/start` the bot first. In groups, bots receive only messages mentioning them or commands unless privacy mode is disabled in BotFather settings.
+- **Chat IDs** — Numeric IDs (positive for users, negative for groups, very negative for supergroups/channels). Channels can also be referenced by `@channelusername`.
+- **Real-time events** — Available via the SDK's long-polling listener (`getUpdates`), not via the CLI. Telegram Bot API does not support WebSockets.
+- **Webhook vs polling** — A bot can use webhooks OR long-polling, not both. The SDK listener auto-disables any active webhook before polling.
+
+## Quick Start
+
+```bash
+# Set your bot token (validates against Telegram)
+agent-telegrambot auth set 123456789:ABC-DEF1234...
+
+# Verify authentication
+agent-telegrambot whoami
+
+# Send a message
+agent-telegrambot message send @username "Hello from bot!"
+
+# Get chat info
+agent-telegrambot chat info @somegroup
+```
+
+## Authentication
+
+### Bot Token Setup
+
+`agent-telegrambot` uses Bot API tokens which you create by chatting with [@BotFather](https://t.me/BotFather):
+
+```bash
+# Set bot token (validates against Telegram API before saving)
+agent-telegrambot auth set 123456789:ABC-DEF1234...
+
+# Set with a custom bot identifier
+agent-telegrambot auth set <token> --bot deploy
+
+# Check auth status
+agent-telegrambot auth status
+
+# Clear stored credentials
+agent-telegrambot auth clear
+```
+
+### Multi-Bot Support
+
+```bash
+# List all configured bots
+agent-telegrambot auth list
+
+# Switch active bot
+agent-telegrambot auth use <bot-id>
+
+# Remove a bot
+agent-telegrambot auth remove <bot-id>
+
+# Use a specific bot for a single command
+agent-telegrambot --bot deploy message send @channel "Deploy succeeded"
+```
+
+## Memory
+
+The agent maintains a `~/.config/agent-messenger/MEMORY.md` file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the `Read` and `Write` tools to manage your memory file.
+
+### What to Store
+
+- Chat IDs with names (e.g. `-1001234567890` → "alerts channel")
+- User IDs with display names (e.g. `123456789` → "Alice")
+- Bot identifiers and their purposes
+- User-given aliases ("the alerts bot", "the team channel")
+
+### What NOT to Store
+
+Never store bot tokens, credentials, or any sensitive data. Never store full message content (just IDs and chat context).
+
+### Format / Example
+
+```markdown
+# Agent Messenger Memory
+
+## Telegram Bots
+
+- `deploy` — Deploy Bot (active)
+- `alert` — Alert Bot
+
+## Chats (Deploy Bot)
+
+- `-1001234567890` — #ci-alerts (channel)
+- `-1009876543210` — Engineering (supergroup)
+- `123456789` — Alice (DM)
+
+## Aliases
+
+- "alerts" → `-1001234567890`
+```
+
+## Commands
+
+### Auth Commands
+
+```bash
+# Set bot token
+agent-telegrambot auth set <token>
+agent-telegrambot auth set <token> --bot deploy
+
+# Check auth status
+agent-telegrambot auth status
+agent-telegrambot auth status --bot deploy
+
+# Clear all credentials
+agent-telegrambot auth clear
+
+# List stored bots
+agent-telegrambot auth list
+
+# Switch active bot
+agent-telegrambot auth use <bot-id>
+
+# Remove a stored bot
+agent-telegrambot auth remove <bot-id>
+```
+
+### Whoami Command
+
+```bash
+# Show current authenticated bot
+agent-telegrambot whoami
+agent-telegrambot whoami --pretty
+agent-telegrambot whoami --bot <bot-id>
+```
+
+### Message Commands
+
+```bash
+# Send a text message
+agent-telegrambot message send <chat> <text>
+agent-telegrambot message send @username "Hello"
+agent-telegrambot message send -1001234567890 "Hello channel"
+
+# Send with formatting
+agent-telegrambot message send @username "<b>Bold</b> message" --parse-mode HTML
+
+# Reply to a specific message
+agent-telegrambot message send @username "Reply text" --reply-to 12345
+
+# Send silently (no notification)
+agent-telegrambot message send @username "Silent message" --silent
+
+# Send to a forum topic
+agent-telegrambot message send <chat> "Topic message" --thread-id 5
+
+# Edit a message (bot's own messages only)
+agent-telegrambot message update <chat> <message-id> <new-text>
+
+# Delete a message
+agent-telegrambot message delete <chat> <message-id> --force
+
+# Forward a message between chats
+agent-telegrambot message forward <to-chat> <from-chat> <message-id>
+
+# Upload a document
+agent-telegrambot message upload <chat> ./report.pdf --caption "Daily report"
+```
+
+### Chat Commands
+
+```bash
+# Get chat info
+agent-telegrambot chat info <chat>
+agent-telegrambot chat info @somegroup
+agent-telegrambot chat info -1001234567890
+
+# Get chat member info
+agent-telegrambot chat member <chat> <user-id>
+```
+
+### Reaction Commands
+
+```bash
+# Set a reaction (replaces any existing reaction by the bot)
+agent-telegrambot reaction set <chat> <message-id> 👍
+agent-telegrambot reaction set <chat> <message-id> 👍 --big
+
+# Clear all reactions
+agent-telegrambot reaction clear <chat> <message-id>
+```
+
+## Output Format
+
+### JSON (Default)
+
+All commands output JSON by default for AI consumption:
+
+```json
+{
+  "message": {
+    "message_id": 42,
+    "chat_id": -1001234567890,
+    "text": "Hello",
+    "from": "mybot",
+    "date": 1735689600
+  }
+}
+```
+
+### Pretty (Human-Readable)
+
+Use `--pretty` flag for formatted output:
+
+```bash
+agent-telegrambot message send @username "Hello" --pretty
+```
+
+## Global Options
+
+| Option       | Description                            |
+| ------------ | -------------------------------------- |
+| `--pretty`   | Human-readable output instead of JSON  |
+| `--bot <id>` | Use a specific bot for this command    |
+
+## Chat ID Resolution
+
+The `<chat>` argument accepts:
+
+- **Numeric ID**: `123456789` (user), `-1001234567890` (channel/supergroup)
+- **@username**: `@channelname`, `@username` (must be public)
+- **Plain username**: `channelname` (auto-prefixed with `@`)
+
+Bots cannot DM a user who has never started a chat with the bot. The user must send `/start` first.
+
+## Real-Time Events
+
+Real-time events are NOT available in the CLI but ARE available via the SDK using long-polling:
+
+```typescript
+import { TelegramBotClient, TelegramBotListener } from 'agent-messenger/telegrambot'
+
+const client = await new TelegramBotClient().login({ token: 'YOUR_BOT_TOKEN' })
+const listener = new TelegramBotListener(client, {
+  allowedUpdates: ['message', 'callback_query'],
+})
+
+listener.on('message', (msg) => {
+  console.log(`From ${msg.chat.id}: ${msg.text}`)
+})
+
+await listener.start()
+```
+
+Long-polling means the bot opens a long-lived HTTPS connection that the server holds open until updates arrive. No public endpoint is required — perfect for CI/CD and behind-NAT environments.
+
+## Error Handling
+
+All commands return consistent error format:
+
+```json
+{
+  "error": "Forbidden: bot can't initiate conversation with a user"
+}
+```
+
+Common errors:
+
+- `Unauthorized` — Invalid or revoked bot token. Generate a new token via @BotFather.
+- `Forbidden` — Bot was kicked from chat, or user hasn't started the bot, or bot lacks permissions.
+- `Bad Request: chat not found` — Wrong chat ID, or the bot isn't a member of that chat.
+- `Conflict` — Another `getUpdates` call is in progress (only one polling instance allowed per bot).
+- `Too Many Requests` — Rate limited; the client automatically retries after the `retry_after` interval.
+
+## Configuration
+
+Credentials stored in `~/.config/agent-messenger/telegrambot-credentials.json` (0600 permissions). The location can be overridden with `AGENT_MESSENGER_CONFIG_DIR`.
+
+## Key Differences from agent-telegram
+
+| Feature              | agent-telegram (TDLib)            | agent-telegrambot (Bot API)       |
+| -------------------- | --------------------------------- | --------------------------------- |
+| Token type           | User session (TDLib)              | Bot token (BotFather)             |
+| Auth                 | Phone + code, stateful            | One-time token from BotFather     |
+| Initiate DMs         | Yes                               | No (user must `/start` first)     |
+| Read all group msgs  | Yes                               | Only with privacy mode disabled   |
+| ToS for automation   | Grey area at scale                | Officially sanctioned             |
+| CI/CD friendly       | Possible (persist auth state)     | Yes (just set token)              |
+| Real-time events     | Yes (TDLib updates)               | Yes (long-polling getUpdates)     |
+| Inline keyboards     | No                                | Yes (via SDK)                     |
+
+## Limitations
+
+- Bots cannot initiate DMs — user must send `/start` first
+- Bots cannot read group messages by default (privacy mode is on by default; turn it off via @BotFather for full access, or grant admin)
+- Bot can only edit/delete its own messages, except in groups where it has delete permissions
+- Plain text messages with optional HTML/Markdown parse modes (no inline keyboards from the CLI yet — use the SDK)
+- File uploads use multipart/form-data; max 50MB per file via the standard Bot API server
+- Only one `getUpdates` polling instance can run per bot (Telegram returns 409 Conflict otherwise)
+
+## Troubleshooting
+
+### `agent-telegrambot: command not found`
+
+**`agent-telegrambot` is NOT the npm package name.** The npm package is `agent-messenger`.
+
+If the package is installed globally, use `agent-telegrambot` directly:
+
+```bash
+agent-telegrambot message send @username "Hello"
+```
+
+If the package is NOT installed, use `npx -y` by default:
+
+```bash
+npx -y agent-messenger telegrambot message send @username "Hello"
+bunx agent-messenger telegrambot message send @username "Hello"
+pnpm dlx agent-messenger telegrambot message send @username "Hello"
+```
+
+> If you already know the user's preferred package runner (e.g., `bunx`, `pnpm dlx`), use that instead.
+
+**NEVER run `npx agent-telegrambot`, `bunx agent-telegrambot`, or `pnpm dlx agent-telegrambot`** — it will fail or install a wrong package since `agent-telegrambot` is not the npm package name.
+
+### "Forbidden: bot can't initiate conversation with a user"
+
+The user has never started a chat with the bot. They need to find the bot in Telegram and tap **Start** (or send `/start`) before the bot can message them.
+
+### "Conflict: terminated by other getUpdates request"
+
+Another instance (or a stale webhook) is polling the same bot. Stop other instances, or run:
+
+```bash
+# Through the SDK or curl - no CLI helper for this yet
+curl "https://api.telegram.org/bot<TOKEN>/deleteWebhook?drop_pending_updates=true"
+```
+
+### "Bad Request: chat not found"
+
+Either the chat ID is wrong, the username is misspelled, or the bot isn't a member of that chat. Make sure the bot has been added to the group/channel and (for channels) given posting permission.

package/skills/agent-webex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webex
 description: Interact with Cisco Webex - send messages, read spaces, manage memberships
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-webex:*)
 metadata:
   openclaw:

package/skills/agent-wechatbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-wechatbot
 description: Interact with WeChat Official Account using API credentials - send messages, manage templates, list followers
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-wechatbot:*)
 metadata:
   openclaw:

package/skills/agent-whatsapp/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsapp
 description: Interact with WhatsApp - send messages, read chats, manage conversations
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-whatsapp:*)
 metadata:
   openclaw:

package/skills/agent-whatsappbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsappbot
 description: Interact with WhatsApp using Cloud API credentials - send messages, manage templates
-version: 2.12.0
+version: 2.12.1
 allowed-tools: Bash(agent-whatsappbot:*)
 metadata:
   openclaw:

package/src/cli.ts

@@ -40,6 +40,10 @@ program.command('telegram', 'Interact with Telegram via TDLib', {
   executableFile: join(__dirname, 'platforms', 'telegram', `cli${ext}`),
 })
 
+program.command('telegrambot', 'Interact with Telegram using bot tokens', {
+  executableFile: join(__dirname, 'platforms', 'telegrambot', `cli${ext}`),
+})
+
 program.command('whatsapp', 'Interact with WhatsApp via linked device', {
   executableFile: join(__dirname, 'platforms', 'whatsapp', `cli${ext}`),
 })