doudou/telegram-management-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Telegram Management System
Some checks failed
Deploy / deploy (push) Has been cancelled
Details

Browse Source 
Full-stack web application for Telegram management
- Frontend: Vue 3 + Vben Admin
- Backend: NestJS
- Features: User management, group broadcast, statistics

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
你的用户名
2025-11-04 15:37:50 +08:00
commit 237c7802e5
3674 changed files with 525172 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
marketing-agent/docs/QUICKSTART.md Normal file
View File

@@ -0,0 +1,243 @@
# 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.

449
marketing-agent/docs/TESTING.md Normal file
View File

@@ -0,0 +1,449 @@
# Testing Documentation
Comprehensive testing guide for the Telegram Marketing Agent System.
## Table of Contents
- [Testing Strategy](#testing-strategy)
- [Test Types](#test-types)
- [Running Tests](#running-tests)
- [Writing Tests](#writing-tests)
- [CI/CD Integration](#cicd-integration)
- [Coverage Goals](#coverage-goals)
- [Best Practices](#best-practices)
## Testing Strategy
Our testing strategy follows the Testing Pyramid approach:
```
/\
/E2E\ (5-10%)
/------\
/Integration\ (20-30%)
/------------\
/ Unit Tests \ (60-70%)
/-----------------\
```
### Test Categories
1. **Unit Tests**: Test individual functions, methods, and components in isolation
2. **Integration Tests**: Test interactions between components and services
3. **End-to-End Tests**: Test complete user workflows and scenarios
## Test Types
### Unit Tests
Located in `tests/unit/`, these tests cover:
- Service methods
- Utility functions
- Middleware logic
- Model validations
- Helper functions
Example structure:
```
tests/unit/
├── services/
│ ├── api-gateway/
│ │ ├── middleware/
│ │ │ ├── auth.test.js
│ │ │ └── rateLimiter.test.js
│ │ └── utils/
│ └── orchestrator/
│ └── campaignService.test.js
└── utils/
```
### Integration Tests
Located in `tests/integration/`, these tests cover:
- API endpoint functionality
- Database operations
- Service interactions
- External API mocking
Example structure:
```
tests/integration/
├── api/
│ ├── auth.test.js
│ ├── campaigns.test.js
│ └── users.test.js
└── services/
```
### End-to-End Tests
Located in `tests/e2e/`, these tests cover:
- Complete user workflows
- Multi-service interactions
- Real-world scenarios
Example structure:
```
tests/e2e/
├── campaigns/
│ └── campaignWorkflow.test.js
└── users/
└── userOnboarding.test.js
```
## Running Tests
### Prerequisites
```bash
# Install dependencies
npm install
# For each service
cd services/<service-name>
npm install
```
### All Tests
```bash
npm test
```
### Unit Tests Only
```bash
npm run test:unit
```
### Integration Tests Only
```bash
npm run test:integration
```
### E2E Tests Only
```bash
npm run test:e2e
```
### Watch Mode (for development)
```bash
npm run test:watch
```
### Coverage Report
```bash
npm run test:coverage
```
### Specific Test File
```bash
npx jest tests/unit/services/orchestrator/campaignService.test.js
```
### Test Pattern
```bash
npx jest --testNamePattern="should create campaign"
```
## Writing Tests
### Unit Test Example
```javascript
import { jest } from '@jest/globals';
import CampaignService from '../../../../services/orchestrator/src/services/campaignService.js';
import { createCampaign } from '../../../helpers/factories.js';
describe('CampaignService', () => {
let campaignService;
let mockDependency;
beforeEach(() => {
// Setup mocks
mockDependency = {
method: jest.fn()
};
campaignService = new CampaignService(mockDependency);
jest.clearAllMocks();
});
describe('createCampaign', () => {
it('should create a new campaign', async () => {
// Arrange
const campaignData = createCampaign();
mockDependency.method.mockResolvedValue({ success: true });
// Act
const result = await campaignService.createCampaign(campaignData);
// Assert
expect(result).toHaveProperty('id');
expect(mockDependency.method).toHaveBeenCalledWith(expect.any(Object));
});
it('should handle errors gracefully', async () => {
// Arrange
mockDependency.method.mockRejectedValue(new Error('Database error'));
// Act & Assert
await expect(campaignService.createCampaign({}))
.rejects.toThrow('Database error');
});
});
});
```
### Integration Test Example
```javascript
import request from 'supertest';
import app from '../../../services/api-gateway/src/app.js';
import { connectDatabase, closeDatabase, clearDatabase } from '../../helpers/database.js';
describe('Campaigns API', () => {
let authToken;
beforeAll(async () => {
await connectDatabase();
authToken = await getAuthToken();
});
afterEach(async () => {
await clearDatabase();
});
afterAll(async () => {
await closeDatabase();
});
describe('POST /api/v1/campaigns', () => {
it('should create campaign', async () => {
const response = await request(app)
.post('/api/v1/campaigns')
.set('Authorization', `Bearer ${authToken}`)
.send({
name: 'Test Campaign',
type: 'message'
});
expect(response.status).toBe(201);
expect(response.body.success).toBe(true);
expect(response.body.data.campaign).toHaveProperty('id');
});
});
});
```
### E2E Test Example
```javascript
describe('Campaign Workflow', () => {
it('should complete full campaign lifecycle', async () => {
// 1. Create template
const template = await createTemplate();
// 2. Import users
const users = await importUsers();
// 3. Create segment
const segment = await createSegment();
// 4. Create campaign
const campaign = await createCampaign({
templateId: template.id,
segmentId: segment.id
});
// 5. Execute campaign
const execution = await executeCampaign(campaign.id);
// 6. Verify results
expect(execution.status).toBe('completed');
expect(execution.messagesSent).toBe(users.length);
});
});
```
## Test Helpers and Utilities
### Database Helpers
```javascript
import { connectDatabase, closeDatabase, clearDatabase } from './helpers/database.js';
```
### Factory Functions
```javascript
import {
createUser,
createCampaign,
createTemplate
} from './helpers/factories.js';
```
### Authentication Helpers
```javascript
import { generateAuthToken, createAuthenticatedRequest } from './helpers/auth.js';
```
## CI/CD Integration
Tests run automatically on:
- Pull requests
- Commits to main/develop branches
- Before deployments
### GitHub Actions Workflow
See `.github/workflows/test.yml` for the complete CI configuration.
Key features:
- Matrix testing (Node.js 18.x, 20.x)
- Multiple database versions
- Parallel test execution
- Coverage reporting
- Test result artifacts
### Pre-commit Hooks
```bash
# Install husky
npm prepare
# Pre-commit hook runs:
- Linting
- Unit tests for changed files
- Commit message validation
```
## Coverage Goals
### Overall Coverage Targets
- **Statements**: 80%
- **Branches**: 70%
- **Functions**: 70%
- **Lines**: 80%
### Service-Specific Targets
- **API Gateway**: 85% (critical path)
- **Orchestrator**: 80%
- **Analytics**: 75%
- **User Management**: 80%
- **Scheduler**: 75%
### Viewing Coverage
```bash
# Generate HTML coverage report
npm run test:coverage
# Open in browser
open coverage/lcov-report/index.html
```
## Best Practices
### General Guidelines
1. **Test Naming**: Use descriptive test names that explain what is being tested
```javascript
// Good
it('should return 404 when campaign does not exist')
// Bad
it('test campaign')
```
2. **Arrange-Act-Assert**: Structure tests clearly
```javascript
it('should calculate discount correctly', () => {
// Arrange
const price = 100;
const discountRate = 0.2;
// Act
const result = calculateDiscount(price, discountRate);
// Assert
expect(result).toBe(80);
});
```
3. **Isolation**: Each test should be independent
- Use `beforeEach` and `afterEach` for setup/cleanup
- Don't rely on test execution order
- Clear mocks between tests
4. **Mocking**: Mock external dependencies
```javascript
jest.mock('axios');
axios.get.mockResolvedValue({ data: mockData });
```
5. **Async Testing**: Handle promises properly
```javascript
// Good
it('should handle async operation', async () => {
await expect(asyncFunction()).resolves.toBe(expected);
});
// Also good
it('should handle async operation', () => {
return expect(asyncFunction()).resolves.toBe(expected);
});
```
6. **Error Testing**: Test error cases thoroughly
```javascript
it('should throw error for invalid input', async () => {
await expect(functionUnderTest(null))
.rejects.toThrow('Input cannot be null');
});
```
### Performance Considerations
1. **Use Test Databases**: MongoDB Memory Server for unit tests
2. **Parallel Execution**: Run independent tests in parallel
3. **Selective Testing**: Use `--watch` mode during development
4. **Mock Heavy Operations**: Mock file I/O, network calls
### Security Testing
1. **Authentication**: Test all auth scenarios
2. **Authorization**: Verify role-based access
3. **Input Validation**: Test with malicious inputs
4. **Rate Limiting**: Verify limits are enforced
## Troubleshooting
### Common Issues
1. **Timeout Errors**
```javascript
// Increase timeout for specific test
it('should handle long operation', async () => {
// test code
}, 10000); // 10 second timeout
```
2. **Database Connection Issues**
- Ensure MongoDB/Redis are running
- Check connection strings in test environment
- Clear test database between runs
3. **Flaky Tests**
- Add proper waits for async operations
- Mock time-dependent functions
- Use stable test data
4. **Memory Leaks**
- Close all connections in `afterAll`
- Clear large data structures
- Use `--detectLeaks` flag
## Additional Resources
- [Jest Documentation](https://jestjs.io/docs/getting-started)
- [Supertest Documentation](https://github.com/visionmedia/supertest)
- [MongoDB Memory Server](https://github.com/nodkz/mongodb-memory-server)
- [Testing Best Practices](https://github.com/goldbergyoni/javascript-testing-best-practices)

155
marketing-agent/docs/api/CHANGELOG.md Normal file
View File

@@ -0,0 +1,155 @@
# API Changelog
All notable changes to the Telegram Marketing Agent API will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [1.0.0] - 2024-01-14
### Added
#### Authentication & Security
- JWT-based authentication with access and refresh tokens
- API key authentication for programmatic access
- Role-based access control (admin, user, viewer)
- Rate limiting with Redis backend
- Input validation and sanitization
- SQL/NoSQL injection prevention
#### Campaign Management
- Create, read, update, and delete campaigns
- Multiple campaign types (message, invitation, data collection, engagement, custom)
- Campaign execution with real-time progress tracking
- Test mode for campaign validation
- Campaign duplication functionality
- Campaign statistics and analytics
#### Campaign Scheduling
- One-time campaign scheduling
- Recurring campaigns (daily, weekly, monthly, custom)
- Trigger-based campaigns
- Timezone support for schedules
- Schedule preview functionality
- Job management and retry mechanisms
#### User Management
- CRUD operations for Telegram users
- User grouping functionality
- Tag-based user categorization
- Dynamic user segmentation
- Bulk user operations
- CSV/Excel import/export
- Custom user fields support
#### Analytics & Reporting
- Real-time analytics dashboard
- Campaign performance metrics
- User engagement tracking
- Conversion tracking
- Revenue reporting
- Time-series data
- Export functionality
#### Message Templates
- Multi-language template support
- Variable interpolation
- Template categories
- Template versioning
- A/B testing support
#### Workflow Automation
- Multi-step workflow creation
- Conditional logic
- Action triggers
- Workflow templates
- Performance tracking
#### Webhook Integration
- Event-based webhooks
- Configurable event types
- Retry mechanisms
- Webhook testing
- Event logs
#### Data Management
- Automated backups
- Data import/export
- Compliance tools
- Data retention policies
#### Claude AI Integration
- AI-powered content suggestions
- Campaign optimization recommendations
- Audience insights
- Performance predictions
### Security
- HTTPS enforcement
- CORS configuration
- Helmet.js security headers
- Request signing
- API versioning
### Documentation
- Comprehensive API documentation
- Swagger/OpenAPI 3.0 specification
- Interactive API explorer
- Code examples in multiple languages
- Postman collection
- Quick start guide
## API Versioning
The API uses URL versioning. All endpoints are prefixed with `/api/v1/`.
## Breaking Changes Policy
- Breaking changes will only be introduced in major version releases
- Deprecated features will be maintained for at least 6 months
- Migration guides will be provided for all breaking changes
## Deprecation Notices
Currently, there are no deprecated endpoints.
## Migration Guide
### From Beta to v1.0.0
If you were using the beta version of the API, please note the following changes:
1. **Authentication**: The `/auth/token` endpoint has been renamed to `/auth/login`
2. **User Management**: The `/telegram-users` endpoints have been moved to `/users`
3. **Campaign Execution**: The `/campaigns/:id/send` endpoint is now `/campaigns/:id/execute`
4. **Response Format**: All responses now follow a consistent format:
```json
{
"success": true,
"data": {},
"meta": {}
}
```
## Support
For API support, please:
- Check the [API Documentation](./README.md)
- Review [Common Issues](./TROUBLESHOOTING.md)
- Contact support at api-support@example.com
## Upcoming Features
### v1.1.0 (Planned)
- GraphQL API endpoint
- WebSocket support for real-time updates
- Advanced analytics with custom metrics
- Multi-account management
- Enhanced AI capabilities
### v1.2.0 (Planned)
- Video message support
- Voice message campaigns
- Interactive bot responses
- Advanced segmentation with ML
- Predictive analytics

136
marketing-agent/docs/api/README.md Normal file
View File

@@ -0,0 +1,136 @@
# Telegram Marketing Agent System API Documentation
## Overview
The Telegram Marketing Agent System provides a comprehensive REST API for managing marketing campaigns, user segmentation, message scheduling, and analytics. This documentation covers all available endpoints, authentication requirements, and usage examples.
## Base URL
```
http://localhost:3000/api/v1
```
## Authentication
All API endpoints (except login and public endpoints) require JWT authentication. Include the JWT token in the Authorization header:
```
Authorization: Bearer <your-jwt-token>
```
## Getting Started
1. **Login to get access token**
```bash
curl -X POST http://localhost:3000/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "password123"}'
```
2. **Use the token for subsequent requests**
```bash
curl -X GET http://localhost:3000/api/v1/campaigns \
-H "Authorization: Bearer <your-token>"
```
## API Documentation Sections
### Core Services
1. [Authentication API](./auth-api.md) - User authentication and session management
2. [Campaigns API](./campaigns-api.md) - Campaign creation and management
3. [Analytics API](./analytics-api.md) - Real-time analytics and reporting
4. [Users API](./users-api.md) - User management and segmentation
### Marketing Features
5. [Templates API](./templates-api.md) - Message template management
6. [Scheduled Campaigns API](./scheduled-campaigns-api.md) - Campaign scheduling
7. [A/B Testing API](./ab-testing-api.md) - A/B test management
8. [Workflows API](./workflows-api.md) - Marketing automation workflows
### Integration Services
9. [Webhooks API](./webhooks-api.md) - Webhook integration management
10. [Translations API](./translations-api.md) - Multi-language support
11. [AI API](./ai-api.md) - Claude AI integration for smart suggestions
### System Management
12. [Accounts API](./accounts-api.md) - Telegram account management
13. [Compliance API](./compliance-api.md) - Compliance checking
14. [Settings API](./settings-api.md) - System configuration
## Interactive API Explorer
Access the Swagger UI at: `http://localhost:3000/api-docs`
## Rate Limiting
- Default rate limit: 100 requests per minute per IP
- Authenticated users: 1000 requests per minute
- AI endpoints: 20 requests per minute
## Error Handling
All API errors follow a consistent format:
```json
{
"success": false,
"error": "Error message",
"code": "ERROR_CODE",
"details": {}
}
```
### Common Error Codes
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `429` - Too Many Requests
- `500` - Internal Server Error
## Pagination
List endpoints support pagination:
```
GET /api/v1/campaigns?page=1&limit=20&sort=-createdAt
```
- `page` - Page number (default: 1)
- `limit` - Items per page (default: 20, max: 100)
- `sort` - Sort field, prefix with `-` for descending
## Filtering
Most list endpoints support filtering:
```
GET /api/v1/campaigns?status=active&type=message
```
## Webhooks
Configure webhooks to receive real-time notifications:
1. Register webhook endpoint
2. Verify webhook signature
3. Handle webhook events
See [Webhooks API](./webhooks-api.md) for details.
## SDKs and Libraries
- [Node.js SDK](https://github.com/yourusername/tg-marketing-sdk-node)
- [Python SDK](https://github.com/yourusername/tg-marketing-sdk-python)
- [PHP SDK](https://github.com/yourusername/tg-marketing-sdk-php)
## Support
- API Status: `http://localhost:3000/health`
- Contact: api-support@yourcompany.com
- GitHub: https://github.com/yourusername/telegram-marketing-agent

380
marketing-agent/docs/api/TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,380 @@
# API Troubleshooting Guide
This guide helps you diagnose and resolve common issues with the Telegram Marketing Agent API.
## Table of Contents
- [Authentication Issues](#authentication-issues)
- [Rate Limiting](#rate-limiting)
- [Campaign Execution Problems](#campaign-execution-problems)
- [Data Import/Export Issues](#data-importexport-issues)
- [Webhook Problems](#webhook-problems)
- [Performance Issues](#performance-issues)
- [Error Codes Reference](#error-codes-reference)
## Authentication Issues
### Problem: 401 Unauthorized Error
**Symptoms:**
```json
{
"success": false,
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}
```
**Solutions:**
1. **Check Token Format**
```bash
# Correct format
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/v1/users
# Common mistakes
curl -H "Authorization: YOUR_TOKEN" # Missing "Bearer" prefix
curl -H "Authorization: bearer YOUR_TOKEN" # Lowercase "bearer"
```
2. **Verify Token Expiration**
- Access tokens expire after 24 hours
- Use the refresh token endpoint to get a new access token
```bash
curl -X POST https://api.example.com/v1/auth/refresh \
-H "Content-Type: application/json" \
-d '{"refreshToken": "YOUR_REFRESH_TOKEN"}'
```
3. **Check API Key (if using)**
```bash
curl -H "X-API-Key: YOUR_API_KEY" https://api.example.com/v1/users
```
### Problem: 403 Forbidden Error
**Symptoms:**
- User authenticated but lacks permissions
- Specific endpoints return forbidden
**Solutions:**
1. Check user role and permissions
2. Verify endpoint access requirements
3. Contact admin for permission updates
## Rate Limiting
### Problem: 429 Too Many Requests
**Symptoms:**
```json
{
"success": false,
"error": "Too many requests",
"code": "RATE_LIMIT_EXCEEDED",
"details": {
"retryAfter": 60
}
}
```
**Solutions:**
1. **Check Rate Limit Headers**
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642012800
```
2. **Implement Exponential Backoff**
```javascript
async function retryWithBackoff(fn, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (error.status === 429 && i < maxRetries - 1) {
const delay = Math.pow(2, i) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
} else {
throw error;
}
}
}
}
```
3. **Batch Operations**
- Use bulk endpoints when available
- Group multiple operations into single requests
## Campaign Execution Problems
### Problem: Campaign Fails to Execute
**Symptoms:**
- Campaign status remains "draft"
- Execution endpoint returns errors
**Solutions:**
1. **Validate Campaign Configuration**
```bash
# Check campaign details
curl -X GET https://api.example.com/v1/orchestrator/campaigns/CAMPAIGN_ID \
-H "Authorization: Bearer YOUR_TOKEN"
```
2. **Common Issues:**
- Empty target audience
- Missing message content
- Invalid scheduling parameters
- Telegram account not connected
3. **Test Mode First**
```bash
curl -X POST https://api.example.com/v1/orchestrator/campaigns/CAMPAIGN_ID/execute \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"test": true,
"testUsers": ["user_123", "user_456"]
}'
```
### Problem: Low Delivery Rate
**Solutions:**
1. **Check Rate Limits**
- Telegram has strict rate limits
- Reduce messages per second in campaign settings
2. **Verify User Status**
- Check if users have blocked the bot
- Ensure phone numbers are valid
3. **Monitor Telegram Account Health**
- Check for account restrictions
- Verify account connection status
## Data Import/Export Issues
### Problem: Import Fails with Validation Errors
**Solutions:**
1. **Validate CSV Format**
```csv
telegramId,username,firstName,lastName,phoneNumber,tags
123456789,johndoe,John,Doe,+1234567890,"customer,active"
```
2. **Common Issues:**
- Missing required fields
- Invalid phone number format
- Special characters in CSV
- File encoding (use UTF-8)
3. **Use Template**
```bash
# Download template
curl -X GET https://api.example.com/v1/users/import/template \
-H "Authorization: Bearer YOUR_TOKEN" \
-o user_template.csv
```
### Problem: Export Timeout for Large Datasets
**Solutions:**
1. **Use Filters**
```json
{
"format": "csv",
"filters": {
"status": "active",
"createdAt": {
"from": "2024-01-01",
"to": "2024-01-31"
}
},
"limit": 10000
}
```
2. **Paginated Export**
- Export in batches
- Use background job for large exports
## Webhook Problems
### Problem: Webhooks Not Triggering
**Solutions:**
1. **Verify Webhook Configuration**
```bash
curl -X GET https://api.example.com/v1/webhooks/WEBHOOK_ID \
-H "Authorization: Bearer YOUR_TOKEN"
```
2. **Test Webhook**
```bash
curl -X POST https://api.example.com/v1/webhooks/WEBHOOK_ID/test \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"event": "campaign.completed",
"payload": {"test": true}
}'
```
3. **Common Issues:**
- URL not publicly accessible
- SSL certificate problems
- Timeout (webhook must respond within 10s)
- Response status not 2xx
### Problem: Duplicate Webhook Events
**Solutions:**
1. Implement idempotency using event IDs
2. Check webhook logs for retry attempts
3. Ensure webhook responds quickly
## Performance Issues
### Problem: Slow API Response Times
**Solutions:**
1. **Use Caching Headers**
```bash
# Check if response is cached
curl -I https://api.example.com/v1/analytics/dashboard \
-H "Authorization: Bearer YOUR_TOKEN"
```
2. **Optimize Queries**
- Use specific field selection
- Implement pagination
- Add appropriate filters
3. **Batch Operations**
```json
{
"operations": [
{"method": "GET", "path": "/users/user_123"},
{"method": "GET", "path": "/users/user_456"}
]
}
```
### Problem: Timeout Errors
**Solutions:**
1. **Increase Client Timeout**
```javascript
const response = await fetch(url, {
timeout: 30000 // 30 seconds
});
```
2. **Use Async Operations**
- For long-running tasks, use job queues
- Poll for results
## Error Codes Reference
### HTTP Status Codes
| Code | Meaning | Common Causes |
|------|---------|---------------|
| 400 | Bad Request | Invalid parameters, malformed JSON |
| 401 | Unauthorized | Missing/invalid token, expired token |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Duplicate resource, conflicting state |
| 422 | Unprocessable Entity | Validation errors |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server-side issue |
| 502 | Bad Gateway | Service unavailable |
| 503 | Service Unavailable | Maintenance, overload |
### Application Error Codes
| Code | Description | Solution |
|------|-------------|----------|
| `AUTH_FAILED` | Authentication failed | Check credentials |
| `TOKEN_EXPIRED` | Access token expired | Refresh token |
| `INVALID_INPUT` | Input validation failed | Check request body |
| `RESOURCE_NOT_FOUND` | Requested resource not found | Verify ID/path |
| `DUPLICATE_RESOURCE` | Resource already exists | Use update instead |
| `CAMPAIGN_NOT_READY` | Campaign missing required data | Complete campaign setup |
| `TELEGRAM_ERROR` | Telegram API error | Check account status |
| `QUOTA_EXCEEDED` | Account quota exceeded | Upgrade plan |
## Debug Mode
Enable debug mode for detailed error information:
```bash
curl -X GET https://api.example.com/v1/users \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-Debug-Mode: true"
```
## Getting Help
If you're still experiencing issues:
1. **Check Logs**
- Request ID in response headers
- Include in support tickets
2. **API Status**
- Check https://status.example.com
- Follow @api_status for updates
3. **Support Channels**
- Email: api-support@example.com
- Discord: https://discord.gg/example
- GitHub Issues: https://github.com/example/api/issues
## Best Practices
1. **Always Handle Errors**
```javascript
try {
const response = await api.createCampaign(data);
} catch (error) {
if (error.code === 'RATE_LIMIT_EXCEEDED') {
// Handle rate limit
} else if (error.code === 'VALIDATION_ERROR') {
// Handle validation errors
} else {
// Handle other errors
}
}
```
2. **Log Everything**
- Request/response bodies
- Headers
- Timestamps
- Error messages
3. **Monitor Your Integration**
- Set up alerts for failures
- Track success rates
- Monitor response times
4. **Use SDK When Available**
- Automatic retry logic
- Built-in error handling
- Type safety

389
marketing-agent/docs/api/auth-api.md Normal file
View File

@@ -0,0 +1,389 @@
# Authentication API
The Authentication API manages user authentication, session management, and access control.
## Endpoints
### Login
Authenticate a user and receive access tokens.
```http
POST /api/v1/auth/login
```
#### Request Body
```json
{
"username": "admin",
"password": "password123"
}
```
#### Response
```json
{
"success": true,
"data": {
"user": {
"id": "user123",
"username": "admin",
"email": "admin@example.com",
"role": "admin",
"accountId": "acc123"
},
"tokens": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"expiresIn": 86400
}
}
}
```
#### Example
```bash
curl -X POST http://localhost:3000/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "password123"
}'
```
### Register
Create a new user account.
```http
POST /api/v1/auth/register
```
#### Request Body
```json
{
"username": "newuser",
"email": "user@example.com",
"password": "securepassword123",
"fullName": "John Doe"
}
```
#### Response
```json
{
"success": true,
"data": {
"user": {
"id": "user456",
"username": "newuser",
"email": "user@example.com",
"role": "user",
"accountId": "acc456"
},
"message": "Registration successful. Please verify your email."
}
}
```
### Refresh Token
Refresh access token using refresh token.
```http
POST /api/v1/auth/refresh
```
#### Request Body
```json
{
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
```
#### Response
```json
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"expiresIn": 86400
}
}
```
### Logout
Invalidate current session.
```http
POST /api/v1/auth/logout
```
#### Headers
```
Authorization: Bearer <access-token>
```
#### Response
```json
{
"success": true,
"data": {
"message": "Logged out successfully"
}
}
```
### Get Current User
Get authenticated user's profile.
```http
GET /api/v1/auth/me
```
#### Headers
```
Authorization: Bearer <access-token>
```
#### Response
```json
{
"success": true,
"data": {
"id": "user123",
"username": "admin",
"email": "admin@example.com",
"fullName": "Admin User",
"role": "admin",
"accountId": "acc123",
"permissions": [
"campaigns.create",
"campaigns.update",
"campaigns.delete",
"users.manage"
],
"createdAt": "2024-01-01T00:00:00Z",
"lastLogin": "2024-01-20T10:30:00Z"
}
}
```
### Update Profile
Update authenticated user's profile.
```http
PUT /api/v1/auth/profile
```
#### Headers
```
Authorization: Bearer <access-token>
```
#### Request Body
```json
{
"fullName": "John Smith",
"email": "john.smith@example.com",
"preferences": {
"language": "en",
"timezone": "America/New_York",
"notifications": {
"email": true,
"push": false
}
}
}
```
#### Response
```json
{
"success": true,
"data": {
"message": "Profile updated successfully",
"user": {
"id": "user123",
"username": "admin",
"email": "john.smith@example.com",
"fullName": "John Smith"
}
}
}
```
### Change Password
Change authenticated user's password.
```http
POST /api/v1/auth/change-password
```
#### Headers
```
Authorization: Bearer <access-token>
```
#### Request Body
```json
{
"currentPassword": "oldpassword123",
"newPassword": "newpassword456"
}
```
#### Response
```json
{
"success": true,
"data": {
"message": "Password changed successfully"
}
}
```
### Reset Password Request
Request password reset link.
```http
POST /api/v1/auth/forgot-password
```
#### Request Body
```json
{
"email": "user@example.com"
}
```
#### Response
```json
{
"success": true,
"data": {
"message": "Password reset instructions sent to your email"
}
}
```
### Reset Password
Reset password using token.
```http
POST /api/v1/auth/reset-password
```
#### Request Body
```json
{
"token": "reset-token-from-email",
"newPassword": "newsecurepassword789"
}
```
#### Response
```json
{
"success": true,
"data": {
"message": "Password reset successfully"
}
}
```
## Error Responses
### Invalid Credentials
```json
{
"success": false,
"error": "Invalid username or password",
"code": "INVALID_CREDENTIALS"
}
```
### Token Expired
```json
{
"success": false,
"error": "Token has expired",
"code": "TOKEN_EXPIRED"
}
```
### Account Locked
```json
{
"success": false,
"error": "Account is locked due to multiple failed login attempts",
"code": "ACCOUNT_LOCKED",
"details": {
"lockedUntil": "2024-01-20T11:00:00Z"
}
}
```
## Security Best Practices
1. **Token Storage**: Store tokens securely in httpOnly cookies or secure storage
2. **Token Rotation**: Refresh tokens regularly to minimize exposure
3. **Password Requirements**:
- Minimum 8 characters
- At least one uppercase letter
- At least one number
- At least one special character
4. **Rate Limiting**: Login attempts are rate-limited to prevent brute force attacks
5. **Two-Factor Authentication**: Available for enhanced security (see 2FA endpoints)
## Two-Factor Authentication (2FA)
### Enable 2FA
```http
POST /api/v1/auth/2fa/enable
```
### Verify 2FA
```http
POST /api/v1/auth/2fa/verify
```
### Disable 2FA
```http
POST /api/v1/auth/2fa/disable
```
For detailed 2FA documentation, see the dedicated 2FA guide.

484
marketing-agent/docs/api/campaigns-api.md Normal file
View File

@@ -0,0 +1,484 @@
# Campaigns API
The Campaigns API allows you to create, manage, and execute marketing campaigns.
## Endpoints
### List Campaigns
Get a paginated list of campaigns.
```http
GET /api/v1/campaigns
```
#### Query Parameters
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| page | integer | Page number | 1 |
| limit | integer | Items per page (max 100) | 20 |
| status | string | Filter by status (draft, active, paused, completed, cancelled) | - |
| type | string | Filter by type (message, invitation, data_collection, engagement, custom) | - |
| sort | string | Sort field (prefix with - for descending) | -createdAt |
| search | string | Search in name and description | - |
#### Response
```json
{
"success": true,
"data": {
"campaigns": [
{
"id": "camp123",
"name": "Summer Sale Campaign",
"description": "Promotional campaign for summer products",
"type": "message",
"status": "active",
"goals": {
"targetAudience": 10000,
"conversionRate": 5,
"revenue": 50000
},
"targetAudience": {
"segments": ["seg123", "seg456"],
"totalCount": 8500
},
"strategy": {
"messaging": "Focus on discount offers",
"timing": "Send during peak hours",
"channels": ["telegram"]
},
"budget": 5000,
"startDate": "2024-06-01T00:00:00Z",
"endDate": "2024-08-31T23:59:59Z",
"statistics": {
"totalTasks": 100,
"completedTasks": 45,
"failedTasks": 2,
"messagesSent": 4500,
"conversionsAchieved": 225,
"totalCost": 2250
},
"createdBy": "user123",
"createdAt": "2024-05-15T10:00:00Z",
"updatedAt": "2024-06-15T14:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 45,
"pages": 3
}
}
}
```
#### Example
```bash
curl -X GET "http://localhost:3000/api/v1/campaigns?status=active&limit=10" \
-H "Authorization: Bearer <your-token>"
```
### Get Campaign
Get a specific campaign by ID.
```http
GET /api/v1/campaigns/:id
```
#### Response
```json
{
"success": true,
"data": {
"id": "camp123",
"name": "Summer Sale Campaign",
"description": "Promotional campaign for summer products",
"type": "message",
"status": "active",
"goals": {
"targetAudience": 10000,
"conversionRate": 5,
"revenue": 50000
},
"targetAudience": {
"segments": ["seg123", "seg456"],
"filters": {
"location": ["US", "CA"],
"ageRange": [18, 45],
"interests": ["shopping", "fashion"]
},
"totalCount": 8500
},
"messages": [
{
"id": "msg123",
"templateId": "tmpl123",
"content": "🌞 Summer Sale! Get 30% off on all items!",
"variations": [
{
"id": "var1",
"content": "☀️ Hot Summer Deals! Save 30% today!",
"weight": 50
}
]
}
],
"workflow": {
"id": "wf123",
"name": "Summer Sale Workflow",
"triggers": ["manual", "scheduled"]
},
"abTests": [
{
"id": "ab123",
"name": "Message Variation Test",
"status": "running"
}
],
"createdAt": "2024-05-15T10:00:00Z",
"updatedAt": "2024-06-15T14:30:00Z"
}
}
```
### Create Campaign
Create a new marketing campaign.
```http
POST /api/v1/campaigns
```
#### Request Body
```json
{
"name": "Black Friday Campaign",
"description": "Massive discounts for Black Friday",
"type": "message",
"goals": {
"targetAudience": 20000,
"conversionRate": 10,
"revenue": 100000
},
"targetAudience": {
"segments": ["seg789"],
"filters": {
"location": ["US"],
"purchaseHistory": true
}
},
"messages": [
{
"templateId": "tmpl456",
"personalization": {
"enabled": true,
"fields": ["firstName", "lastPurchase"]
}
}
],
"budget": 10000,
"startDate": "2024-11-24T00:00:00Z",
"endDate": "2024-11-30T23:59:59Z"
}
```
#### Response
```json
{
"success": true,
"data": {
"id": "camp456",
"name": "Black Friday Campaign",
"status": "draft",
"message": "Campaign created successfully"
}
}
```
### Update Campaign
Update an existing campaign.
```http
PUT /api/v1/campaigns/:id
```
#### Request Body
```json
{
"name": "Updated Campaign Name",
"description": "Updated description",
"goals": {
"targetAudience": 25000,
"conversionRate": 12
},
"status": "active"
}
```
### Delete Campaign
Delete a campaign (only if status is draft or cancelled).
```http
DELETE /api/v1/campaigns/:id
```
#### Response
```json
{
"success": true,
"data": {
"message": "Campaign deleted successfully"
}
}
```
### Execute Campaign
Start executing a campaign.
```http
POST /api/v1/campaigns/:id/execute
```
#### Request Body (Optional)
```json
{
"testMode": false,
"targetPercentage": 100,
"priority": "high",
"scheduledAt": "2024-11-24T10:00:00Z"
}
```
#### Response
```json
{
"success": true,
"data": {
"executionId": "exec123",
"status": "started",
"estimatedCompletion": "2024-11-24T12:00:00Z",
"message": "Campaign execution started"
}
}
```
### Pause Campaign
Pause an active campaign.
```http
POST /api/v1/campaigns/:id/pause
```
#### Response
```json
{
"success": true,
"data": {
"status": "paused",
"message": "Campaign paused successfully",
"pausedAt": "2024-06-20T15:30:00Z"
}
}
```
### Resume Campaign
Resume a paused campaign.
```http
POST /api/v1/campaigns/:id/resume
```
#### Response
```json
{
"success": true,
"data": {
"status": "active",
"message": "Campaign resumed successfully",
"resumedAt": "2024-06-21T09:00:00Z"
}
}
```
### Clone Campaign
Create a copy of an existing campaign.
```http
POST /api/v1/campaigns/:id/clone
```
#### Request Body (Optional)
```json
{
"name": "Cloned Campaign Name",
"resetStatistics": true
}
```
#### Response
```json
{
"success": true,
"data": {
"id": "camp789",
"name": "Summer Sale Campaign (Copy)",
"status": "draft",
"message": "Campaign cloned successfully"
}
}
```
### Get Campaign Statistics
Get detailed statistics for a campaign.
```http
GET /api/v1/campaigns/:id/statistics
```
#### Query Parameters
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| period | string | Time period (1h, 24h, 7d, 30d, all) | all |
| metrics | string | Comma-separated metrics to include | all |
#### Response
```json
{
"success": true,
"data": {
"overview": {
"messagesSent": 8500,
"delivered": 8200,
"read": 6500,
"clicked": 1200,
"converted": 425,
"revenue": 42500
},
"performance": {
"deliveryRate": 96.5,
"readRate": 76.5,
"clickRate": 14.1,
"conversionRate": 5.0
},
"timeline": [
{
"date": "2024-06-01",
"sent": 1000,
"delivered": 960,
"conversions": 48
}
],
"segments": [
{
"segmentId": "seg123",
"name": "Premium Users",
"performance": {
"sent": 2000,
"conversionRate": 8.5
}
}
]
}
}
```
### Get Campaign Progress
Get real-time execution progress.
```http
GET /api/v1/campaigns/:id/progress
```
#### Response
```json
{
"success": true,
"data": {
"status": "running",
"progress": {
"percentage": 65,
"processed": 5525,
"total": 8500,
"successful": 5300,
"failed": 225
},
"currentRate": 120,
"estimatedCompletion": "2024-06-20T16:45:00Z",
"errors": [
{
"code": "USER_BLOCKED",
"count": 150,
"message": "User has blocked the bot"
}
]
}
}
```
## Campaign Types
### Message Campaign
Send promotional or informational messages to users.
### Invitation Campaign
Invite users to join groups or channels.
### Data Collection Campaign
Collect user feedback or information through surveys.
### Engagement Campaign
Increase user interaction through contests or challenges.
### Custom Campaign
Custom campaign type with flexible configuration.
## Best Practices
1. **Audience Targeting**: Use segments and filters to target the right audience
2. **Message Personalization**: Personalize messages for better engagement
3. **Timing**: Schedule campaigns during peak engagement hours
4. **A/B Testing**: Test different message variations
5. **Budget Management**: Set realistic budgets and monitor spending
6. **Compliance**: Ensure campaigns comply with regulations
7. **Performance Monitoring**: Track metrics and adjust strategy
## Webhooks
You can configure webhooks to receive real-time updates about campaign events:
- `campaign.created`
- `campaign.started`
- `campaign.completed`
- `campaign.failed`
- `campaign.paused`
- `campaign.resumed`
See [Webhooks API](./webhooks-api.md) for configuration details.

600
marketing-agent/docs/api/examples.md Normal file
View File

@@ -0,0 +1,600 @@
# API Usage Examples
Practical examples demonstrating common use cases for the Telegram Marketing Agent API.
## Complete Campaign Workflow
### 1. Authenticate
```bash
# Login to get access token
TOKEN=$(curl -s -X POST http://localhost:3000/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "password123"
}' | jq -r '.data.tokens.accessToken')
echo "Token: $TOKEN"
```
### 2. Create User Segment
```bash
# Create a segment for active users
SEGMENT_ID=$(curl -s -X POST http://localhost:3000/api/v1/segments \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Active Premium Users",
"description": "Premium users active in last 7 days",
"criteria": [
{
"field": "groups",
"operator": "contains",
"value": "Premium Users"
},
{
"field": "engagement.lastActivity",
"operator": "greater_than",
"value": "7d"
}
],
"logic": "AND"
}' | jq -r '.data._id')
echo "Segment ID: $SEGMENT_ID"
```
### 3. Create Message Template
```bash
# Create a personalized message template
TEMPLATE_ID=$(curl -s -X POST http://localhost:3000/api/v1/templates \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium Offer Template",
"category": "promotional",
"content": "Hi {{firstName}}! 🎉 As a valued premium member, enjoy 30% off your next purchase. Use code: PREMIUM30",
"variables": [
{
"name": "firstName",
"type": "string",
"required": true,
"defaultValue": "Valued Customer"
}
],
"language": "en"
}' | jq -r '.data.id')
echo "Template ID: $TEMPLATE_ID"
```
### 4. Create Campaign
```bash
# Create a marketing campaign
CAMPAIGN_ID=$(curl -s -X POST http://localhost:3000/api/v1/campaigns \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium Member Exclusive Offer",
"description": "30% discount for active premium members",
"type": "message",
"goals": {
"targetAudience": 1000,
"conversionRate": 15,
"revenue": 50000
},
"targetAudience": {
"segments": ["'$SEGMENT_ID'"]
},
"messages": [
{
"templateId": "'$TEMPLATE_ID'",
"personalization": {
"enabled": true,
"fields": ["firstName"]
}
}
],
"budget": 5000
}' | jq -r '.data.id')
echo "Campaign ID: $CAMPAIGN_ID"
```
### 5. Schedule the Campaign
```bash
# Schedule campaign to run daily at 10 AM
curl -s -X POST http://localhost:3000/api/v1/scheduled-campaigns \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"campaignId": "'$CAMPAIGN_ID'",
"campaignName": "Daily Premium Offers",
"type": "recurring",
"schedule": {
"recurring": {
"pattern": "daily",
"timeOfDay": "10:00",
"timezone": "America/New_York",
"endDate": "2024-12-31T23:59:59Z"
}
},
"targetAudience": {
"type": "segment",
"segmentId": "'$SEGMENT_ID'"
},
"messageConfig": {
"templateId": "'$TEMPLATE_ID'"
},
"deliverySettings": {
"priority": "normal",
"rateLimiting": {
"enabled": true,
"messagesPerHour": 500
}
}
}'
```
### 6. Monitor Campaign Progress
```bash
# Check campaign statistics
curl -s -X GET "http://localhost:3000/api/v1/campaigns/$CAMPAIGN_ID/statistics" \
-H "Authorization: Bearer $TOKEN" | jq '.data.overview'
# Get real-time progress
curl -s -X GET "http://localhost:3000/api/v1/campaigns/$CAMPAIGN_ID/progress" \
-H "Authorization: Bearer $TOKEN" | jq '.data.progress'
```
## A/B Testing Example
### Create A/B Test
```bash
# Create an A/B test for message variations
AB_TEST_ID=$(curl -s -X POST http://localhost:3000/api/v1/experiments \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Emoji vs No Emoji Test",
"description": "Test engagement with and without emojis",
"type": "message",
"status": "draft",
"hypothesis": "Messages with emojis will have 20% higher engagement",
"metrics": {
"primary": "click_rate",
"secondary": ["open_rate", "conversion_rate"]
},
"variants": [
{
"id": "control",
"name": "No Emoji",
"description": "Plain text message",
"allocation": 50,
"config": {
"message": "Special offer: Get 25% off today!"
}
},
{
"id": "variant_a",
"name": "With Emoji",
"description": "Message with emojis",
"allocation": 50,
"config": {
"message": "🎉 Special offer: Get 25% off today! 🛍️"
}
}
],
"audience": {
"segmentId": "'$SEGMENT_ID'",
"size": 1000
},
"schedule": {
"startDate": "2024-07-01T00:00:00Z",
"endDate": "2024-07-07T23:59:59Z"
}
}' | jq -r '.data.id')
# Start the A/B test
curl -s -X POST "http://localhost:3000/api/v1/experiments/$AB_TEST_ID/start" \
-H "Authorization: Bearer $TOKEN"
```
## Workflow Automation Example
### Create Welcome Workflow
```bash
# Create an automated welcome workflow
WORKFLOW_ID=$(curl -s -X POST http://localhost:3000/api/v1/workflows \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "New User Welcome Series",
"description": "3-step welcome series for new users",
"trigger": {
"type": "user_event",
"event": "user_joined",
"conditions": {
"source": "telegram"
}
},
"nodes": [
{
"id": "welcome_message",
"type": "send_message",
"name": "Welcome Message",
"config": {
"templateId": "welcome_template_1",
"delay": {
"value": 0,
"unit": "minutes"
}
}
},
{
"id": "wait_1_day",
"type": "delay",
"name": "Wait 1 Day",
"config": {
"duration": {
"value": 1,
"unit": "days"
}
}
},
{
"id": "tips_message",
"type": "send_message",
"name": "Tips Message",
"config": {
"templateId": "tips_template"
}
},
{
"id": "check_engagement",
"type": "condition",
"name": "Check Engagement",
"config": {
"condition": {
"field": "engagement.messagesSent",
"operator": "greater_than",
"value": 0
},
"trueBranch": "engaged_user_path",
"falseBranch": "re_engagement_path"
}
}
],
"edges": [
{
"source": "welcome_message",
"target": "wait_1_day"
},
{
"source": "wait_1_day",
"target": "tips_message"
},
{
"source": "tips_message",
"target": "check_engagement"
}
]
}' | jq -r '.data.id')
# Activate the workflow
curl -s -X POST "http://localhost:3000/api/v1/workflows/$WORKFLOW_ID/activate" \
-H "Authorization: Bearer $TOKEN"
```
## User Management Example
### Import Users from CSV
```bash
# First, create a CSV file
cat > users.csv << EOF
phone,firstName,lastName,tags,groups
+1234567890,John,Doe,"VIP,Newsletter","Premium Users"
+0987654321,Jane,Smith,Newsletter,"Standard Users"
+1122334455,Bob,Johnson,"VIP,Beta","Premium Users,Beta Testers"
EOF
# Import users
curl -X POST http://localhost:3000/api/v1/users/import \
-H "Authorization: Bearer $TOKEN" \
-F "file=@users.csv" \
-F 'mapping={
"phone": "phone",
"firstName": "firstName",
"lastName": "lastName",
"tags": "tags",
"groups": "groups"
}'
```
### Bulk Tag Users
```bash
# Tag all users who made a purchase
curl -X POST http://localhost:3000/api/v1/users/bulk-update \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"attributes.hasPurchased": true
},
"updates": {
"addTags": ["Customer"],
"attributes": {
"customerSince": "2024-06-20"
}
}
}'
```
## Analytics Example
### Get Real-time Dashboard Data
```bash
# Get current metrics
curl -s -X GET http://localhost:3000/api/v1/analytics/realtime/metrics \
-H "Authorization: Bearer $TOKEN" | jq '.data'
# Get campaign performance
curl -s -X GET "http://localhost:3000/api/v1/analytics/campaigns?period=7d" \
-H "Authorization: Bearer $TOKEN" | jq '.data.campaigns[0]'
```
### Generate Custom Report
```bash
# Create a custom report
REPORT_ID=$(curl -s -X POST http://localhost:3000/api/v1/analytics/reports \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Weekly Performance Report",
"type": "performance",
"period": {
"start": "2024-06-01T00:00:00Z",
"end": "2024-06-30T23:59:59Z"
},
"metrics": [
"messages_sent",
"delivery_rate",
"engagement_rate",
"conversion_rate"
],
"groupBy": "campaign",
"format": "pdf"
}' | jq -r '.data.id')
# Download the report
curl -X GET "http://localhost:3000/api/v1/analytics/reports/$REPORT_ID/download" \
-H "Authorization: Bearer $TOKEN" \
-o "weekly_report.pdf"
```
## Webhook Integration Example
### Setup Webhook for Campaign Events
```bash
# Create webhook endpoint
WEBHOOK_ID=$(curl -s -X POST http://localhost:3000/api/v1/webhooks \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Campaign Status Webhook",
"url": "https://your-server.com/webhooks/campaigns",
"events": [
"campaign.started",
"campaign.completed",
"campaign.failed"
],
"active": true,
"headers": {
"X-Custom-Header": "your-secret-value"
},
"retryPolicy": {
"maxRetries": 3,
"retryDelay": 60
}
}' | jq -r '.data.id')
# Test the webhook
curl -X POST "http://localhost:3000/api/v1/webhooks/$WEBHOOK_ID/test" \
-H "Authorization: Bearer $TOKEN"
```
## Error Handling Examples
### Handle Rate Limiting
```bash
#!/bin/bash
# Script with retry logic for rate limits
function api_call_with_retry() {
local url=$1
local max_retries=3
local retry_count=0
while [ $retry_count -lt $max_retries ]; do
response=$(curl -s -w "\n%{http_code}" -X GET "$url" \
-H "Authorization: Bearer $TOKEN")
http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')
if [ "$http_code" -eq 200 ]; then
echo "$body"
return 0
elif [ "$http_code" -eq 429 ]; then
retry_after=$(echo "$body" | jq -r '.retryAfter // 60')
echo "Rate limited. Retrying after $retry_after seconds..." >&2
sleep "$retry_after"
((retry_count++))
else
echo "Error: HTTP $http_code" >&2
echo "$body" >&2
return 1
fi
done
echo "Max retries exceeded" >&2
return 1
}
# Use the function
api_call_with_retry "http://localhost:3000/api/v1/campaigns"
```
### Handle Pagination
```bash
#!/bin/bash
# Script to fetch all users with pagination
function fetch_all_users() {
local page=1
local limit=100
local total_fetched=0
while true; do
response=$(curl -s -X GET "http://localhost:3000/api/v1/users?page=$page&limit=$limit" \
-H "Authorization: Bearer $TOKEN")
users=$(echo "$response" | jq -r '.data.users')
pagination=$(echo "$response" | jq -r '.data.pagination')
# Process users
echo "$users" | jq -c '.[]' | while read -r user; do
# Process each user
echo "Processing user: $(echo "$user" | jq -r '.phone')"
done
# Check if there are more pages
current_page=$(echo "$pagination" | jq -r '.page')
total_pages=$(echo "$pagination" | jq -r '.pages')
if [ "$current_page" -ge "$total_pages" ]; then
break
fi
((page++))
done
}
fetch_all_users
```
## SDK Examples
### Node.js Example
```javascript
const MarketingAPI = require('telegram-marketing-sdk');
const client = new MarketingAPI({
baseURL: 'http://localhost:3000/api/v1',
auth: {
username: 'admin',
password: 'password123'
}
});
// Create and execute a campaign
async function runCampaign() {
try {
// Create campaign
const campaign = await client.campaigns.create({
name: 'Flash Sale',
type: 'message',
targetAudience: {
segments: ['segment123']
},
messages: [{
templateId: 'template456'
}]
});
// Execute campaign
const execution = await client.campaigns.execute(campaign.id);
// Monitor progress
const interval = setInterval(async () => {
const progress = await client.campaigns.getProgress(campaign.id);
console.log(`Progress: ${progress.percentage}%`);
if (progress.status === 'completed') {
clearInterval(interval);
console.log('Campaign completed!');
}
}, 5000);
} catch (error) {
console.error('Campaign failed:', error.message);
}
}
runCampaign();
```
### Python Example
```python
import telegram_marketing_sdk as tg
import time
# Initialize client
client = tg.Client(
base_url='http://localhost:3000/api/v1',
username='admin',
password='password123'
)
# Create user segment
segment = client.segments.create(
name='Python SDK Users',
criteria=[
{
'field': 'attributes.sdk',
'operator': 'equals',
'value': 'python'
}
]
)
# Create and schedule campaign
campaign = client.campaigns.create(
name='Python SDK Campaign',
type='message',
target_audience={
'segments': [segment.id]
}
)
schedule = client.scheduled_campaigns.create(
campaign_id=campaign.id,
campaign_name=f'{campaign.name} - Daily',
type='recurring',
schedule={
'recurring': {
'pattern': 'daily',
'time_of_day': '10:00',
'timezone': 'UTC'
}
}
)
print(f'Campaign scheduled: {schedule.id}')
```

531
marketing-agent/docs/api/scheduled-campaigns-api.md Normal file
View File

@@ -0,0 +1,531 @@
# Scheduled Campaigns API
The Scheduled Campaigns API allows you to create and manage recurring or scheduled marketing campaigns.
## Endpoints
### List Scheduled Campaigns
Get a list of scheduled campaigns.
```http
GET /api/v1/scheduled-campaigns
```
#### Query Parameters
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| status | string | Filter by status (draft, scheduled, active, paused, completed, cancelled, failed) | - |
| type | string | Filter by type (one-time, recurring, trigger-based) | - |
| limit | integer | Items per page (max 100) | 100 |
| skip | integer | Number of items to skip | 0 |
#### Response
```json
{
"success": true,
"data": [
{
"_id": "sched123",
"campaignId": "camp123",
"campaignName": "Weekly Newsletter",
"type": "recurring",
"schedule": {
"recurring": {
"pattern": "weekly",
"daysOfWeek": [1],
"timeOfDay": "10:00",
"timezone": "America/New_York",
"endDate": null,
"maxOccurrences": null
}
},
"targetAudience": {
"type": "segment",
"segmentId": "seg123"
},
"status": "active",
"execution": {
"nextRunAt": "2024-06-24T14:00:00Z",
"lastRunAt": "2024-06-17T14:00:00Z",
"runCount": 12
},
"statistics": {
"totalRuns": 12,
"totalMessagesSent": 24000,
"avgDeliveryRate": 95.5
}
}
]
}
```
### Get Scheduled Campaign
Get a specific scheduled campaign.
```http
GET /api/v1/scheduled-campaigns/:id
```
#### Response
```json
{
"success": true,
"data": {
"_id": "sched123",
"campaignId": "camp123",
"campaignName": "Weekly Newsletter",
"type": "recurring",
"schedule": {
"recurring": {
"pattern": "weekly",
"daysOfWeek": [1],
"timeOfDay": "10:00",
"timezone": "America/New_York"
}
},
"targetAudience": {
"type": "segment",
"segmentId": "seg123"
},
"messageConfig": {
"templateId": "tmpl123",
"personalization": {
"enabled": true,
"fields": ["firstName", "preferences"]
}
},
"deliverySettings": {
"priority": "normal",
"rateLimiting": {
"enabled": true,
"messagesPerHour": 1000
},
"quietHours": {
"enabled": true,
"start": "22:00",
"end": "08:00",
"timezone": "UTC"
}
},
"notifications": {
"onComplete": {
"enabled": true,
"channels": ["email"],
"recipients": ["admin@example.com"]
}
}
}
}
```
### Create Scheduled Campaign
Create a new scheduled campaign.
```http
POST /api/v1/scheduled-campaigns
```
#### Request Body
##### One-Time Campaign
```json
{
"campaignId": "camp456",
"campaignName": "Holiday Special",
"type": "one-time",
"schedule": {
"startDateTime": "2024-12-25T10:00:00Z"
},
"targetAudience": {
"type": "all"
},
"messageConfig": {
"templateId": "tmpl789"
},
"deliverySettings": {
"priority": "high"
}
}
```
##### Recurring Campaign
```json
{
"campaignId": "camp789",
"campaignName": "Daily Tips",
"type": "recurring",
"schedule": {
"recurring": {
"pattern": "daily",
"timeOfDay": "09:00",
"timezone": "UTC",
"endDate": "2024-12-31T23:59:59Z"
}
},
"targetAudience": {
"type": "segment",
"segmentId": "seg456"
},
"messageConfig": {
"templateId": "tmpl101",
"variations": [
{
"name": "Morning",
"templateId": "tmpl102",
"weight": 50
},
{
"name": "Standard",
"templateId": "tmpl103",
"weight": 50
}
]
}
}
```
##### Trigger-Based Campaign
```json
{
"campaignId": "camp111",
"campaignName": "Welcome Series",
"type": "trigger-based",
"schedule": {
"triggers": [
{
"type": "user_event",
"conditions": {
"event": "user_registered",
"source": "website"
},
"delay": {
"value": 1,
"unit": "hours"
}
}
]
},
"targetAudience": {
"type": "dynamic",
"dynamicCriteria": {
"newUsers": true,
"within": "24h"
}
},
"messageConfig": {
"templateId": "tmpl-welcome"
}
}
```
#### Response
```json
{
"success": true,
"data": {
"_id": "sched456",
"campaignName": "Holiday Special",
"status": "scheduled",
"execution": {
"nextRunAt": "2024-12-25T10:00:00Z"
}
}
}
```
### Update Scheduled Campaign
Update an existing scheduled campaign.
```http
PUT /api/v1/scheduled-campaigns/:id
```
#### Request Body
```json
{
"schedule": {
"recurring": {
"pattern": "weekly",
"daysOfWeek": [1, 3, 5],
"timeOfDay": "11:00"
}
},
"deliverySettings": {
"rateLimiting": {
"enabled": true,
"messagesPerHour": 2000
}
}
}
```
### Delete Scheduled Campaign
Delete a scheduled campaign.
```http
DELETE /api/v1/scheduled-campaigns/:id
```
#### Response
```json
{
"success": true,
"data": {
"success": true
}
}
```
### Pause Scheduled Campaign
Pause an active scheduled campaign.
```http
POST /api/v1/scheduled-campaigns/:id/pause
```
#### Response
```json
{
"success": true,
"data": {
"_id": "sched123",
"status": "paused",
"pausedAt": "2024-06-20T15:30:00Z"
}
}
```
### Resume Scheduled Campaign
Resume a paused scheduled campaign.
```http
POST /api/v1/scheduled-campaigns/:id/resume
```
#### Response
```json
{
"success": true,
"data": {
"_id": "sched123",
"status": "active",
"execution": {
"nextRunAt": "2024-06-24T14:00:00Z"
}
}
}
```
### Test Scheduled Campaign
Run a test execution of the scheduled campaign.
```http
POST /api/v1/scheduled-campaigns/:id/test
```
#### Request Body (Optional)
```json
{
"targetAudience": {
"type": "individual",
"userIds": ["user123", "user456"]
},
"maxRecipients": 10
}
```
#### Response
```json
{
"success": true,
"data": {
"testJobId": "job123",
"queueJobId": "queue456",
"message": "Test job created and queued"
}
}
```
### Get Campaign History
Get execution history for a scheduled campaign.
```http
GET /api/v1/scheduled-campaigns/:id/history
```
#### Query Parameters
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| limit | integer | Number of executions to return | 50 |
#### Response
```json
{
"success": true,
"data": {
"campaign": {
"id": "sched123",
"name": "Weekly Newsletter",
"type": "recurring",
"status": "active"
},
"executions": [
{
"runAt": "2024-06-17T14:00:00Z",
"status": "success",
"messagesSent": 2000,
"errors": 0,
"duration": 3600
},
{
"runAt": "2024-06-10T14:00:00Z",
"status": "success",
"messagesSent": 1950,
"errors": 5,
"duration": 3450
}
],
"jobs": [
{
"_id": "job789",
"status": "completed",
"scheduledFor": "2024-06-17T14:00:00Z",
"completedAt": "2024-06-17T15:00:00Z"
}
]
}
}
```
### Get Campaign Statistics
Get aggregated statistics for scheduled campaigns.
```http
GET /api/v1/scheduled-campaigns/statistics/:period
```
#### Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| period | string | Time period (1h, 24h, 7d, 30d, 90d, 1y) |
#### Response
```json
{
"success": true,
"data": {
"totalCampaigns": 15,
"activeCampaigns": 8,
"totalRuns": 248,
"totalMessagesSent": 124000,
"totalDelivered": 118000,
"avgDeliveryRate": 95.2
}
}
```
## Schedule Patterns
### Daily Pattern
```json
{
"pattern": "daily",
"timeOfDay": "10:00",
"timezone": "America/New_York"
}
```
### Weekly Pattern
```json
{
"pattern": "weekly",
"daysOfWeek": [1, 3, 5], // Monday, Wednesday, Friday
"timeOfDay": "14:00",
"timezone": "Europe/London"
}
```
### Monthly Pattern
```json
{
"pattern": "monthly",
"daysOfMonth": [1, 15], // 1st and 15th of each month
"timeOfDay": "09:00",
"timezone": "Asia/Tokyo"
}
```
### Custom Pattern
```json
{
"pattern": "custom",
"frequency": {
"interval": 2,
"unit": "hours"
}
}
```
## Supported Timezones
The API supports all IANA timezone identifiers. Common examples:
- `UTC`
- `America/New_York`
- `America/Los_Angeles`
- `Europe/London`
- `Europe/Paris`
- `Asia/Shanghai`
- `Asia/Tokyo`
- `Australia/Sydney`
## Best Practices
1. **Timezone Awareness**: Always specify timezone for recurring campaigns
2. **Rate Limiting**: Configure appropriate rate limits to avoid overwhelming users
3. **Quiet Hours**: Respect user preferences with quiet hours configuration
4. **Testing**: Test campaigns before setting them to active
5. **Monitoring**: Set up notifications for campaign completion and failures
6. **End Dates**: Set end dates for recurring campaigns to prevent indefinite runs
7. **Error Handling**: Monitor execution history for failed runs
## Error Codes
| Code | Description |
|------|-------------|
| INVALID_SCHEDULE | Schedule configuration is invalid |
| CAMPAIGN_NOT_FOUND | Referenced campaign does not exist |
| SCHEDULE_CONFLICT | Schedule conflicts with existing campaign |
| PAST_DATE | Start date/time is in the past |
| INVALID_TIMEZONE | Timezone identifier is not valid |

889
marketing-agent/docs/api/telegram-marketing-api.postman_collection.json Normal file
View File

@@ -0,0 +1,889 @@
{
"info": {
"name": "Telegram Marketing Agent API",
"description": "Comprehensive API collection for the Telegram Marketing Agent System. This collection includes all endpoints for managing campaigns, users, analytics, and more.\n\n## Getting Started\n\n1. Set the `base_url` variable to your API endpoint (default: http://localhost:3000)\n2. Authenticate using the Login endpoint to get your access token\n3. The token will be automatically saved to the `access_token` variable\n4. Start exploring the API!\n\n## Authentication\n\nMost endpoints require Bearer token authentication. The token is automatically managed after login.",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"variable": [
{
"key": "base_url",
"value": "http://localhost:3000",
"type": "string"
},
{
"key": "access_token",
"value": "",
"type": "string"
},
{
"key": "refresh_token",
"value": "",
"type": "string"
}
],
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{access_token}}",
"type": "string"
}
]
},
"item": [
{
"name": "Authentication",
"item": [
{
"name": "Login",
"event": [
{
"listen": "test",
"script": {
"exec": [
"if (pm.response.code === 200) {",
" const response = pm.response.json();",
" pm.collectionVariables.set('access_token', response.data.accessToken);",
" pm.collectionVariables.set('refresh_token', response.data.refreshToken);",
" pm.environment.set('userId', response.data.user.id);",
"}"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"username\": \"admin\",\n \"password\": \"password123\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/auth/login",
"host": ["{{base_url}}"],
"path": ["api", "v1", "auth", "login"]
},
"description": "Authenticate user and receive access token"
}
},
{
"name": "Register",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"username\": \"newuser\",\n \"email\": \"newuser@example.com\",\n \"password\": \"SecurePassword123!\",\n \"fullName\": \"John Doe\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/auth/register",
"host": ["{{base_url}}"],
"path": ["api", "v1", "auth", "register"]
}
}
},
{
"name": "Refresh Token",
"event": [
{
"listen": "test",
"script": {
"exec": [
"if (pm.response.code === 200) {",
" const response = pm.response.json();",
" pm.collectionVariables.set('access_token', response.data.accessToken);",
"}"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"refreshToken\": \"{{refresh_token}}\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/auth/refresh",
"host": ["{{base_url}}"],
"path": ["api", "v1", "auth", "refresh"]
}
}
},
{
"name": "Get Current User",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/auth/me",
"host": ["{{base_url}}"],
"path": ["api", "v1", "auth", "me"]
}
}
},
{
"name": "Logout",
"request": {
"method": "POST",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/auth/logout",
"host": ["{{base_url}}"],
"path": ["api", "v1", "auth", "logout"]
}
}
}
]
},
{
"name": "Campaigns",
"item": [
{
"name": "List Campaigns",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/orchestrator/campaigns?page=1&limit=20&status=active",
"host": ["{{base_url}}"],
"path": ["api", "v1", "orchestrator", "campaigns"],
"query": [
{
"key": "page",
"value": "1"
},
{
"key": "limit",
"value": "20"
},
{
"key": "status",
"value": "active"
},
{
"key": "type",
"value": "message",
"disabled": true
}
]
}
}
},
{
"name": "Create Campaign",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Summer Sale Campaign\",\n \"description\": \"Promotional campaign for summer products\",\n \"type\": \"message\",\n \"content\": {\n \"customMessage\": \"🌞 Summer Sale! Get 20% off on all products. Use code: SUMMER20\",\n \"media\": []\n },\n \"targeting\": {\n \"segments\": [],\n \"tags\": [\"customer\", \"active\"],\n \"filters\": {\n \"lastActivity\": {\n \"operator\": \"greater_than\",\n \"value\": \"30d\"\n }\n }\n },\n \"settings\": {\n \"rateLimit\": {\n \"messagesPerSecond\": 10,\n \"messagesPerUser\": 1\n }\n },\n \"goals\": {\n \"targetAudience\": 1000,\n \"conversionRate\": 15,\n \"revenue\": 50000\n }\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/orchestrator/campaigns",
"host": ["{{base_url}}"],
"path": ["api", "v1", "orchestrator", "campaigns"]
}
}
},
{
"name": "Get Campaign",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/orchestrator/campaigns/:campaignId",
"host": ["{{base_url}}"],
"path": ["api", "v1", "orchestrator", "campaigns", ":campaignId"],
"variable": [
{
"key": "campaignId",
"value": "camp_123456789"
}
]
}
}
},
{
"name": "Update Campaign",
"request": {
"method": "PUT",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Updated Summer Sale Campaign\",\n \"content\": {\n \"customMessage\": \"🌞 Extended Summer Sale! Get 25% off on all products. Use code: SUMMER25\"\n }\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/orchestrator/campaigns/:campaignId",
"host": ["{{base_url}}"],
"path": ["api", "v1", "orchestrator", "campaigns", ":campaignId"],
"variable": [
{
"key": "campaignId",
"value": "camp_123456789"
}
]
}
}
},
{
"name": "Execute Campaign",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"test\": false\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/orchestrator/campaigns/:campaignId/execute",
"host": ["{{base_url}}"],
"path": ["api", "v1", "orchestrator", "campaigns", ":campaignId", "execute"],
"variable": [
{
"key": "campaignId",
"value": "camp_123456789"
}
]
}
}
},
{
"name": "Get Campaign Statistics",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/orchestrator/campaigns/:campaignId/statistics?dateRange=last7days",
"host": ["{{base_url}}"],
"path": ["api", "v1", "orchestrator", "campaigns", ":campaignId", "statistics"],
"query": [
{
"key": "dateRange",
"value": "last7days"
}
],
"variable": [
{
"key": "campaignId",
"value": "camp_123456789"
}
]
}
}
},
{
"name": "Delete Campaign",
"request": {
"method": "DELETE",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/orchestrator/campaigns/:campaignId",
"host": ["{{base_url}}"],
"path": ["api", "v1", "orchestrator", "campaigns", ":campaignId"],
"variable": [
{
"key": "campaignId",
"value": "camp_123456789"
}
]
}
}
}
]
},
{
"name": "Scheduled Campaigns",
"item": [
{
"name": "List Scheduled Campaigns",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/scheduler/scheduled-campaigns?status=active&type=recurring",
"host": ["{{base_url}}"],
"path": ["api", "v1", "scheduler", "scheduled-campaigns"],
"query": [
{
"key": "status",
"value": "active"
},
{
"key": "type",
"value": "recurring"
}
]
}
}
},
{
"name": "Create Schedule",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"campaignId\": \"camp_123456789\",\n \"name\": \"Daily Morning Newsletter\",\n \"description\": \"Send newsletter every morning at 9 AM\",\n \"type\": \"recurring\",\n \"schedule\": {\n \"startDateTime\": \"2024-01-15T09:00:00Z\",\n \"recurring\": {\n \"pattern\": \"daily\",\n \"frequency\": {\n \"interval\": 1,\n \"unit\": \"day\"\n },\n \"time\": \"09:00\",\n \"timezone\": \"America/New_York\"\n }\n }\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/scheduler/scheduled-campaigns",
"host": ["{{base_url}}"],
"path": ["api", "v1", "scheduler", "scheduled-campaigns"]
}
}
},
{
"name": "Pause Schedule",
"request": {
"method": "POST",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/scheduler/scheduled-campaigns/:scheduleId/pause",
"host": ["{{base_url}}"],
"path": ["api", "v1", "scheduler", "scheduled-campaigns", ":scheduleId", "pause"],
"variable": [
{
"key": "scheduleId",
"value": "sched_123456789"
}
]
}
}
},
{
"name": "Resume Schedule",
"request": {
"method": "POST",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/scheduler/scheduled-campaigns/:scheduleId/resume",
"host": ["{{base_url}}"],
"path": ["api", "v1", "scheduler", "scheduled-campaigns", ":scheduleId", "resume"],
"variable": [
{
"key": "scheduleId",
"value": "sched_123456789"
}
]
}
}
}
]
},
{
"name": "Users",
"item": [
{
"name": "List Users",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/users?page=1&limit=20&status=active",
"host": ["{{base_url}}"],
"path": ["api", "v1", "users"],
"query": [
{
"key": "page",
"value": "1"
},
{
"key": "limit",
"value": "20"
},
{
"key": "status",
"value": "active"
},
{
"key": "search",
"value": "john",
"disabled": true
}
]
}
}
},
{
"name": "Create User",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"telegramId\": \"123456789\",\n \"username\": \"johndoe\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"phoneNumber\": \"+1234567890\",\n \"languageCode\": \"en\",\n \"tags\": [\"customer\", \"active\"],\n \"customFields\": {\n \"company\": \"Acme Corp\",\n \"subscription\": \"premium\"\n }\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/users",
"host": ["{{base_url}}"],
"path": ["api", "v1", "users"]
}
}
},
{
"name": "Import Users",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "formdata",
"formdata": [
{
"key": "file",
"type": "file",
"src": "/path/to/users.csv"
},
{
"key": "updateExisting",
"value": "true",
"type": "text"
},
{
"key": "defaultTags",
"value": "[\"imported\", \"newsletter\"]",
"type": "text"
}
]
},
"url": {
"raw": "{{base_url}}/api/v1/users/import",
"host": ["{{base_url}}"],
"path": ["api", "v1", "users", "import"]
}
}
},
{
"name": "Export Users",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"format\": \"csv\",\n \"filters\": {\n \"status\": \"active\",\n \"tags\": [\"customer\"]\n },\n \"fields\": [\"telegramId\", \"username\", \"firstName\", \"lastName\", \"tags\", \"createdAt\"]\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/users/export",
"host": ["{{base_url}}"],
"path": ["api", "v1", "users", "export"]
}
}
},
{
"name": "Bulk Update Users",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"userIds\": [\"user_123\", \"user_456\", \"user_789\"],\n \"updates\": {\n \"addTags\": [\"vip\", \"2024-campaign\"],\n \"removeTags\": [\"inactive\"],\n \"customFields\": {\n \"lastCampaign\": \"Summer Sale 2024\"\n }\n }\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/users/bulk",
"host": ["{{base_url}}"],
"path": ["api", "v1", "users", "bulk"]
}
}
}
]
},
{
"name": "Segments",
"item": [
{
"name": "List Segments",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/segments",
"host": ["{{base_url}}"],
"path": ["api", "v1", "segments"]
}
}
},
{
"name": "Create Segment",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Active Premium Users\",\n \"description\": \"Users who are premium subscribers and active in the last 7 days\",\n \"criteria\": [\n {\n \"field\": \"tags\",\n \"operator\": \"contains\",\n \"value\": \"premium\",\n \"logic\": \"AND\"\n },\n {\n \"field\": \"engagement.lastActivity\",\n \"operator\": \"greater_than\",\n \"value\": \"7d\"\n }\n ],\n \"isDynamic\": true\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/segments",
"host": ["{{base_url}}"],
"path": ["api", "v1", "segments"]
}
}
},
{
"name": "Preview Segment",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"criteria\": [\n {\n \"field\": \"tags\",\n \"operator\": \"contains\",\n \"value\": \"newsletter\"\n }\n ]\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/segments/preview",
"host": ["{{base_url}}"],
"path": ["api", "v1", "segments", "preview"]
}
}
},
{
"name": "Get Segment Users",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/segments/:segmentId/users",
"host": ["{{base_url}}"],
"path": ["api", "v1", "segments", ":segmentId", "users"],
"variable": [
{
"key": "segmentId",
"value": "seg_123456789"
}
]
}
}
}
]
},
{
"name": "Analytics",
"item": [
{
"name": "Campaign Analytics",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/analytics/campaigns?dateRange=last30days",
"host": ["{{base_url}}"],
"path": ["api", "v1", "analytics", "campaigns"],
"query": [
{
"key": "dateRange",
"value": "last30days"
}
]
}
}
},
{
"name": "User Analytics",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/analytics/users?metrics=growth,engagement",
"host": ["{{base_url}}"],
"path": ["api", "v1", "analytics", "users"],
"query": [
{
"key": "metrics",
"value": "growth,engagement"
}
]
}
}
},
{
"name": "Real-time Dashboard",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/analytics/dashboard",
"host": ["{{base_url}}"],
"path": ["api", "v1", "analytics", "dashboard"]
}
}
}
]
},
{
"name": "Templates",
"item": [
{
"name": "List Templates",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/templates?category=promotional",
"host": ["{{base_url}}"],
"path": ["api", "v1", "templates"],
"query": [
{
"key": "category",
"value": "promotional"
}
]
}
}
},
{
"name": "Create Template",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Welcome Message\",\n \"category\": \"onboarding\",\n \"content\": {\n \"en\": \"Welcome {{firstName}}! 🎉 Thank you for joining us.\",\n \"es\": \"¡Bienvenido {{firstName}}! 🎉 Gracias por unirte a nosotros.\"\n },\n \"variables\": [\"firstName\"],\n \"isActive\": true\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/templates",
"host": ["{{base_url}}"],
"path": ["api", "v1", "templates"]
}
}
}
]
},
{
"name": "Webhooks",
"item": [
{
"name": "List Webhooks",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/webhooks",
"host": ["{{base_url}}"],
"path": ["api", "v1", "webhooks"]
}
}
},
{
"name": "Create Webhook",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Campaign Events\",\n \"url\": \"https://your-server.com/webhooks/campaigns\",\n \"events\": [\"campaign.completed\", \"campaign.failed\", \"user.converted\"],\n \"headers\": {\n \"X-Webhook-Secret\": \"your-secret-key\"\n },\n \"isActive\": true\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/webhooks",
"host": ["{{base_url}}"],
"path": ["api", "v1", "webhooks"]
}
}
},
{
"name": "Test Webhook",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"event\": \"campaign.completed\",\n \"payload\": {\n \"campaignId\": \"camp_test_123\",\n \"name\": \"Test Campaign\"\n }\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/webhooks/:webhookId/test",
"host": ["{{base_url}}"],
"path": ["api", "v1", "webhooks", ":webhookId", "test"],
"variable": [
{
"key": "webhookId",
"value": "webhook_123456789"
}
]
}
}
}
]
},
{
"name": "System",
"item": [
{
"name": "Health Check",
"request": {
"auth": {
"type": "noauth"
},
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/health",
"host": ["{{base_url}}"],
"path": ["health"]
}
}
},
{
"name": "Service Health",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/api/v1/health/services",
"host": ["{{base_url}}"],
"path": ["api", "v1", "health", "services"]
}
}
},
{
"name": "Metrics",
"request": {
"auth": {
"type": "noauth"
},
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/metrics",
"host": ["{{base_url}}"],
"path": ["metrics"]
}
}
},
{
"name": "Create Backup",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"includeUsers\": true,\n \"includeCampaigns\": true,\n \"includeAnalytics\": true,\n \"compression\": true\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/api/v1/backup",
"host": ["{{base_url}}"],
"path": ["api", "v1", "backup"]
}
}
}
]
}
],
"event": [
{
"listen": "prerequest",
"script": {
"type": "text/javascript",
"exec": [
"// Set default headers",
"pm.request.headers.add({",
" key: 'Content-Type',",
" value: 'application/json'",
"});",
"",
"// Add request ID",
"pm.request.headers.add({",
" key: 'X-Request-ID',",
" value: pm.variables.replaceIn('{{$guid}}')",
"});"
]
}
},
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
"// Log response time",
"console.log(`Response time: ${pm.response.responseTime}ms`);",
"",
"// Check for common errors",
"if (pm.response.code >= 400) {",
" const jsonData = pm.response.json();",
" console.error(`Error: ${jsonData.error || jsonData.message}`);",
"}"
]
}
}
]
}

623
marketing-agent/docs/api/users-api.md Normal file
View File

@@ -0,0 +1,623 @@
# Users API
The Users API provides endpoints for managing users, groups, tags, and segments.
## User Endpoints
### List Users
Get a paginated list of users.
```http
GET /api/v1/users
```
#### Query Parameters
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| page | integer | Page number | 1 |
| limit | integer | Items per page (max 100) | 20 |
| search | string | Search in phone, firstName, lastName | - |
| status | string | Filter by status (active, inactive, blocked) | - |
| groups | string | Comma-separated group IDs | - |
| tags | string | Comma-separated tag IDs | - |
| sort | string | Sort field (prefix with - for descending) | -createdAt |
#### Response
```json
{
"success": true,
"data": {
"users": [
{
"_id": "user123",
"accountId": "acc123",
"phone": "+1234567890",
"firstName": "John",
"lastName": "Doe",
"username": "johndoe",
"status": "active",
"groups": [
{
"_id": "grp123",
"name": "Premium Users"
}
],
"tags": [
{
"_id": "tag123",
"name": "VIP",
"color": "#FFD700"
}
],
"attributes": {
"location": "New York",
"language": "en",
"joinDate": "2024-01-15T10:00:00Z"
},
"engagement": {
"lastActivity": "2024-06-20T15:30:00Z",
"messagesSent": 45,
"messagesReceived": 120,
"engagementScore": 85
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-06-20T15:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1250,
"pages": 63
}
}
}
```
### Get User
Get a specific user by ID.
```http
GET /api/v1/users/:id
```
### Create User
Create a new user.
```http
POST /api/v1/users
```
#### Request Body
```json
{
"phone": "+1234567890",
"firstName": "Jane",
"lastName": "Smith",
"username": "janesmith",
"groups": ["grp123"],
"tags": ["tag456"],
"attributes": {
"location": "Los Angeles",
"language": "en",
"source": "website"
}
}
```
### Update User
Update user information.
```http
PUT /api/v1/users/:id
```
#### Request Body
```json
{
"firstName": "Jane",
"lastName": "Johnson",
"status": "active",
"attributes": {
"location": "San Francisco",
"preferences": {
"notifications": true,
"newsletter": false
}
}
}
```
### Delete User
Delete a user.
```http
DELETE /api/v1/users/:id
```
### Bulk Update Users
Update multiple users at once.
```http
POST /api/v1/users/bulk-update
```
#### Request Body
```json
{
"userIds": ["user123", "user456", "user789"],
"updates": {
"addGroups": ["grp789"],
"removeTags": ["tag123"],
"attributes": {
"campaign": "summer2024"
}
}
}
```
### Import Users
Import users from CSV.
```http
POST /api/v1/users/import
```
#### Request
- Content-Type: multipart/form-data
- File field name: `file`
- Optional field: `mapping` (JSON string)
#### Example CSV Format
```csv
phone,firstName,lastName,tags,groups
+1234567890,John,Doe,VIP,"Premium Users"
+0987654321,Jane,Smith,"VIP,Gold","Premium Users,Beta Testers"
```
### Export Users
Export users to CSV.
```http
GET /api/v1/users/export
```
#### Query Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| format | string | Export format (csv, json) |
| fields | string | Comma-separated fields to export |
| filters | object | Same as list filters |
## Group Endpoints
### List Groups
Get all user groups.
```http
GET /api/v1/groups
```
#### Response
```json
{
"success": true,
"data": [
{
"_id": "grp123",
"name": "Premium Users",
"description": "Users with premium subscription",
"type": "static",
"memberCount": 450,
"color": "#4CAF50",
"isDefault": false,
"createdAt": "2024-01-01T00:00:00Z"
},
{
"_id": "grp456",
"name": "Active Last 7 Days",
"description": "Users active in the last 7 days",
"type": "dynamic",
"memberCount": 832,
"rules": {
"criteria": [
{
"field": "engagement.lastActivity",
"operator": "greater_than",
"value": "7d"
}
],
"logic": "AND"
},
"lastCalculated": "2024-06-20T15:00:00Z"
}
]
}
```
### Create Group
Create a new user group.
```http
POST /api/v1/groups
```
#### Request Body (Static Group)
```json
{
"name": "Beta Testers",
"description": "Users testing beta features",
"type": "static",
"color": "#FF5722"
}
```
#### Request Body (Dynamic Group)
```json
{
"name": "High Engagement Users",
"description": "Users with engagement score > 80",
"type": "dynamic",
"rules": {
"criteria": [
{
"field": "engagement.engagementScore",
"operator": "greater_than",
"value": 80
}
],
"logic": "AND"
},
"color": "#9C27B0"
}
```
### Update Group
Update group information.
```http
PUT /api/v1/groups/:id
```
### Delete Group
Delete a group.
```http
DELETE /api/v1/groups/:id
```
### Add Users to Group
Add users to a static group.
```http
POST /api/v1/groups/:id/add-users
```
#### Request Body
```json
{
"userIds": ["user123", "user456", "user789"]
}
```
### Remove Users from Group
Remove users from a static group.
```http
POST /api/v1/groups/:id/remove-users
```
### Recalculate Dynamic Group
Manually trigger recalculation of a dynamic group.
```http
POST /api/v1/groups/:id/recalculate
```
## Tag Endpoints
### List Tags
Get all tags.
```http
GET /api/v1/tags
```
#### Query Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| category | string | Filter by category |
| search | string | Search in tag names |
#### Response
```json
{
"success": true,
"data": [
{
"_id": "tag123",
"name": "VIP",
"category": "status",
"color": "#FFD700",
"description": "Very important customers",
"usageCount": 156,
"isSystem": false,
"createdAt": "2024-01-01T00:00:00Z"
}
]
}
```
### Create Tag
Create a new tag.
```http
POST /api/v1/tags
```
#### Request Body
```json
{
"name": "Newsletter",
"category": "preferences",
"color": "#2196F3",
"description": "Subscribed to newsletter"
}
```
### Update Tag
Update tag information.
```http
PUT /api/v1/tags/:id
```
### Delete Tag
Delete a tag.
```http
DELETE /api/v1/tags/:id
```
### Merge Tags
Merge multiple tags into one.
```http
POST /api/v1/tags/merge
```
#### Request Body
```json
{
"sourceTagIds": ["tag456", "tag789"],
"targetTagId": "tag123"
}
```
## Segment Endpoints
### List Segments
Get all segments.
```http
GET /api/v1/segments
```
#### Response
```json
{
"success": true,
"data": [
{
"_id": "seg123",
"name": "High Value Customers",
"description": "Customers with high purchase value and engagement",
"criteria": [
{
"field": "attributes.totalPurchases",
"operator": "greater_than",
"value": 1000
},
{
"field": "engagement.engagementScore",
"operator": "greater_than",
"value": 70
}
],
"logic": "AND",
"userCount": 342,
"lastCalculated": "2024-06-20T15:00:00Z",
"isActive": true
}
]
}
```
### Create Segment
Create a new segment.
```http
POST /api/v1/segments
```
#### Request Body
```json
{
"name": "Inactive Users",
"description": "Users who haven't been active in 30 days",
"criteria": [
{
"field": "engagement.lastActivity",
"operator": "less_than",
"value": "30d"
}
],
"logic": "AND",
"excludeSegments": ["seg456"]
}
```
### Test Segment
Test segment criteria and get user count.
```http
POST /api/v1/segments/:id/test
```
#### Response
```json
{
"success": true,
"data": {
"userCount": 156,
"sampleUsers": [
{
"_id": "user123",
"phone": "+1234567890",
"firstName": "John"
}
],
"executionTime": 125
}
}
```
### Export Segment Users
Export users in a segment.
```http
GET /api/v1/segments/:id/export
```
### Clone Segment
Create a copy of a segment.
```http
POST /api/v1/segments/:id/clone
```
## Statistics Endpoints
### User Statistics
Get user statistics.
```http
GET /api/v1/users-stats
```
#### Response
```json
{
"success": true,
"data": {
"totalUsers": 12500,
"activeUsers": 8900,
"newUsers": {
"today": 45,
"thisWeek": 312,
"thisMonth": 1250
},
"engagement": {
"avgEngagementScore": 72.5,
"highlyEngaged": 3200,
"moderatelyEngaged": 5700,
"lowEngagement": 3600
},
"growth": {
"daily": 2.5,
"weekly": 8.3,
"monthly": 15.6
}
}
}
```
### Group Statistics
Get group statistics.
```http
GET /api/v1/groups-stats
```
### Tag Statistics
Get tag usage statistics.
```http
GET /api/v1/tags-stats
```
## Supported Operators
For dynamic groups and segments:
| Operator | Description | Example |
|----------|-------------|----------|
| equals | Exact match | status equals "active" |
| not_equals | Not equal | status not_equals "blocked" |
| contains | Contains string | tags contains "VIP" |
| not_contains | Doesn't contain | groups not_contains "Blocked" |
| greater_than | Greater than | engagementScore greater_than 80 |
| less_than | Less than | lastActivity less_than "7d" |
| greater_or_equal | Greater or equal | totalPurchases greater_or_equal 100 |
| less_or_equal | Less or equal | messagesSent less_or_equal 10 |
| in | In list | location in ["NY", "CA", "TX"] |
| not_in | Not in list | status not_in ["blocked", "inactive"] |
| exists | Field exists | email exists true |
| regex | Regular expression | phone regex "^\+1" |
## Best Practices
1. **Segmentation**: Use segments for targeted campaigns
2. **Dynamic Groups**: Leverage dynamic groups for automatic user categorization
3. **Tags**: Use tags for flexible user labeling
4. **Bulk Operations**: Use bulk endpoints for efficiency
5. **Caching**: Segment calculations are cached for performance
6. **Regular Updates**: Keep user data updated for accurate targeting

267
marketing-agent/docs/architecture/system-architecture.md Normal file
View File

@@ -0,0 +1,267 @@
# System Architecture - Marketing Intelligence Agent
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Admin Frontend │
│ (React + TypeScript + Ant Design) │
└─────────────────────────────────────┬───────────────────────────────────────┘
│
┌─────────┴──────────┐
│ API Gateway │
│ (Nginx/Kong) │
└─────────┬──────────┘
│
┌─────────────────────────────┼─────────────────────────────┐
│ │ │
┌───────┴────────┐ ┌────────┴────────┐ ┌────────┴────────┐
│ Orchestrator │ │ Claude Agent │ │ gramJS Adapter │
│ Service │◄─────────►│ Service │◄────────►│ Service │
└───────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
│ ┌────────┴────────┐ │
│ │ Safety Guard │ │
│ │ Service │◄──────────────────┘
│ └────────┬────────┘
│ │
┌───────┴────────┐ ┌────────┴────────┐ ┌─────────────────┐
│ Analytics │ │ A/B Testing │ │ Compliance │
│ Service │◄─────────►│ Service │◄────────►│ Guard │
└────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└─────────────────────────────┼─────────────────────────────┘
│
┌─────────────────────┼──────────────────────┐
│ │ │
┌───────┴────────┐ ┌───────┴────────┐ ┌────────┴────────┐
│ PostgreSQL │ │ MongoDB │ │ Redis │
│ (Main DB) │ │ (Events) │ │ (Cache/Queue) │
└────────────────┘ └────────────────┘ └─────────────────┘
```
## Service Descriptions
### 1. API Gateway (Port 8000)
- **Purpose**: Central entry point for all API requests
- **Technology**: Nginx or Kong
- **Features**:
- Request routing
- Authentication
- Rate limiting
- Load balancing
- SSL termination
### 2. Orchestrator Service (Port 3001)
- **Purpose**: Task scheduling and workflow management
- **Key Components**:
- Task Queue Manager (BullMQ)
- State Machine Engine (XState)
- Task Scheduler
- Workflow Engine
- **Database**: PostgreSQL for task persistence
### 3. Claude Agent Service (Port 3002)
- **Purpose**: AI-powered decision making and content generation
- **Key Components**:
- Claude API Integration
- Function Calling Handler
- Prompt Template Engine
- Context Manager
- Token Usage Tracker
- **Integration**: Anthropic Claude API
### 4. gramJS Adapter Service (Port 3003)
- **Purpose**: Telegram automation and messaging
- **Key Components**:
- Connection Pool Manager
- Session Manager
- Message Tools (send, create, invite, etc.)
- Event Listener
- FloodWait Handler
- **Integration**: Telegram API via gramJS
### 5. Safety Guard Service (Port 3004)
- **Purpose**: Compliance and safety enforcement
- **Key Components**:
- Rate Limiter
- Content Filter
- Keyword Blacklist
- PII Scanner
- ToS Compliance Checker
- Account Health Monitor
### 6. Analytics Service (Port 3005)
- **Purpose**: Data collection and analysis
- **Key Components**:
- Event Collector
- Real-time Aggregator
- Funnel Analyzer
- User Segmentation
- ROI Calculator
- **Database**: MongoDB for event storage
### 7. A/B Testing Service (Port 3006)
- **Purpose**: Experiment management and optimization
- **Key Components**:
- Experiment Engine
- Traffic Splitter
- Multi-Armed Bandit
- Bayesian Optimizer
- Statistical Calculator
### 8. Compliance Guard Service (Port 3007)
- **Purpose**: Legal compliance and data protection
- **Key Components**:
- GDPR Compliance
- CCPA Compliance
- Data Privacy Scanner
- Audit Logger
- Consent Manager
## Data Flow
### Campaign Creation Flow
```
1. User → Admin UI → API Gateway
2. API Gateway → Orchestrator Service
3. Orchestrator → Claude Agent (Strategy Generation)
4. Claude Agent → Safety Guard (Content Validation)
5. Safety Guard → Orchestrator (Approved/Rejected)
6. Orchestrator → Campaign Database
```
### Message Sending Flow
```
1. Orchestrator → Task Queue
2. Task Worker → gramJS Adapter
3. gramJS Adapter → Safety Guard (Pre-check)
4. Safety Guard → gramJS Adapter (Approved)
5. gramJS Adapter → Telegram API
6. Result → Analytics Service
7. Analytics → Event Store
```
### Human-in-the-Loop Flow
```
1. High-risk Task → Escalation Engine
2. Escalation → Human Review Queue
3. Admin UI → Review Interface
4. Human Decision → Orchestrator
5. Orchestrator → Continue/Abort Task
```
## Infrastructure Components
### Message Queue (RabbitMQ)
- Task distribution
- Service communication
- Event broadcasting
- Dead letter queues
### Cache Layer (Redis)
- Session storage
- Rate limiting counters
- Temporary data
- Task queues (BullMQ)
### Search Engine (Elasticsearch)
- Log aggregation
- Full-text search
- Analytics queries
- Audit trail search
### Monitoring Stack
- **Prometheus**: Metrics collection
- **Grafana**: Visualization
- **Jaeger**: Distributed tracing
- **ELK Stack**: Log management
## Security Architecture
### Authentication & Authorization
- JWT-based authentication
- Role-based access control (RBAC)
- API key management
- OAuth2 integration
### Data Protection
- End-to-end encryption
- At-rest encryption
- TLS/SSL for transit
- Key rotation
### Network Security
- VPC isolation
- Security groups
- WAF protection
- DDoS mitigation
## Scalability Considerations
### Horizontal Scaling
- Stateless services
- Load balancer distribution
- Database read replicas
- Cache clustering
### Vertical Scaling
- Resource monitoring
- Auto-scaling groups
- Performance tuning
- Database optimization
### High Availability
- Multi-AZ deployment
- Failover mechanisms
- Health checks
- Backup strategies
## Deployment Architecture
### Container Orchestration
```yaml
Kubernetes Cluster:
- Namespace: marketing-agent
- Services: 8 microservices
- Ingress: NGINX controller
- Storage: PersistentVolumes
- ConfigMaps: Environment configs
- Secrets: Sensitive data
```
### CI/CD Pipeline
```
1. Code Push → GitHub
2. GitHub Actions → Build & Test
3. Docker Build → Container Registry
4. Kubernetes Deploy → Staging
5. Integration Tests → Validation
6. Blue-Green Deploy → Production
```
## Development Guidelines
### Service Communication
- RESTful APIs for synchronous calls
- RabbitMQ for asynchronous messaging
- gRPC for high-performance internal communication
### Error Handling
- Circuit breaker pattern
- Retry with exponential backoff
- Dead letter queues
- Graceful degradation
### Logging & Monitoring
- Structured logging (JSON)
- Correlation IDs
- Distributed tracing
- Custom metrics
### Testing Strategy
- Unit tests (>80% coverage)
- Integration tests
- End-to-end tests
- Performance tests
- Security tests

402
marketing-agent/docs/deployment/README.md Normal file
View File

@@ -0,0 +1,402 @@
# Deployment Guide for Marketing Intelligence Agent System
This guide covers various deployment options for the Marketing Intelligence Agent System.
## Table of Contents
- [Prerequisites](#prerequisites)
- [Docker Deployment](#docker-deployment)
- [Kubernetes Deployment](#kubernetes-deployment)
- [CI/CD Pipeline](#cicd-pipeline)
- [Environment Configuration](#environment-configuration)
- [Security Best Practices](#security-best-practices)
- [Monitoring and Maintenance](#monitoring-and-maintenance)
## Prerequisites
### System Requirements
- **CPU**: Minimum 8 cores (16 cores recommended for production)
- **Memory**: Minimum 16GB RAM (32GB recommended for production)
- **Storage**: Minimum 100GB SSD storage
- **Network**: Stable internet connection with low latency
### Software Requirements
- Docker 20.10+ and Docker Compose 2.0+
- Kubernetes 1.24+ (for K8s deployment)
- Helm 3.10+ (for K8s deployment)
- Git
- Node.js 18+ (for local development)
### External Services
- Telegram account with API credentials
- Anthropic API key (for Claude AI)
- OpenAI API key (optional, for safety checks)
- SMTP server or email service (for notifications)
- S3-compatible storage (for backups)
## Docker Deployment
### Quick Start
1. Clone the repository:
```bash
git clone https://github.com/yourcompany/marketing-agent.git
cd marketing-agent
```
2. Copy environment template:
```bash
cp .env.example .env
```
3. Edit `.env` file with your configurations:
```bash
# Required configurations
ANTHROPIC_API_KEY=your_anthropic_api_key
JWT_SECRET=your_jwt_secret
MONGO_ROOT_PASSWORD=secure_password
REDIS_PASSWORD=secure_password
# ... other configurations
```
4. Build and start services:
```bash
# Build all images
./scripts/docker-build.sh
# Start services
docker-compose up -d
# Wait for services to be ready
./scripts/wait-for-services.sh
```
5. Initialize admin user:
```bash
docker-compose exec api-gateway node scripts/init-admin.js
```
### Production Deployment
For production deployment, use the production compose file:
```bash
# Build with production optimizations
./scripts/docker-build.sh --tag v1.0.0 --registry ghcr.io/yourcompany
# Deploy with production settings
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```
### SSL/TLS Configuration
1. Place SSL certificates in `infrastructure/ssl/`:
```
infrastructure/ssl/
├── cert.pem
├── key.pem
└── dhparam.pem
```
2. Update nginx configuration:
```nginx
server {
listen 443 ssl http2;
ssl_certificate /etc/nginx/ssl/cert.pem;
ssl_certificate_key /etc/nginx/ssl/key.pem;
# ... other SSL settings
}
```
## Kubernetes Deployment
### Using Helm
1. Add Helm dependencies:
```bash
cd helm/marketing-agent
helm dependency update
```
2. Create namespace:
```bash
kubectl create namespace marketing-agent
```
3. Create secrets:
```bash
kubectl create secret generic marketing-agent-secrets \
--from-literal=anthropic-api-key=$ANTHROPIC_API_KEY \
--from-literal=jwt-secret=$JWT_SECRET \
-n marketing-agent
```
4. Install the chart:
```bash
helm install marketing-agent ./helm/marketing-agent \
--namespace marketing-agent \
--values ./helm/marketing-agent/values.yaml \
--values ./helm/marketing-agent/values.prod.yaml
```
### Manual Kubernetes Deployment
If not using Helm, apply the manifests directly:
```bash
kubectl apply -f infrastructure/k8s/namespace.yaml
kubectl apply -f infrastructure/k8s/configmap.yaml
kubectl apply -f infrastructure/k8s/secrets.yaml
kubectl apply -f infrastructure/k8s/deployments/
kubectl apply -f infrastructure/k8s/services/
kubectl apply -f infrastructure/k8s/ingress.yaml
```
### Scaling
Horizontal Pod Autoscaling is configured for key services:
```bash
# Check HPA status
kubectl get hpa -n marketing-agent
# Manual scaling
kubectl scale deployment marketing-agent-api-gateway --replicas=5 -n marketing-agent
```
## CI/CD Pipeline
### GitHub Actions
The project includes comprehensive CI/CD pipelines:
#### Continuous Integration (.github/workflows/ci.yml)
- Code linting and formatting
- Security scanning
- Unit and integration tests
- Docker image building
- E2E testing
- Performance testing
#### Continuous Deployment (.github/workflows/cd.yml)
- Automatic deployment to staging on main branch
- Production deployment on version tags
- Database migrations
- Blue-green deployment
- Automated rollback on failure
#### Security Scanning (.github/workflows/security.yml)
- Container vulnerability scanning
- SAST (Static Application Security Testing)
- Secret scanning
- Dependency auditing
- Infrastructure security checks
### Setting up CI/CD
1. Configure GitHub secrets:
```
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
ANTHROPIC_API_KEY
SLACK_WEBHOOK
DOCKER_REGISTRY_USERNAME
DOCKER_REGISTRY_PASSWORD
```
2. Configure deployment environments in GitHub:
- staging
- production
3. Enable branch protection rules for main branch
## Environment Configuration
### Environment Variables
Create environment-specific files:
- `.env.development`
- `.env.staging`
- `.env.production`
Key configurations:
```bash
# Application
NODE_ENV=production
LOG_LEVEL=info
# Security
JWT_SECRET=<generate-with-openssl-rand>
ENCRYPTION_KEY=<32-byte-key>
# Database
MONGODB_URI=mongodb://user:pass@mongodb:27017/marketing_agent
REDIS_PASSWORD=<secure-password>
# External Services
ANTHROPIC_API_KEY=<your-key>
TELEGRAM_SYSTEM_URL=<your-telegram-system-url>
# Monitoring
GRAFANA_ADMIN_PASSWORD=<secure-password>
ELASTIC_PASSWORD=<secure-password>
```
### Configuration Management
Use ConfigMaps for non-sensitive configurations:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: marketing-agent-config
data:
NODE_ENV: "production"
LOG_LEVEL: "info"
RATE_LIMIT_WINDOW: "60000"
RATE_LIMIT_MAX: "100"
```
## Security Best Practices
### 1. Secret Management
- Use Kubernetes secrets or external secret managers (Vault, AWS Secrets Manager)
- Rotate secrets regularly
- Never commit secrets to version control
### 2. Network Security
- Enable network policies to restrict traffic
- Use TLS for all communications
- Implement proper CORS policies
### 3. Container Security
- Run containers as non-root user
- Use minimal base images (Alpine)
- Scan images for vulnerabilities
- Keep dependencies updated
### 4. Access Control
- Implement RBAC in Kubernetes
- Use service accounts with minimal permissions
- Enable audit logging
### 5. Data Protection
- Encrypt data at rest
- Use TLS for data in transit
- Implement proper backup encryption
- Follow GDPR compliance guidelines
## Monitoring and Maintenance
### Health Checks
All services expose health endpoints:
- `/health` - Basic health check
- `/health/live` - Liveness probe
- `/health/ready` - Readiness probe
### Metrics and Monitoring
1. Access Grafana dashboards:
```
http://localhost:3032 (Docker)
https://grafana.your-domain.com (K8s)
```
2. Key metrics to monitor:
- API response times
- Error rates
- Message delivery success rate
- System resource usage
- Database performance
### Logging
Centralized logging with Elasticsearch:
```bash
# View logs
docker-compose logs -f api-gateway
# Search logs in Elasticsearch
curl -X GET "localhost:9200/logs-*/_search?q=error"
```
### Backup and Recovery
Automated backups are configured to run daily:
```bash
# Manual backup
./scripts/backup.sh
# Restore from backup
./scripts/restore.sh backup-20240115-020000.tar.gz
```
### Maintenance Tasks
1. **Database maintenance**:
```bash
# MongoDB optimization
docker-compose exec mongodb mongosh --eval "db.adminCommand({compact: 'campaigns'})"
# Redis memory optimization
docker-compose exec redis redis-cli --raw MEMORY DOCTOR
```
2. **Log rotation**:
```bash
# Configured in Docker with max-size and max-file
# For K8s, use log shipping solutions
```
3. **Update dependencies**:
```bash
# Check for updates
npm audit
# Update dependencies
npm update
```
### Troubleshooting
Common issues and solutions:
1. **Service not starting**:
- Check logs: `docker-compose logs <service>`
- Verify environment variables
- Check resource availability
2. **Database connection issues**:
- Verify connection strings
- Check network connectivity
- Ensure database is initialized
3. **Performance issues**:
- Check resource usage
- Review slow query logs
- Enable performance profiling
4. **Deployment failures**:
- Check CI/CD logs
- Verify credentials and permissions
- Review deployment prerequisites
## Next Steps
- Review [API Documentation](../api/README.md)
- Configure [Monitoring Dashboards](../monitoring/README.md)
- Set up [Backup Strategy](../backup/README.md)
- Implement [Disaster Recovery Plan](../disaster-recovery/README.md)