28adc22388
Co-authored-by: Kai <noreply@gtb.ai> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Cameron <cameron@pfiffer.org>
252 lines
7.4 KiB
Markdown
252 lines
7.4 KiB
Markdown
# Telegram MTProto (User Account) Setup Guide
|
|
|
|
This guide explains how to run LettaBot as a Telegram **user account** instead of a bot. This uses the MTProto protocol via TDLib, giving you full user capabilities.
|
|
|
|
## Overview: Bot API vs MTProto
|
|
|
|
| Feature | Bot API | MTProto (User) |
|
|
|---------|---------|----------------|
|
|
| **Setup** | Simple (BotFather token) | Phone + API credentials |
|
|
| **DM users first** | No (must wait for user) | Yes |
|
|
| **File size limit** | 50 MB | 2 GB |
|
|
| **Privacy mode** | Restricted in groups | Full access |
|
|
| **Rate limits** | 30 req/sec | Higher limits |
|
|
| **Appears as** | Bot account | Regular user |
|
|
|
|
**Choose MTProto if you need:** User-first DMs, larger files, or full group access.
|
|
|
|
## Prerequisites
|
|
|
|
1. **Telegram account** with a phone number
|
|
2. **API credentials** from my.telegram.org (see below)
|
|
3. **LettaBot** installed with dependencies
|
|
|
|
## Getting API Credentials
|
|
|
|
1. Go to [my.telegram.org](https://my.telegram.org)
|
|
2. Log in with your phone number
|
|
3. Click **"API development tools"**
|
|
4. Fill in the form:
|
|
- **App title**: LettaBot (or any name)
|
|
- **Short name**: lettabot
|
|
- **Platform**: Desktop
|
|
- **Description**: AI assistant
|
|
5. Click **"Create application"**
|
|
6. Note your **API ID** and **API Hash**
|
|
|
|
> **Security Note**: Keep your API credentials secret. Never commit them to git or share them publicly. They are tied to your Telegram account.
|
|
|
|
## Configuration
|
|
|
|
Add these to your `.env` file:
|
|
|
|
```bash
|
|
# Telegram MTProto User Mode
|
|
TELEGRAM_PHONE_NUMBER=+1234567890
|
|
TELEGRAM_API_ID=12345678
|
|
TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890
|
|
|
|
# Optional: Custom database directory (default: ./data/telegram-mtproto)
|
|
# TELEGRAM_MTPROTO_DB_DIR=./data/telegram-mtproto
|
|
|
|
# DM policy (same as bot mode)
|
|
TELEGRAM_DM_POLICY=pairing
|
|
# TELEGRAM_ALLOWED_USERS=123456789,987654321
|
|
```
|
|
|
|
**Important**: Do NOT set `TELEGRAM_BOT_TOKEN` at the same time. You must choose one mode or the other.
|
|
|
|
## First Run Authentication
|
|
|
|
On first run, you'll see prompts for authentication:
|
|
|
|
```
|
|
$ lettabot server
|
|
|
|
[Telegram MTProto] Starting authentication...
|
|
[Telegram MTProto] Sending phone number...
|
|
[Telegram MTProto] Verification code sent to your Telegram app
|
|
Enter verification code: █
|
|
```
|
|
|
|
1. Open your Telegram app on another device
|
|
2. You'll receive a login code message
|
|
3. Enter the code in the terminal
|
|
|
|
If you have 2FA enabled:
|
|
|
|
```
|
|
[Telegram MTProto] 2FA password required
|
|
Enter 2FA password: █
|
|
```
|
|
|
|
Enter your Telegram 2FA password.
|
|
|
|
On success:
|
|
|
|
```
|
|
[Telegram MTProto] Authenticated successfully!
|
|
[Telegram MTProto] Session saved to ./data/telegram-mtproto/
|
|
```
|
|
|
|
## Subsequent Runs
|
|
|
|
After initial authentication, the session is saved. You won't need to enter codes again:
|
|
|
|
```
|
|
$ lettabot server
|
|
|
|
[Telegram MTProto] Starting adapter...
|
|
[Telegram MTProto] Authenticated successfully!
|
|
[Telegram MTProto] Session saved to ./data/telegram-mtproto/
|
|
[Telegram MTProto] Adapter started
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Phone number banned" or "PHONE_NUMBER_BANNED"
|
|
|
|
Your phone number may be flagged by Telegram. This can happen if:
|
|
- The number was recently used for spam
|
|
- Too many failed login attempts
|
|
- Account previously terminated
|
|
|
|
**Solution**: Contact Telegram support or use a different number.
|
|
|
|
### "FLOOD_WAIT_X" errors
|
|
|
|
You're sending too many requests. TDLib handles this automatically by waiting, but you'll see delay messages in logs.
|
|
|
|
**Solution**: This is normal - TDLib will retry automatically.
|
|
|
|
### Session keeps asking for code
|
|
|
|
The session database may be corrupted.
|
|
|
|
**Solution**: Delete the database directory and re-authenticate:
|
|
```bash
|
|
rm -rf ./data/telegram-mtproto
|
|
lettabot server
|
|
```
|
|
|
|
### "API_ID_INVALID" or "API_HASH_INVALID"
|
|
|
|
Your API credentials are incorrect.
|
|
|
|
**Solution**: Double-check the values from my.telegram.org.
|
|
|
|
### Database grows very large
|
|
|
|
TDLib caches data locally, which can grow to 50+ MB quickly.
|
|
|
|
**Solution**: This is normal. For very long sessions, you may want to periodically clear the database and re-authenticate.
|
|
|
|
## Switching Between Bot and MTProto
|
|
|
|
To switch modes:
|
|
|
|
1. **Stop LettaBot**
|
|
2. **Edit `.env`**:
|
|
- For Bot mode: Set `TELEGRAM_BOT_TOKEN`, remove/comment `TELEGRAM_PHONE_NUMBER`
|
|
- For MTProto: Set `TELEGRAM_PHONE_NUMBER` + API credentials, remove/comment `TELEGRAM_BOT_TOKEN`
|
|
3. **Start LettaBot**
|
|
|
|
You cannot run both modes simultaneously.
|
|
|
|
## Security Notes
|
|
|
|
1. **API credentials**: Treat like passwords. They can be used to access your Telegram account.
|
|
|
|
2. **Session files**: The `./data/telegram-mtproto/` directory contains your authenticated session. Anyone with these files can act as your Telegram account.
|
|
|
|
3. **gitignore**: The session directory is automatically gitignored. Never commit it.
|
|
|
|
4. **Account security**: Consider using a dedicated phone number for bots rather than your personal number.
|
|
|
|
5. **Logout**: To revoke the session:
|
|
- Go to Telegram Settings → Devices
|
|
- Find "TDLib" or the session
|
|
- Click "Terminate Session"
|
|
|
|
## Using with DM Policy
|
|
|
|
MTProto mode supports the same DM policies as bot mode:
|
|
|
|
- **pairing** (default): Unknown users must be approved before chatting
|
|
- **allowlist**: Only users in `TELEGRAM_ALLOWED_USERS` can message
|
|
- **open**: Anyone can message
|
|
|
|
```bash
|
|
# Pairing mode (recommended for most users)
|
|
TELEGRAM_DM_POLICY=pairing
|
|
|
|
# Or pre-approve specific users
|
|
TELEGRAM_ALLOWED_USERS=123456789,987654321
|
|
```
|
|
|
|
### Admin Notifications for Pairing
|
|
|
|
When using pairing mode, you can set up an admin chat to receive pairing requests:
|
|
|
|
```bash
|
|
# Your Telegram user ID or a group chat ID for admin notifications
|
|
TELEGRAM_ADMIN_CHAT_ID=137747014
|
|
```
|
|
|
|
**How it works:**
|
|
|
|
1. Unknown user sends a message
|
|
2. User sees: *"Your request has been passed on to the admin."*
|
|
3. Admin chat receives notification with username and user ID
|
|
4. Admin replies **"approve"** or **"deny"** to the notification
|
|
5. Both user and admin get confirmation
|
|
|
|
**Approve/Deny keywords:**
|
|
- Approve: `approve`, `yes`, `y`
|
|
- Deny: `deny`, `no`, `n`, `reject`
|
|
|
|
If no admin chat is configured, pairing codes are logged to the console instead.
|
|
|
|
**Pairing request behavior:**
|
|
- Repeated messages from the same unapproved user do not create duplicate admin notifications.
|
|
- If the pending pairing queue is full, the user gets: *"Too many pending pairing requests. Please try again later."*
|
|
|
|
## Group Chat Policy
|
|
|
|
Since MTProto gives you full group access, you need to control when the agent responds in groups. The **group policy** determines this:
|
|
|
|
| Policy | Behavior |
|
|
|--------|----------|
|
|
| **mention** | Only respond when @mentioned by username |
|
|
| **reply** | Only respond when someone replies to agent's message |
|
|
| **both** | Respond to mentions OR replies (default) |
|
|
| **off** | Never respond in groups, DMs only |
|
|
|
|
```bash
|
|
# Only respond when @mentioned (recommended for busy groups)
|
|
TELEGRAM_GROUP_POLICY=mention
|
|
|
|
# Only respond to replies
|
|
TELEGRAM_GROUP_POLICY=reply
|
|
|
|
# Respond to either mentions or replies (default)
|
|
TELEGRAM_GROUP_POLICY=both
|
|
|
|
# Never respond in groups
|
|
TELEGRAM_GROUP_POLICY=off
|
|
```
|
|
|
|
**Note**: Group policy does NOT affect DMs - direct messages always work based on your DM policy.
|
|
|
|
### How Mentions Work
|
|
|
|
The agent responds when:
|
|
- Someone types `@yourusername` in their message
|
|
- Someone uses Telegram's mention feature (clicking your name in the member list)
|
|
|
|
### How Reply Detection Works
|
|
|
|
The agent tracks messages it sends. When someone replies to one of those messages (using Telegram's reply feature), the agent will respond.
|
|
|
|
**Tip**: For busy groups, use `mention` policy. For small groups or channels, `both` works well.
|