Campaign Management

Campaigns let you send messages to multiple contacts at once, with scheduling, cost estimation, and detailed analytics.

Campaign Lifecycle

Every campaign follows this workflow:

Draft → Configured → Cost Calculated → Confirmed/Scheduled → Sending → Completed

1. Draft — Campaign created, initial setup
2. Configured — All settings finalized (contacts, channel, message)
3. Cost Calculated — System estimates total cost
4. Confirmed/Scheduled — Approved and ready to send (immediate or scheduled)
5. Sending — Messages being delivered
6. Completed — All messages sent

Creating a Campaign

Endpoint: POST /campaigns

{
  "name": "Spring Promotion 2025",
  "channel": "sms",
  "message": "Spring sale is here! 30% off everything. Shop now: https://example.com/spring",
  "contactList": "list_12345",
  "sendImmediately": false,
  "scheduledTime": "2025-04-15T09:00:00Z"
}

Request Fields

Field	Type	Required	Description
name	string	Yes	Campaign name
channel	string	Yes	sms, rcs, or whatsapp
message	string	Yes	Message content (for SMS) or templateId (for RCS/WhatsApp)
contactList	string	Yes	ID of contact list to send to
sendImmediately	boolean	No	Send now (default: false)
scheduledTime	ISO 8601	No	Send at this time (if not immediate)
fallback	boolean	No	Enable channel fallback (default: false)

Updating a Campaign

Endpoint: PUT /campaigns/{id}

Update campaign before sending (Draft or Configured status only):

{
  "name": "Spring Promotion 2025 - Updated",
  "message": "New offer text",
  "scheduledTime": "2025-04-16T10:00:00Z"
}

You cannot modify campaigns that are Confirmed, Sending, or Completed.

Calculating Cost

Before confirming, estimate the total cost.

Endpoint: POST /campaigns/{id}/calculateGoal

{
  "goalContactCount": 5000
}

Response:

{
  "totalContacts": 5000,
  "estimatedCost": 250.00,
  "costPerMessage": 0.05,
  "currency": "EUR",
  "estimatedDuration": "15 minutes"
}

Cost Factors

• SMS: Cheapest (~0.03-0.05 EUR per message)
• RCS: Medium (~0.05-0.10 EUR per message)
• WhatsApp: Most expensive (~0.10-0.20 EUR per message)

Prices vary by country and volume.

Getting Campaign Price

Endpoint: GET /campaigns/{id}/price

Get the final price before confirming:

{
  "campaignId": "camp_12345",
  "totalContacts": 5000,
  "estimatedCost": 250.00,
  "breakdown": {
    "sms": { "count": 0, "cost": 0 },
    "rcs": { "count": 0, "cost": 0 },
    "whatsapp": { "count": 0, "cost": 0 }
  }
}

Confirming a Campaign

Endpoint: PUT /campaigns/{id}/confirm

Confirm and move to Confirmed status. After this, you cannot edit the campaign.

curl -X PUT https://lora-api.agiletelecom.com/api/campaigns/camp_12345/confirm \
  -H "X-Api-Key: your_api_key_here"

Response:

{
  "id": "camp_12345",
  "status": "confirmed",
  "scheduledTime": "2025-04-15T09:00:00Z",
  "message": "Campaign confirmed. Sending starts at scheduled time."
}

Once confirmed, the campaign will send at the scheduled time (or immediately if sendImmediately: true).

Canceling a Campaign

Endpoint: DELETE /campaigns/{id}

Cancel a campaign (only Draft, Configured, or Confirmed status):

curl -X DELETE https://lora-api.agiletelecom.com/api/campaigns/camp_12345 \
  -H "X-Api-Key: your_api_key_here"

You cannot cancel campaigns that are Sending or Completed.

Campaign Statistics

Endpoint: GET /campaigns/{id}/stats

Get real-time campaign analytics:

curl -X GET https://lora-api.agiletelecom.com/api/campaigns/camp_12345/stats \
  -H "X-Api-Key: your_api_key_here"

Response:

{
  "campaignId": "camp_12345",
  "name": "Spring Promotion 2025",
  "status": "sending",
  "totalMessages": 5000,
  "sent": 3200,
  "delivered": 2890,
  "failed": 310,
  "pending": 1800,
  "deliveryRate": 0.578,
  "failureRate": 0.062,
  "startTime": "2025-04-15T09:00:00Z",
  "estimatedCompletionTime": "2025-04-15T09:45:00Z"
}

Statistics Fields

Field	Description
sent	Messages sent to carriers (left our servers)
delivered	Successfully delivered to recipients
failed	Failed (invalid number, carrier rejection, etc.)
pending	Not yet sent
deliveryRate	delivered / sent
failureRate	failed / sent

Best Practices

Planning

1. Test first — Send a small test campaign to verify message content and contacts
2. Review contacts — Ensure phone numbers are valid and contacts have opted in
3. Check cost — Always call calculateGoal before confirming large campaigns
4. Use templates — For RCS and WhatsApp, use pre-approved templates for faster processing

Execution

1. Schedule off-peak — Avoid sending during carrier maintenance windows (typically 2-4 AM)
2. Monitor early — Check stats in the first few minutes to catch issues
3. Set expectations — Delivery takes time. Check back in 30-60 minutes for completion
4. Handle failures — Monitor failed messages and retry with SMS fallback if needed

Analytics

1. Track delivery rate — Aim for 90%+ delivery rate. Investigate if lower.
2. Monitor failures — High failure rate indicates invalid contact data
3. Compare channels — WhatsApp has highest delivery rate, SMS is most reliable
4. Optimize send time — Experiment with different days/times to maximize engagement

Campaign Limits

Limit	Value
Max contacts per campaign	1,000,000
Max campaigns (active)	10
Min message length	1 character
Max message length	160 (SMS), 1000 (RCS), 1000 (WhatsApp)

Common Use Cases

Promotional Campaign

{
  "name": "Spring Sale",
  "channel": "sms",
  "message": "40% off everything! Code: SPRING2025",
  "contactList": "active_customers",
  "scheduledTime": "2025-04-15T10:00:00Z"
}

Two-Step Campaign (SMS + WhatsApp)

1. Send SMS to all contacts (fast, high reach)
2. Send WhatsApp to engaged users only (high engagement)

{
  "name": "Important Update - SMS Phase",
  "channel": "sms",
  "message": "Account update required. Tap here: https://example.com/update",
  "contactList": "all_users",
  "sendImmediately": true
}

Then later:

{
  "name": "Important Update - WhatsApp Phase",
  "channel": "whatsapp",
  "message": "template_id_approved_by_meta",
  "contactList": "engaged_users",
  "scheduledTime": "2025-04-16T14:00:00Z"
}

Transactional Campaign (Order Confirmations)

Use the single-message endpoint instead:

curl -X POST https://lora-api.agiletelecom.com/api/message-server/sms/send \
  -H "X-Api-Key: your_api_key_here" \
  -d '{
    "phoneNumber": "+393901234567",
    "message": "Order confirmed. Tracking: https://example.com/track/12345"
  }'

Campaigns are for bulk sends. For individual transactional messages, use the direct send endpoint.

Next Steps

• Quick Start — Send your first message
• Webhooks — Track campaign delivery in real-time
• Messaging Channels — Choose the best channel

Have questions? Contact support@agiletelecom.com.