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.

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