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

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.

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

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

GET /api/v1/scheduled-campaigns/:id

Response

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

POST /api/v1/scheduled-campaigns

Request Body

One-Time Campaign

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

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

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

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

PUT /api/v1/scheduled-campaigns/:id

Request Body

{
  "schedule": {
    "recurring": {
      "pattern": "weekly",
      "daysOfWeek": [1, 3, 5],
      "timeOfDay": "11:00"
    }
  },
  "deliverySettings": {
    "rateLimiting": {
      "enabled": true,
      "messagesPerHour": 2000
    }
  }
}

Delete Scheduled Campaign

Delete a scheduled campaign.

DELETE /api/v1/scheduled-campaigns/:id

Response

{
  "success": true,
  "data": {
    "success": true
  }
}

Pause Scheduled Campaign

Pause an active scheduled campaign.

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

Response

{
  "success": true,
  "data": {
    "_id": "sched123",
    "status": "paused",
    "pausedAt": "2024-06-20T15:30:00Z"
  }
}

Resume Scheduled Campaign

Resume a paused scheduled campaign.

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

Response

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

POST /api/v1/scheduled-campaigns/:id/test

Request Body (Optional)

{
  "targetAudience": {
    "type": "individual",
    "userIds": ["user123", "user456"]
  },
  "maxRecipients": 10
}

Response

{
  "success": true,
  "data": {
    "testJobId": "job123",
    "queueJobId": "queue456",
    "message": "Test job created and queued"
  }
}

Get Campaign History

Get execution history for a scheduled campaign.

GET /api/v1/scheduled-campaigns/:id/history

Query Parameters

Parameter	Type	Description	Default
limit	integer	Number of executions to return	50

Response

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

GET /api/v1/scheduled-campaigns/statistics/:period

Path Parameters

Parameter	Type	Description
period	string	Time period (1h, 24h, 7d, 30d, 90d, 1y)

Response

{
  "success": true,
  "data": {
    "totalCampaigns": 15,
    "activeCampaigns": 8,
    "totalRuns": 248,
    "totalMessagesSent": 124000,
    "totalDelivered": 118000,
    "avgDeliveryRate": 95.2
  }
}

Schedule Patterns

Daily Pattern

{
  "pattern": "daily",
  "timeOfDay": "10:00",
  "timezone": "America/New_York"
}

Weekly Pattern

{
  "pattern": "weekly",
  "daysOfWeek": [1, 3, 5], // Monday, Wednesday, Friday
  "timeOfDay": "14:00",
  "timezone": "Europe/London"
}

Monthly Pattern

{
  "pattern": "monthly",
  "daysOfMonth": [1, 15], // 1st and 15th of each month
  "timeOfDay": "09:00",
  "timezone": "Asia/Tokyo"
}

Custom Pattern

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