Skip to content
Whatomate

Campaigns

Overview

Section titled “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

Section titled “List Campaigns”

Retrieve all campaigns.

Terminal window
GET /api/campaigns

Query Parameters

Section titled “Query Parameters”

| Parameter | Type | Description | |-----------|------|-------------| | page | integer | Page number (default: 1) | | limit | integer | Items per page (default: 20) | | status | string | Filter by status | | account_id | string | Filter by WhatsApp account |

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Holiday Promotion",
        "template_id": "uuid",
        "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"
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 20
  }
}

Get Campaign

Section titled “Get Campaign”

Retrieve a single campaign with detailed progress.

Terminal window
GET /api/campaigns/{id}

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Holiday Promotion",
    "template_id": "uuid",
    "template_name": "holiday_offer",
    "account_id": "uuid",
    "status": "sending",
    "total_recipients": 1000,
    "sent_count": 450,
    "delivered_count": 400,
    "read_count": 100,
    "failed_count": 10,
    "variable_mapping": {
      "1": "name",
      "2": "discount_code"
    },
    "scheduled_at": null,
    "started_at": "2024-01-01T10:00:05Z",
    "created_at": "2024-01-01T09:00:00Z"
  }
}

Create Campaign

Section titled “Create Campaign”

Create a new campaign.

Terminal window
POST /api/campaigns

Request Body

Section titled “Request Body”
{
  "name": "New Year Sale",
  "account_id": "uuid",
  "template_id": "uuid",
  "variable_mapping": {
    "1": "name",
    "2": "discount_code"
  },
  "scheduled_at": "2024-01-01T00:00:00Z"
}

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "New Year Sale",
    "status": "draft",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Update Campaign

Section titled “Update Campaign”

Update a draft campaign.

Terminal window
PUT /api/campaigns/{id}

Delete Campaign

Section titled “Delete Campaign”

Delete a campaign.

Terminal window
DELETE /api/campaigns/{id}

Import Recipients

Section titled “Import Recipients”

Import recipients from a CSV or JSON file.

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

Request Body (JSON)

Section titled “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

Section titled “Response”
{
  "status": "success",
  "data": {
    "imported": 2,
    "duplicates": 0,
    "invalid": 0
  }
}

Get Recipients

Section titled “Get Recipients”

Get campaign recipients with their delivery status.

Terminal window
GET /api/campaigns/{id}/recipients

Query Parameters

Section titled “Query Parameters”

| Parameter | Type | Description | |-----------|------|-------------| | page | integer | Page number | | limit | integer | Items per page | | status | string | Filter by status |

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "phone_number": "+1234567890",
        "name": "John Doe",
        "status": "delivered",
        "sent_at": "2024-01-01T10:00:10Z",
        "delivered_at": "2024-01-01T10:00:15Z"
      }
    ],
    "total": 1000,
    "page": 1,
    "limit": 50
  }
}

Campaign Actions

Section titled “Campaign Actions”

Start Campaign

Section titled “Start Campaign”

Begin sending messages.

Terminal window
POST /api/campaigns/{id}/start

Pause Campaign

Section titled “Pause Campaign”

Pause a running campaign.

Terminal window
POST /api/campaigns/{id}/pause

Cancel Campaign

Section titled “Cancel Campaign”

Cancel a campaign (cannot be resumed).

Terminal window
POST /api/campaigns/{id}/cancel

Campaign Status

Section titled “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 |

Rate Limiting

Section titled “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 |