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:
```bash
git clone https://github.com/yourusername/telegram-marketing-agent.git
cd telegram-marketing-agent
```

2. Create environment file:
```bash
cp .env.example .env
```

3. Update `.env` with your configurations:
```env
# 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:
```bash
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:
```bash
# API Gateway
cd services/api-gateway
npm install

# Orchestrator
cd ../orchestrator
npm install

# Continue for all services...
```

2. Start MongoDB and Redis:
```bash
# Using Docker
docker run -d -p 27017:27017 --name mongodb mongo
docker run -d -p 6379:6379 --name redis redis
```

3. Start services:
```bash
# 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:
```bash
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

```javascript
// 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

```javascript
// 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](./README.md)
- [API Documentation](./api/README.md)
- [Advanced Features](./ADVANCED.md)
- [Deployment Guide](./DEPLOYMENT.md)

## Support

- GitHub Issues: [Report bugs](https://github.com/yourusername/telegram-marketing-agent/issues)
- Documentation: [Full docs](./docs)
- Community: [Join Discord](https://discord.gg/yourinvite)

## Quick API Reference

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

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

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

For more examples, visit the [API Examples](./api/examples.md) page.