Channels
Plugin Telegram Business
By Telegram Business channel plugin for OpenClaw — bot replies on behalf of a business account in private chats
Install
npm install
#Configuration Example
channels:
telegram-business:
token: "123456:ABC-DEF..."
dmPolicy: open # open | allowlist | pairing
allowFrom: [] # Telegram user IDs (for allowlist mode)README
# @openclaw/telegram-business
OpenClaw channel plugin for **Telegram Business** — the bot replies to customers in private chats on behalf of the business account owner.
Unlike the regular Telegram channel where users talk to a bot, here OpenClaw answers as the business account itself. Customers see messages from the business owner, not from a bot.
## Prerequisites
1. **Telegram Bot** with Business Mode enabled:
- Open [@BotFather](https://t.me/BotFather) in Telegram
- Send `/newbot` or select an existing bot
- Send `/mybots` → select your bot → **Bot Settings** → **Business Mode** → **Enable**
- Copy the bot token
2. **Telegram Business account** (the account that will use the bot):
- Go to **Settings** → **Telegram Business** → **Chatbots**
- Enter the bot's username
- Configure which chats the bot can access
- Grant the desired rights (reply, read, delete, stories, profile, etc.)
3. **OpenClaw** >= 2026.3.28
## Installation
```bash
# From local directory
openclaw plugins install -l /path/to/openclaw-plugin-telegram-business
# Or from npm (when published)
openclaw plugins install @openclaw/telegram-business
```
## Configuration
### Option 1: Environment variable
```bash
export TELEGRAM_BUSINESS_BOT_TOKEN="123456:ABC-DEF..."
```
### Option 2: Gateway config
Add to your OpenClaw config file:
```yaml
channels:
telegram-business:
token: "123456:ABC-DEF..."
dmPolicy: open # open | allowlist | pairing
allowFrom: [] # Telegram user IDs (for allowlist mode)
```
### Multi-account setup
```yaml
channels:
telegram-business:
accounts:
law-firm:
token: "111111:AAA..."
dmPolicy: allowlist
allowFrom: ["12345678", "87654321"]
support:
token: "222222:BBB..."
dmPolicy: open
```
## DM Policies
| Policy | Behavior |
|--------|----------|
| `open` | Anyone can message the business account, OpenClaw will respond |
| `allowlist` | Only users listed in `allowFrom` get responses |
| `pairing` | New users must be approved before getting responses |
To approve a user in pairing mode:
```
/allow telegram-business:<userId>
```
## What the plugin handles
### Channel (inbound/outbound)
- Receives all message types: text, photos, documents, voice, video, stickers, contacts, locations, GIFs
- Replies on behalf of the business account owner (customers don't see a bot)
- Typing indicator before responses
- Marks incoming messages as read (if the right is granted)
- Handles edited and deleted messages
- Sends text with formatting (HTML/Markdown) and inline keyboards
- Sends media: photos, videos, voice, audio, animations, documents
### Agent Tools (14 tools)
When the bot is granted additional rights, OpenClaw agents can use these tools:
**Stories** (requires `can_manage_stories`):
- `telegram_business_post_story` — post a photo/video story
- `telegram_business_edit_story` — edit an existing story
- `telegram_business_delete_story` — delete a story
**Profile** (requires respective `can_edit_*` rights):
- `telegram_business_set_name` — change display name
- `telegram_business_set_bio` — change bio
- `telegram_business_set_profile_photo` — set profile photo
- `telegram_business_remove_profile_photo` — remove profile photo
- `telegram_business_set_username` — change username
**Gifts & Stars** (requires `can_view_gifts_and_stars` and related rights):
- `telegram_business_get_gifts` — list owned gifts
- `telegram_business_get_star_balance` — check Stars balance
- `telegram_business_convert_gift_to_stars` — convert a gift to Stars
- `telegram_business_upgrade_gift` — upgrade a gift
- `telegram_business_transfer_gift` — transfer a gift to another user
- `telegram_business_transfer_stars` — transfer Stars to the bot
## How it works
```
Customer sends DM to business account
-> Telegram routes to the bot via Business API
-> Plugin receives business_message
-> Marks as read + shows typing
-> Dispatches to OpenClaw runtime (dispatchInboundDirectDmWithRuntime)
-> Agent processes and generates response
-> Plugin sends reply via business_connection_id
-> Customer sees message from the business owner
```
## Project structure
```
index.ts # Plugin entry (defineChannelPluginEntry)
setup-entry.ts # Lightweight entry for disabled state
openclaw.plugin.json # Plugin manifest with config schema
src/
channel.ts # createChatChannelPlugin — plugin definition
config.ts # Account resolution and config parsing
connections.ts # In-memory store for active business connections
gateway.ts # Bot startup, polling, graceful shutdown
inbound.ts # Message handling + dispatch to OpenClaw
runtime.ts # Plugin runtime store
send.ts # Outbound: text, media, edit, delete, typing
account-management.ts # Stories, profile, gifts/stars API wrappers
tools.ts # 14 registered OpenClaw agent tools
```
## Development
```bash
# Clone and install
git clone <repo-url>
cd openclaw-plugin-telegram-business
pnpm install
# Type check
pnpm exec tsc --noEmit
# Install locally in OpenClaw
openclaw plugins install -l .
```
## Rights reference
Rights are granted by the business account owner when connecting the bot:
| Right | What it enables |
|-------|----------------|
| `can_reply` | Send and edit messages (24h window) |
| `can_read_messages` | Mark messages as read |
| `can_delete_outgoing_messages` | Delete bot's own messages |
| `can_delete_all_messages` | Delete any messages |
| `can_manage_stories` | Post, edit, delete stories |
| `can_edit_name` | Change display name |
| `can_edit_bio` | Change bio |
| `can_edit_profile_photo` | Set/remove profile photo |
| `can_edit_username` | Change username |
| `can_view_gifts_and_stars` | View gifts and Stars balance |
| `can_convert_gifts_to_stars` | Convert gifts to Stars |
| `can_transfer_and_upgrade_gifts` | Transfer and upgrade gifts |
| `can_transfer_stars` | Transfer Stars |
| `can_change_gift_settings` | Change gift privacy settings |
## License
MIT
channels
Comments
Sign in to leave a comment