lettabot/docs/telegram-mtproto-setup.md

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
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:

# 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:

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

# 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:

# 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

# 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.