Merge 8280ce880e into 09be5d45d5
This commit is contained in:
29 files changed
+4744
-14
No files matched your search
@@ -0,0 +1,572 @@
|
||||
---
|
||||
summary: "Telegram user account support via GramJS/MTProto - access cloud chats as your personal account"
|
||||
read_when:
|
||||
- Working on Telegram user account features
|
||||
- Need access to personal DMs and groups
|
||||
- Want to use Telegram without creating a bot
|
||||
---
|
||||
# Telegram (GramJS / User Account)
|
||||
|
||||
**Status:** Beta (Phase 1 complete - DMs and groups)
|
||||
|
||||
Connect openclaw to your **personal Telegram account** using GramJS (MTProto protocol). This allows the agent to access your DMs, groups, and channels as *you* — no bot required.
|
||||
|
||||
## Quick Setup
|
||||
|
||||
1. **Get API credentials** from [https://my.telegram.org/apps](https://my.telegram.org/apps)
|
||||
- `api_id` (integer)
|
||||
- `api_hash` (string)
|
||||
|
||||
2. **Run the setup wizard:**
|
||||
```bash
|
||||
openclaw setup telegram-gramjs
|
||||
```
|
||||
|
||||
3. **Follow the prompts:**
|
||||
- Enter your phone number (format: +12025551234)
|
||||
- Enter SMS verification code
|
||||
- Enter 2FA password (if enabled on your account)
|
||||
|
||||
4. **Done!** The session is saved to your config file.
|
||||
|
||||
## What It Is
|
||||
|
||||
- A **user account** channel (not a bot)
|
||||
- Uses **GramJS** (JavaScript implementation of Telegram's MTProto protocol)
|
||||
- Access to **all your chats**: DMs, groups, channels (as yourself)
|
||||
- **Session persistence** via encrypted StringSession
|
||||
- **Routing rules**: DMs → main session, Groups → isolated sessions
|
||||
|
||||
## When to Use GramJS vs Bot API
|
||||
|
||||
| Feature | GramJS (User Account) | Bot API (grammY) |
|
||||
|---------|----------------------|------------------|
|
||||
| **Access** | Your personal account | Separate bot account |
|
||||
| **DMs** | ✅ All your DMs | ✅ Only DMs to the bot |
|
||||
| **Groups** | ✅ All your groups | ❌ Only groups with bot added |
|
||||
| **Channels** | ✅ Subscribed channels | ❌ Not supported |
|
||||
| **Read History** | ✅ Full message history | ❌ Only new messages |
|
||||
| **Setup** | API credentials + phone auth | Bot token from @BotFather |
|
||||
| **Privacy** | You are the account | Separate bot identity |
|
||||
| **Rate Limits** | Strict (user account limits) | More lenient (bot limits) |
|
||||
|
||||
**Use GramJS when:**
|
||||
- You want the agent to access your personal Telegram
|
||||
- You need full chat history access
|
||||
- You want to avoid creating a separate bot
|
||||
|
||||
**Use Bot API when:**
|
||||
- You want a separate bot identity
|
||||
- You need webhook support (not yet in GramJS)
|
||||
- You prefer simpler setup (just a token)
|
||||
|
||||
## Configuration
|
||||
|
||||
### Basic Setup (Single Account)
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
telegramGramjs: {
|
||||
enabled: true,
|
||||
apiId: 123456,
|
||||
apiHash: "your_api_hash_here",
|
||||
phoneNumber: "+12025551234",
|
||||
sessionString: "encrypted_session_data",
|
||||
dmPolicy: "pairing",
|
||||
groupPolicy: "open"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Account Setup
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
telegramGramjs: {
|
||||
enabled: true,
|
||||
accounts: {
|
||||
personal: {
|
||||
name: "Personal Account",
|
||||
apiId: 123456,
|
||||
apiHash: "hash1",
|
||||
phoneNumber: "+12025551234",
|
||||
sessionString: "session1",
|
||||
dmPolicy: "pairing"
|
||||
},
|
||||
work: {
|
||||
name: "Work Account",
|
||||
apiId: 789012,
|
||||
apiHash: "hash2",
|
||||
phoneNumber: "+15551234567",
|
||||
sessionString: "session2",
|
||||
dmPolicy: "allowlist",
|
||||
allowFrom: ["+15559876543"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
You can set credentials via environment variables:
|
||||
|
||||
```bash
|
||||
export TELEGRAM_API_ID=123456
|
||||
export TELEGRAM_API_HASH=your_api_hash
|
||||
export TELEGRAM_SESSION_STRING=your_encrypted_session
|
||||
```
|
||||
|
||||
**Note:** Config file values take precedence over environment variables.
|
||||
|
||||
## Getting API Credentials
|
||||
|
||||
1. Go to [https://my.telegram.org/apps](https://my.telegram.org/apps)
|
||||
2. Log in with your phone number
|
||||
3. Click **"API Development Tools"**
|
||||
4. Fill out the form:
|
||||
- **App title:** openclaw
|
||||
- **Short name:** openclaw-gateway
|
||||
- **Platform:** Other
|
||||
- **Description:** Personal agent gateway
|
||||
5. Click **"Create application"**
|
||||
6. Save your `api_id` and `api_hash`
|
||||
|
||||
**Important notes:**
|
||||
- `api_id` and `api_hash` are **NOT secrets** — they identify your app, not your account
|
||||
- The **session string** is the secret — keep it encrypted and secure
|
||||
- You can use the same API credentials for multiple phone numbers
|
||||
|
||||
## Authentication Flow
|
||||
|
||||
The interactive setup wizard (`openclaw setup telegram-gramjs`) handles:
|
||||
|
||||
### 1. Phone Number
|
||||
```
|
||||
Enter your phone number (format: +12025551234): +12025551234
|
||||
```
|
||||
|
||||
**Format rules:**
|
||||
- Must start with `+`
|
||||
- Country code required
|
||||
- 10-15 digits total
|
||||
- Example: `+12025551234` (US), `+442071234567` (UK)
|
||||
|
||||
### 2. SMS Code
|
||||
```
|
||||
📱 A verification code has been sent to your phone via SMS.
|
||||
Enter the verification code: 12345
|
||||
```
|
||||
|
||||
**Telegram will send a 5-digit code to your phone.**
|
||||
|
||||
### 3. Two-Factor Authentication (if enabled)
|
||||
```
|
||||
🔒 Your account has Two-Factor Authentication enabled.
|
||||
Enter your 2FA password: ********
|
||||
```
|
||||
|
||||
**Only required if you have 2FA enabled on your Telegram account.**
|
||||
|
||||
### 4. Session Saved
|
||||
```
|
||||
✅ Authentication successful!
|
||||
Session string generated. This will be saved to your config.
|
||||
```
|
||||
|
||||
The encrypted session string is saved to your config file.
|
||||
|
||||
## Session Management
|
||||
|
||||
### Session Persistence
|
||||
|
||||
After successful authentication, a **StringSession** is generated and saved:
|
||||
|
||||
```json5
|
||||
{
|
||||
sessionString: "encrypted_base64_session_data"
|
||||
}
|
||||
```
|
||||
|
||||
This session remains valid until:
|
||||
- You explicitly log out via Telegram settings
|
||||
- Telegram detects suspicious activity
|
||||
- You hit the max concurrent sessions limit (~10)
|
||||
|
||||
### Session Security
|
||||
|
||||
**⚠️ IMPORTANT: Session strings are sensitive credentials!**
|
||||
|
||||
- Session strings grant **full access** to your account
|
||||
- Store them **encrypted** (openclaw does this automatically)
|
||||
- Never commit session strings to git
|
||||
- Never share session strings with anyone
|
||||
|
||||
If a session is compromised:
|
||||
1. Go to Telegram Settings → Privacy → Active Sessions
|
||||
2. Terminate the suspicious session
|
||||
3. Re-run `openclaw setup telegram-gramjs` to create a new session
|
||||
|
||||
### Session File Storage (Alternative)
|
||||
|
||||
Instead of storing in config, you can use a session file:
|
||||
|
||||
```json5
|
||||
{
|
||||
sessionFile: "~/.config/openclaw/sessions/telegram-personal.session"
|
||||
}
|
||||
```
|
||||
|
||||
The file will be encrypted automatically.
|
||||
|
||||
## DM Policies
|
||||
|
||||
Control who can send DMs to your account:
|
||||
|
||||
```json5
|
||||
{
|
||||
dmPolicy: "pairing", // "pairing", "open", "allowlist", "closed"
|
||||
allowFrom: ["+12025551234", "@username", "123456789"]
|
||||
}
|
||||
```
|
||||
|
||||
| Policy | Behavior |
|
||||
|--------|----------|
|
||||
| `pairing` | First contact requires approval (default) |
|
||||
| `open` | Accept DMs from anyone |
|
||||
| `allowlist` | Only accept from `allowFrom` list |
|
||||
| `closed` | Reject all DMs |
|
||||
|
||||
## Group Policies
|
||||
|
||||
Control how the agent responds in groups:
|
||||
|
||||
```json5
|
||||
{
|
||||
groupPolicy: "open", // "open", "allowlist", "closed"
|
||||
groupAllowFrom: ["@groupusername", "-100123456789"],
|
||||
groups: {
|
||||
"-100123456789": { // Specific group ID
|
||||
requireMention: true,
|
||||
allowFrom: ["@alice", "@bob"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Group Settings
|
||||
|
||||
- **`requireMention`:** Only respond when mentioned (default: true)
|
||||
- **`allowFrom`:** Allowlist of users who can trigger the agent
|
||||
- **`autoReply`:** Enable auto-reply in this group
|
||||
|
||||
### Group IDs
|
||||
|
||||
GramJS uses Telegram's internal group IDs:
|
||||
- Format: `-100{channel_id}` (e.g., `-1001234567890`)
|
||||
- Find group ID: Send a message in the group, check logs for `chatId`
|
||||
|
||||
## Message Routing
|
||||
|
||||
### DM Messages
|
||||
```
|
||||
telegram-gramjs:{accountId}:{senderId}
|
||||
```
|
||||
Routes to the **main agent session** (shared history with this user).
|
||||
|
||||
### Group Messages
|
||||
```
|
||||
telegram-gramjs:{accountId}:group:{groupId}
|
||||
```
|
||||
Routes to an **isolated session** per group (separate context).
|
||||
|
||||
### Channel Messages
|
||||
**Not yet supported.** Channel messages are skipped in Phase 1.
|
||||
|
||||
## Features
|
||||
|
||||
### ✅ Supported (Phase 1)
|
||||
|
||||
- ✅ DM messages (send and receive)
|
||||
- ✅ Group messages (send and receive)
|
||||
- ✅ Reply context (reply to specific messages)
|
||||
- ✅ Text messages
|
||||
- ✅ Command detection (`/start`, `/help`, etc.)
|
||||
- ✅ Session persistence
|
||||
- ✅ Multi-account support
|
||||
- ✅ Security policies (allowFrom, dmPolicy, groupPolicy)
|
||||
|
||||
### ⏳ Coming Soon (Phase 2)
|
||||
|
||||
- ⏳ Media support (photos, videos, files)
|
||||
- ⏳ Voice messages
|
||||
- ⏳ Stickers and GIFs
|
||||
- ⏳ Reactions
|
||||
- ⏳ Message editing and deletion
|
||||
- ⏳ Forward detection
|
||||
|
||||
### ⏳ Future (Phase 3)
|
||||
|
||||
- ⏳ Channel messages
|
||||
- ⏳ Secret chats
|
||||
- ⏳ Poll creation
|
||||
- ⏳ Inline queries
|
||||
- ⏳ Custom entity parsing (mentions, hashtags, URLs)
|
||||
|
||||
## Rate Limits
|
||||
|
||||
Telegram has **strict rate limits** for user accounts:
|
||||
|
||||
- **~20 messages per minute** per chat
|
||||
- **~40-50 messages per minute** globally
|
||||
- **Flood wait errors** trigger cooldown (can be minutes or hours)
|
||||
|
||||
**Best practices:**
|
||||
- Don't spam messages rapidly
|
||||
- Respect `FLOOD_WAIT` errors (the client will auto-retry)
|
||||
- Use batching for multiple messages
|
||||
- Consider using Bot API for high-volume scenarios
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "API_ID_INVALID" or "API_HASH_INVALID"
|
||||
- Check your credentials at https://my.telegram.org/apps
|
||||
- Ensure `apiId` is a **number** (not string)
|
||||
- Ensure `apiHash` is a **string** (not number)
|
||||
|
||||
### "PHONE_NUMBER_INVALID"
|
||||
- Phone number must start with `+`
|
||||
- Include country code
|
||||
- Remove spaces and dashes
|
||||
- Example: `+12025551234`
|
||||
|
||||
### "SESSION_PASSWORD_NEEDED"
|
||||
- Your account has 2FA enabled
|
||||
- Enter your 2FA password when prompted
|
||||
- Check Telegram Settings → Privacy → Two-Step Verification
|
||||
|
||||
### "AUTH_KEY_UNREGISTERED"
|
||||
- Your session expired or was terminated
|
||||
- Re-run `openclaw setup telegram-gramjs` to re-authenticate
|
||||
|
||||
### "FLOOD_WAIT_X"
|
||||
- You hit Telegram's rate limit
|
||||
- Wait X seconds before retrying
|
||||
- GramJS handles this automatically with exponential backoff
|
||||
|
||||
### Connection Issues
|
||||
- Check internet connection
|
||||
- Verify Telegram isn't blocked on your network
|
||||
- Try restarting the gateway
|
||||
- Check logs: `openclaw logs --channel=telegram-gramjs`
|
||||
|
||||
### Session Lost After Restart
|
||||
- Ensure `sessionString` is saved in config
|
||||
- Check file permissions on config file
|
||||
- Verify encryption key is consistent
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### ✅ Do
|
||||
- ✅ Store session strings encrypted
|
||||
- ✅ Use `dmPolicy: "pairing"` for new contacts
|
||||
- ✅ Use `allowFrom` to restrict access
|
||||
- ✅ Regularly review active sessions in Telegram
|
||||
- ✅ Use separate accounts for different purposes
|
||||
- ✅ Enable 2FA on your Telegram account
|
||||
|
||||
### ❌ Don't
|
||||
- ❌ Share session strings publicly
|
||||
- ❌ Commit session strings to git
|
||||
- ❌ Use `groupPolicy: "open"` in public groups
|
||||
- ❌ Run on untrusted servers
|
||||
- ❌ Reuse API credentials across multiple machines
|
||||
|
||||
## Migration from Bot API
|
||||
|
||||
If you're currently using the Telegram Bot API (`telegram` channel), you can run both simultaneously:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
// Bot API (existing)
|
||||
telegram: {
|
||||
enabled: true,
|
||||
botToken: "123:abc"
|
||||
},
|
||||
|
||||
// GramJS (new)
|
||||
telegramGramjs: {
|
||||
enabled: true,
|
||||
apiId: 123456,
|
||||
apiHash: "hash"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Routing:**
|
||||
- Bot token messages → `telegram` channel
|
||||
- User account messages → `telegram-gramjs` channel
|
||||
- No conflicts (separate accounts, separate sessions)
|
||||
|
||||
## Examples
|
||||
|
||||
### Personal Assistant Setup
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
telegramGramjs: {
|
||||
enabled: true,
|
||||
apiId: 123456,
|
||||
apiHash: "your_hash",
|
||||
phoneNumber: "+12025551234",
|
||||
dmPolicy: "pairing",
|
||||
groupPolicy: "closed", // No groups
|
||||
sessionString: "..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Team Bot in Groups
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
telegramGramjs: {
|
||||
enabled: true,
|
||||
apiId: 123456,
|
||||
apiHash: "your_hash",
|
||||
phoneNumber: "+12025551234",
|
||||
dmPolicy: "closed", // No DMs
|
||||
groupPolicy: "allowlist",
|
||||
groupAllowFrom: [
|
||||
"-1001234567890", // Team group
|
||||
"-1009876543210" // Project group
|
||||
],
|
||||
groups: {
|
||||
"-1001234567890": {
|
||||
requireMention: true,
|
||||
allowFrom: ["@alice", "@bob"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Account with Family + Work
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
telegramGramjs: {
|
||||
enabled: true,
|
||||
accounts: {
|
||||
family: {
|
||||
name: "Family Account",
|
||||
apiId: 123456,
|
||||
apiHash: "hash1",
|
||||
phoneNumber: "+12025551234",
|
||||
dmPolicy: "allowlist",
|
||||
allowFrom: ["+15555551111", "+15555552222"], // Family members
|
||||
groupPolicy: "closed"
|
||||
},
|
||||
work: {
|
||||
name: "Work Account",
|
||||
apiId: 789012,
|
||||
apiHash: "hash2",
|
||||
phoneNumber: "+15551234567",
|
||||
dmPolicy: "allowlist",
|
||||
allowFrom: ["@boss", "@coworker1"],
|
||||
groupPolicy: "allowlist",
|
||||
groupAllowFrom: ["-1001111111111"] // Work group
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Connection Settings
|
||||
```json5
|
||||
{
|
||||
connectionRetries: 5,
|
||||
connectionTimeout: 30000, // 30 seconds
|
||||
floodSleepThreshold: 60, // Auto-sleep on flood wait < 60s
|
||||
useIPv6: false,
|
||||
deviceModel: "openclaw",
|
||||
systemVersion: "1.0.0",
|
||||
appVersion: "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
### Message Settings
|
||||
```json5
|
||||
{
|
||||
historyLimit: 100, // Max messages to fetch on poll
|
||||
mediaMaxMb: 10, // Max media file size (Phase 2)
|
||||
textChunkLimit: 4096 // Max text length per message
|
||||
}
|
||||
```
|
||||
|
||||
### Capabilities
|
||||
```json5
|
||||
{
|
||||
capabilities: [
|
||||
"sendMessage",
|
||||
"receiveMessage",
|
||||
"replyToMessage",
|
||||
"deleteMessage", // Phase 2
|
||||
"editMessage", // Phase 2
|
||||
"sendMedia", // Phase 2
|
||||
"downloadMedia" // Phase 2
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Logs and Debugging
|
||||
|
||||
### Enable Debug Logs
|
||||
```bash
|
||||
export DEBUG=telegram-gramjs:*
|
||||
openclaw gateway start
|
||||
```
|
||||
|
||||
### Check Session Status
|
||||
```bash
|
||||
openclaw status telegram-gramjs
|
||||
```
|
||||
|
||||
### View Recent Messages
|
||||
```bash
|
||||
openclaw logs --channel=telegram-gramjs --limit=50
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- **GramJS Documentation:** https://gram.js.org/
|
||||
- **GramJS GitHub:** https://github.com/gram-js/gramjs
|
||||
- **Telegram API Docs:** https://core.telegram.org/methods
|
||||
- **MTProto Protocol:** https://core.telegram.org/mtproto
|
||||
- **Get API Credentials:** https://my.telegram.org/apps
|
||||
- **openclaw Issue #937:** https://github.com/openclaw/openclaw/issues/937
|
||||
|
||||
## Support
|
||||
|
||||
For issues specific to the GramJS channel:
|
||||
- Check GitHub issues: https://github.com/openclaw/openclaw/issues
|
||||
- Join the community: https://discord.gg/openclaw
|
||||
- Report bugs: `openclaw report --channel=telegram-gramjs`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-01-30
|
||||
**Version:** Phase 1 (Beta)
|
||||
**Tested Platforms:** macOS, Linux
|
||||
**Dependencies:** GramJS 2.24.15+, Node.js 18+
|
||||
Reference in new issue
Block a user