telegram-management-system/marketing-agent/docs/QUICKSTART.md

Quick Start Guide

Get started with the Telegram Marketing Agent System in 5 minutes.

Prerequisites

• Docker and Docker Compose installed
• Node.js 18+ (for local development)
• MongoDB and Redis (or use Docker)
• Telegram account with API credentials

Installation

Option 1: Docker Compose (Recommended)

1. Clone the repository:

git clone https://github.com/yourusername/telegram-marketing-agent.git
cd telegram-marketing-agent

2. Create environment file:

cp .env.example .env

3. Update .env with your configurations:

# Telegram API
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash

# Claude API (optional)
CLAUDE_API_KEY=your_claude_key

# Database
MONGODB_URI=mongodb://mongodb:27017/marketing_agent
REDIS_URL=redis://redis:6379

# Security
JWT_SECRET=your-secret-key-change-this

4. Start all services:

docker-compose up -d

5. Access the application:

• Frontend: http://localhost:8080
• API Gateway: http://localhost:3000
• API Docs: http://localhost:3000/api-docs

Option 2: Local Development

1. Install dependencies for each service:

# API Gateway
cd services/api-gateway
npm install

# Orchestrator
cd ../orchestrator
npm install

# Continue for all services...

2. Start MongoDB and Redis:

# Using Docker
docker run -d -p 27017:27017 --name mongodb mongo
docker run -d -p 6379:6379 --name redis redis

3. Start services:

# In separate terminals
cd services/api-gateway && npm start
cd services/orchestrator && npm start
cd services/gramjs-adapter && npm start
# Continue for all services...

4. Start frontend:

cd frontend
npm install
npm run dev

First Steps

1. Login

Default credentials:

• Username: admin
• Password: password123

2. Connect Telegram Account

1. Go to Settings → Accounts
2. Click Add Account
3. Enter your phone number
4. Follow the verification process

3. Import Users

1. Go to Users → Import
2. Download the sample CSV template
3. Fill in user data
4. Upload and import

4. Create Your First Campaign

1. Go to Campaigns → Create New
2. Fill in campaign details:
   • Name: "Welcome Campaign"
   • Type: "Message"
   • Target: Select imported users
3. Create message:
   • Use template or write custom
   • Add personalization tags
4. Review and save as draft

5. Test Campaign

1. Select a small test group
2. Click Test Campaign
3. Review test results
4. Make adjustments if needed

6. Execute Campaign

1. Click Execute Campaign
2. Monitor real-time progress
3. View analytics dashboard

Common Tasks

Creating User Segments

// API Example
POST /api/v1/segments
{
  "name": "Active Users",
  "criteria": [{
    "field": "engagement.lastActivity",
    "operator": "greater_than",
    "value": "7d"
  }]
}

Scheduling Recurring Campaigns

1. Create campaign
2. Go to Schedules → Create Schedule
3. Select campaign and set recurrence:
   • Daily at 10 AM
   • Weekly on Mondays
   • Monthly on 1st

Setting Up Webhooks

// API Example
POST /api/v1/webhooks
{
  "name": "Campaign Events",
  "url": "https://your-server.com/webhooks",
  "events": ["campaign.completed", "campaign.failed"]
}

Troubleshooting

Cannot Connect to Telegram

1. Check API credentials in .env
2. Ensure phone number format: +1234567890
3. Check firewall/proxy settings
4. View logs: docker-compose logs gramjs-adapter

Campaign Not Sending

1. Check account connection status
2. Verify rate limits aren't exceeded
3. Check user permissions
4. Review compliance settings

Performance Issues

1. Check Redis connection
2. Monitor resource usage
3. Adjust rate limiting settings
4. Scale services if needed

Best Practices

1. Test First: Always test campaigns on small groups
2. Rate Limiting: Respect Telegram's rate limits
3. Personalization: Use tags for better engagement
4. Timing: Schedule during user's active hours
5. Compliance: Follow local regulations
6. Monitoring: Set up alerts for failures

Next Steps

• Read Full Documentation
• API Documentation
• Advanced Features
• Deployment Guide

Support

• GitHub Issues: Report bugs
• Documentation: Full docs
• Community: Join Discord

Quick API Reference

Authentication

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password123"}'

List Campaigns

curl -X GET http://localhost:3000/api/v1/campaigns \
  -H "Authorization: Bearer <token>"

Execute Campaign

curl -X POST http://localhost:3000/api/v1/campaigns/<id>/execute \
  -H "Authorization: Bearer <token>"

For more examples, visit the API Examples page.