📱 Telegram Service (Python)

یک سرویس مستقل پایتون برای مدیریت اتصالات و پیام‌های تلگرام با استفاده از Telethon

✨ ویژگی‌ها

• 🔐 اتصال به تلگرام با QR Code
• 📱 پشتیبانی از Phone Code و 2FA
• 💬 دریافت و ارسال پیام‌های تلگرام
• 🔄 مدیریت Session های متعدد به صورت همزمان
• 🗄️ ذخیره تمام داده‌ها در MongoDB (sessions, messages, events)
• ⚡ عملیات Async با Motor (MongoDB async driver)
• 🔌 Reconnect خودکار
• 🐳 Docker Support
• 📊 RESTful API با FastAPI
• 📈 آمار و گزارش‌گیری از پیام‌ها

📋 پیش‌نیازها

• Python 3.11+
• MongoDB 5.0+ (برای ذخیره تمام داده‌ها)
• Telegram API Credentials (API ID & API Hash)
• Redis (برای caching)
• Docker & Docker Compose (برای deployment)

🚀 نصب و راه‌اندازی

1. دریافت Telegram API Credentials

1. به https://my.telegram.org بروید
2. وارد شوید و به قسمت "API development tools" بروید
3. یک Application جدید بسازید
4. API ID و API Hash را کپی کنید

2. نصب به صورت Local

# کلون پروژه
git clone <repository-url>
cd telegram-crawler-python

# ایجاد virtual environment
python -m venv venv
source venv/bin/activate  # در Windows: venv\Scripts\activate

# نصب dependencies
pip install -r requirements.txt

# کپی و تنظیم environment variables
cp .env.example .env
# ویرایش .env و تنظیم مقادیر

3. تنظیم فایل .env

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
HOST=0.0.0.0
PORT=8000
DEBUG=False
DATABASE_URL=sqlite:///./sessions.db
MONGODB_URL=mongodb://localhost:27017
MONGODB_DATABASE=telegram_serviceackend.com
WEBHOOK_SECRET_TOKEN=your-secret-token
API_SECRET_KEY=your-api-secret-key

4. اجرای سرویس

روش اول: اجرای مستقیم

python -m app.main
# یا
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

روش دوم: Docker

# Build و اجرا
docker-compose up -d

# مشاهده logs
docker-compose logs -f

# متوقف کردن
docker-compose down

📖 استفاده از API

Base URL

http://localhost:8000

Authentication

تمام درخواست‌ها نیاز به API Key دارند که باید در header ارسال شود:

X-API-Key: your-api-secret-key

Endpoints

1. درخواست QR Code

POST /api/telegram/request-qr

Request:

{
  "agent_id": 123
}

Response:

{
  "success": true,
  "session_id": "uuid-v4-session-id",
  "qr_code": "data:image/png;base64,iVBORw0KG...",
  "expires_in": 300
}

2. تایید کد

POST /api/telegram/verify-code

Request:

{
  "session_id": "uuid-v4-session-id",
  "code": "12345"
}

3. تایید رمز عبور (2FA)

POST /api/telegram/verify-password

Request:

{
  "session_id": "uuid-v4-session-id",
  "password": "my-password"
}

4. قطع اتصال

POST /api/telegram/disconnect

Request:

{
  "session_id": "uuid-v4-session-id"
}

5. بررسی وضعیت

GET /api/telegram/status/{session_id}

6. ارسال پیام

POST /api/telegram/send-message

Request:

{
  "session_id": "uuid-v4-session-id",
  "chat_id": 123456789,
  "message": "سلام، چطور می‌تونم کمکتون کنم؟",
  "reply_to": null
}

مثال استفاده با cURL

# درخواست QR Code
curl -X POST "http://localhost:8000/api/telegram/request-qr" \
  -H "X-API-Key: your-api-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 123}'

# بررسی وضعیت
curl -X GET "http://localhost:8000/api/telegram/status/{session_id}" \
  -H "X-API-Key: your-api-secret-key"

# ارسال پیام
curl -X POST "http://localhost:8000/api/telegram/send-message" \
  -H "X-API-Key: your-api-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "uuid",
    "chat_id": 123456789,
    "message": "سلام"
  }'

# دریافت پیام‌ها
curl -X GET "http://localhost:8000/api/telegram/messages/{session_id}?limit=50" \
  -H "X-API-Key: your-api-secret-key"

# دریافت آمار
curl -X GET "http://localhost:8000/api/telegram/agent-stats/123" \
  -H "X-API-Key: your-api-secret-key"

مثال استفاده با Python

import httpx

API_BASE_URL = "http://localhost:8000"
API_KEY = "your-api-secret-key"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# درخواست QR Code

# دریافت پیام‌ها
res🗄️ ساختار MongoDB

### Collections

#### 1. messages
```javascript
{
  "_id": ObjectId,
  "session_id": "uuid",
  "agent_id": 123,
  "message_id": 456,
  "chat_id": 789,
  "from_user": {
    "id": 987654321,
    "first_name": "علی",
    "last_name": "محمدی",
    "username": "ali_m",
    "phone": "+989123456789"
  },
  "chat": {
    "id": 789,
    "type": "private"
  },
  "text": "سلام",
  "date": "2025-12-20T10:30:00Z",
  "reply_to_message_id": null,
  "is_outgoing": false,
  "created_at": ISODate("2025-12-20T10:30:00Z")
}

2. events

{
  "_id": ObjectId,
  "session_id": "uuid",
  "agent_id": 123,
  "event_type": "new_message",
  "metadata": {
    "message_id": 456,
    "chat_id": 789
  },
  "created_at": ISODate("2025-12-20T10:30:00Z")
}

Indexes

• messages: session_id, agent_id, chat_id, message_id, date
• events: session_id, event_type, created_at

📊 مثال Query ها

دریافت همه پیام‌های یک Agent

db.messages.find({ "agent_id": 123 }).sort({ "date": -1 }).limit(100)

دریافت تاریخچه چت خاص

db.messages.find({ 
  "session_id": "uuid",
  "chat_id": 789 
}).sort({ "date": -1 })

mongodb.py # MongoDB service

آمار پیام‌ها

db.messages.aggregate([
  { $match: { "agent_id": 123 } },
  { $group: { 
    _id: "$chat_id",
    count: { $sum: 1 }
  }}
])

🪝 تغییر از Webhook به MongoDB

این سرویس به جای ارسال webhook به Laravel، تمام پیام‌ها و رویدادها را در MongoDB ذخیره می‌کند. مزایا:

✅ Performance بهتر: ذخیره مستقیم در دیتابیس سریع‌تر از HTTP request است ✅ Reliability: در صورت مشکل شبکه، داده از دست نمی‌رود ✅ Query آسان: می‌توانید به راحتی پیام‌ها را جستجو و فیلتر کنید ✅ Scalability: MongoDB برای حجم بالای داده مناسب است ✅ Offline Access: می‌توانید بدون نیاز به Laravel به داده‌ها دسترسی داشته باشید

اگر نیاز به ارسال داده به Laravel دارید، می‌توانید از طریق API endpoints دریافت کنید یا یک worker service اضافه کنید که داده‌ها را از MongoDB بخواند و به Laravel بفرستد. "from": { "id": 987654321, "first_name": "علی", "last_name": "محمدی", "username": "ali_m", "phone": "+989123456789" }, "chat": { "id": 987654321, "type": "private" }, "text": "سلام", "date": "2025-12-20T10:30:00Z", "reply_to_message_id": null } }

## 📁 ساختار پروژه

telegram-crawler-python/ ├── app/ │ ├── init.py │ ├── main.py # FastAPI application │ ├── config.py # تنظیمات │ ├── api/ │ │ ├── init.py │ │ ├── routes.py # API endpoints │ │ └── schemas.py # Pydantic schemas │ ├── models/ │ │ ├── init.py │ │ └── session.py # Database models │ ├── services/ │ │ ├── init.py │ │ ├── telegram.py # Telegram client management │ │ └── webhook.py # Webhook sender │ └── utils/ │ ├── init.py │ ├── qr_generator.py # QR code generator │ └── session_manager.py # Session management ├── sessions/ # Session files ├── .env.example ├── .gitignore ├── docker-compose.yml ├── Dockerfile ├── requirements.txt ├── docs.md # مستندات کامل └── README.md # این فایل

## 🔧 توسعه و تست

### اجرای در حالت Development

```bash
# با reload خودکار
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

مشاهده Swagger UI

پس از اجرای سرویس، به آدرس زیر بروید:

http://localhost:8000/docs

مشاهده ReDoc

http://localhost:8000/redoc

🐛 عیب‌یابی

مشکلات رایج

1. خطای "Session not found"

   • مطمئن شوید session_id صحیح است
   • بررسی کنید که Session در دیتابیس موجود باشد

2. خطای "Invalid API key"

   • API_SECRET_KEY در .env را بررسی کنید
   • Header X-API-Key را در درخواست قرار دهید

3. خطای "FloodWaitError"

   • تلگرام محدودیت تعداد درخواست دارد
   • چند دقیقه صبر کنید و دوباره تلاش کنید

4. Session منقضی می‌شود

   • Session files را backup کنید
   • از Volume در Docker استفاده کنید

مشاهده Logs

# Docker
docker-compose logs -f telegram-service

# Local
# Logs در console نمایش داده می‌شوند

📊 Monitoring

Health Check

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "active_sessions": 5
}

🔒 امنیت

توصیه‌های امنیتی

1. ✅ API_SECRET_KEY قوی استفاده کنید
2. ✅ HTTPS برای Production
3. ✅ محدود کردن CORS
4. ✅ Firewall برای محدود کردن دسترسی
5. ✅ Backup منظم از Session files
6. ✅ استفاده از Environment Variables

محدود کردن CORS (Production)

در فایل app/main.py:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://your-frontend.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

🚢 Deployment

Docker Production

# Build image
docker build -t telegram-service:latest .

# Run container
docker run -d \
  --name telegram-service \
  -p 8000:8000 \
  --env-file .env \
  -v $(pwd)/sessions:/app/sessions \
  telegram-service:latest

با Docker Compose

docker-compose -f docker-compose.yml up -d

📝 Changelog

Version 1.0.0 (2025-12-20)

• ✅ پیاده‌سازی اولیه
• ✅ اتصال به تلگرام با QR Code
• ✅ مدیریت Session ها
• ✅ دریافت و ارسال پیام
• ✅ Webhook به Laravel
• ✅ Docker Support

🤝 مشارکت

برای مشارکت در پروژه:

1. Fork کنید
2. یک Branch جدید بسازید (git checkout -b feature/AmazingFeature)
3. تغییرات را Commit کنید (git commit -m 'Add some AmazingFeature')
4. Push کنید (git push origin feature/AmazingFeature)
5. یک Pull Request باز کنید

📄 License

این پروژه تحت لایسنس MIT است.

📞 پشتیبانی

برای سوالات و مشکلات، Issue باز کنید یا به تیم توسعه مراجعه کنید.

🔗 لینک‌های مفید

• Telethon Documentation
• FastAPI Documentation
• Telegram API Documentation
• مستندات کامل پروژه

---

ساخته شده با ❤️ برای Laravel Backend Integration