telegram-management-system/marketing-agent/docs/api/campaigns-api.md

Campaigns API

The Campaigns API allows you to create, manage, and execute marketing campaigns.

Endpoints

List Campaigns

Get a paginated list of campaigns.

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

{
  "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

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.

GET /api/v1/campaigns/:id

Response

{
  "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.

POST /api/v1/campaigns

Request Body

{
  "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

{
  "success": true,
  "data": {
    "id": "camp456",
    "name": "Black Friday Campaign",
    "status": "draft",
    "message": "Campaign created successfully"
  }
}

Update Campaign

Update an existing campaign.

PUT /api/v1/campaigns/:id

Request Body

{
  "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).

DELETE /api/v1/campaigns/:id

Response

{
  "success": true,
  "data": {
    "message": "Campaign deleted successfully"
  }
}

Execute Campaign

Start executing a campaign.

POST /api/v1/campaigns/:id/execute

Request Body (Optional)

{
  "testMode": false,
  "targetPercentage": 100,
  "priority": "high",
  "scheduledAt": "2024-11-24T10:00:00Z"
}

Response

{
  "success": true,
  "data": {
    "executionId": "exec123",
    "status": "started",
    "estimatedCompletion": "2024-11-24T12:00:00Z",
    "message": "Campaign execution started"
  }
}

Pause Campaign

Pause an active campaign.

POST /api/v1/campaigns/:id/pause

Response

{
  "success": true,
  "data": {
    "status": "paused",
    "message": "Campaign paused successfully",
    "pausedAt": "2024-06-20T15:30:00Z"
  }
}

Resume Campaign

Resume a paused campaign.

POST /api/v1/campaigns/:id/resume

Response

{
  "success": true,
  "data": {
    "status": "active",
    "message": "Campaign resumed successfully",
    "resumedAt": "2024-06-21T09:00:00Z"
  }
}

Clone Campaign

Create a copy of an existing campaign.

POST /api/v1/campaigns/:id/clone

Request Body (Optional)

{
  "name": "Cloned Campaign Name",
  "resetStatistics": true
}

Response

{
  "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.

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

{
  "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.

GET /api/v1/campaigns/:id/progress

Response

{
  "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 for configuration details.