Campaigns

Overview

Campaigns allow you to send bulk WhatsApp messages to multiple contacts using approved templates. The API handles rate limiting and delivery tracking automatically.

List Campaigns

Retrieve all campaigns.

GET /api/campaigns

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20)
`status`	string	Filter by status (draft, scheduled, sending, paused, completed, cancelled)
`whatsapp_account`	string	Filter by WhatsApp account name
`search`	string	Search campaign name (case-insensitive)
`from`	string	ISO date string - filter campaigns created on or after this date
`to`	string	ISO date string - filter campaigns created on or before this date

Response

{
  "status": "success",
  "data": {
    "campaigns": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Holiday Promotion",
        "whatsapp_account": "default_account",
        "template_id": "880e8400-e29b-41d4-a716-446655440000",
        "template_name": "holiday_offer",
        "status": "completed",
        "total_recipients": 1000,
        "sent_count": 1000,
        "delivered_count": 950,
        "read_count": 500,
        "failed_count": 50,
        "scheduled_at": "2024-01-01T10:00:00Z",
        "started_at": "2024-01-01T10:00:05Z",
        "completed_at": "2024-01-01T10:30:00Z",
        "created_at": "2024-01-01T09:00:00Z",
        "updated_at": "2024-01-01T10:30:00Z"
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 20
  }
}

Get Campaign

Retrieve a single campaign with detailed progress.

GET /api/campaigns/{id}

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Holiday Promotion",
    "whatsapp_account": "default_account",
    "template_id": "880e8400-e29b-41d4-a716-446655440000",
    "template_name": "holiday_offer",
    "status": "sending",
    "total_recipients": 1000,
    "sent_count": 450,
    "delivered_count": 400,
    "read_count": 100,
    "failed_count": 10,
    "scheduled_at": null,
    "started_at": "2024-01-01T10:00:05Z",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  }
}

Create Campaign

Create a new campaign.

POST /api/campaigns

Request Body

Field	Type	Required	Description
`name`	string	Yes	Campaign name
`whatsapp_account`	string	Yes	WhatsApp account name
`template_id`	string	Yes	UUID of template to use
`header_media_id`	string	No	Already-uploaded WhatsApp media ID for header
`scheduled_at`	string	No	Optional ISO date-time string to schedule campaign

{
  "name": "New Year Sale",
  "whatsapp_account": "default_account",
  "template_id": "880e8400-e29b-41d4-a716-446655440000",
  "scheduled_at": "2024-01-01T12:00:00Z"
}

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "New Year Sale",
    "whatsapp_account": "default_account",
    "template_id": "880e8400-e29b-41d4-a716-446655440000",
    "status": "draft",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Update Campaign

Update a draft campaign.

PUT /api/campaigns/{id}

Request Body

Same structure as Create Campaign. Only fields provided will be updated.

Delete Campaign

Delete a campaign.

DELETE /api/campaigns/{id}

Upload Campaign Media

Upload a media file (image, video, document, audio) to WhatsApp to use as the template’s media header for the campaign.

This endpoint accepts multipart/form-data.

POST /api/campaigns/{id}/media

Request Payload

Field	Type	Required	Description
`file`	file binary	Yes	The header media file to upload

Response

{
  "status": "success",
  "data": {
    "media_id": "990e8400-e29b-41d4-a716-446655440000",
    "filename": "banner.png",
    "mime_type": "image/png",
    "local_path": "/media/campaigns/550e8400-e29b-41d4-a716-446655440000.png",
    "message": "Media uploaded successfully"
  }
}

Import Recipients

Import recipients for a campaign. You should supply parameters on a per-recipient basis here.

POST /api/campaigns/{id}/recipients/import

Request Body (JSON)

{
  "recipients": [
    {
      "phone_number": "+1234567890",
      "recipient_name": "John Doe",
      "template_params": { "customer_name": "John", "coupon": "SAVE20" },
      "header_params": { "season": "Summer" }
    },
    {
      "phone_number": "+0987654321",
      "recipient_name": "Jane Smith",
      "template_params": { "customer_name": "Jane", "coupon": "SAVE15" },
      "header_params": { "season": "Winter" }
    }
  ]
}

header_params is only needed for templates with a TEXT header variable (Meta allows at most one). It’s kept separate from template_params so a positional header {{1}} doesn’t collide with body {{1}}. Omit the field entirely for templates without a header variable.

Response

{
  "status": "success",
  "data": {
    "imported": 2,
    "duplicates": 0,
    "invalid": 0
  }
}

Get Recipients

Get campaign recipients with their delivery status.

GET /api/campaigns/{id}/recipients

Response

{
  "status": "success",
  "data": {
    "recipients": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440000",
        "phone_number": "+1234567890",
        "recipient_name": "John Doe",
        "status": "delivered",
        "sent_at": "2024-01-01T10:00:10Z",
        "delivered_at": "2024-01-01T10:00:15Z"
      }
    ],
    "total": 1
  }
}

Delete Recipient

Delete a single recipient from a campaign.

DELETE /api/campaigns/{id}/recipients/{recipientId}

Response

{
  "status": "success",
  "data": {
    "message": "Recipient deleted successfully"
  }
}

Start Campaign

Begin sending messages.

POST /api/campaigns/{id}/start

Pause Campaign

Pause a running campaign.

POST /api/campaigns/{id}/pause

Cancel Campaign

Cancel a campaign (cannot be resumed).

POST /api/campaigns/{id}/cancel

Retry Failed Recipients

Reset all failed recipients to pending and retry sending messages to them.

POST /api/campaigns/{id}/retry-failed

Response

{
  "status": "success",
  "data": {
    "message": "Retrying failed messages",
    "retry_count": 5,
    "status": "processing"
  }
}

Campaign Status

Status	Description
`draft`	Campaign created, not yet started
`scheduled`	Campaign scheduled for future sending
`sending`	Campaign is actively sending messages
`paused`	Campaign is paused
`completed`	All messages have been processed
`cancelled`	Campaign was cancelled
`failed`	Campaign failed

Rate Limiting

Campaigns automatically respect WhatsApp’s rate limits:

Tier	Messages per second
TIER_1K	~10 msg/sec
TIER_10K	~30 msg/sec
TIER_100K	~80 msg/sec
TIER_UNLIMITED	No limit