237c7802e5
Some checks failed
Deploy / deploy (push) Has been cancelled
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>
484 lines
8.9 KiB
Markdown
484 lines
8.9 KiB
Markdown
# 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. |