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