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	Page size, 1–100. Default 50.
status	string	Filter by status
whatsapp_account	string	Filter by WhatsApp account name
search	string	Case-insensitive match on the campaign name
from / to	string	YYYY-MM-DD range filter on created_at (to is inclusive of the whole day)

Ordered by created_at DESC.

Response

{
  "status": "success",
  "data": {
    "campaigns": [
      {
        "id": "uuid",
        "name": "Holiday Promotion",
        "whatsapp_account": "Main Business",
        "template_id": "uuid",
        "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_by_name": "Jane Admin",
        "updated_by_name": "Jane Admin",
        "created_at": "2024-01-01T09:00:00Z",
        "updated_at": "2024-01-01T10:30:00Z"
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 50,
    "summary": {
      "campaigns": 25,
      "sending": 1,
      "sent": 18400,
      "delivered": 17650,
      "read": 11200,
      "replied": 940,
      "failed": 310
    }
  }
}

summary adds up every campaign the filters match, not just this page: how many there are, how many are sending now (queued or processing), and their message counts.

Note

The account is referenced by name via whatsapp_account — there is no account_id field. Campaigns that use a media header also return header_media_id, header_media_filename and header_media_mime_type.

Get Campaign

Retrieve a single campaign with detailed progress.

GET/api/campaigns/{id}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Holiday Promotion",
    "template_id": "uuid",
    "template_name": "holiday_offer",
    "whatsapp_account": "Main Business",
    "status": "processing",
    "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:05:00Z"
  }
}

Create Campaign

Create a new campaign. Per-recipient template values are supplied when you import recipients, not on the campaign itself — there is no variable_mapping field.

POST/api/campaigns

Request Body

{
  "name": "New Year Sale",
  "whatsapp_account": "Main Business",
  "template_id": "uuid",
  "header_media_id": "",
  "scheduled_at": "2024-01-01T00:00:00Z"
}

Field	Type	Required	Description
name	string	Yes	Campaign name
whatsapp_account	string	Yes	Name of the sending WhatsApp account
template_id	uuid	Yes	Template to send
header_media_id	string	No	Meta media ID for a media-header template — upload it first with POST /api/campaigns/{id}/media
scheduled_at	string	No	ISO-8601 time to start the campaign

Response

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

Update Campaign

Update a draft campaign.

PUT/api/campaigns/{id}

Note

Only draft campaigns can be updated. Started or completed campaigns cannot be modified.

Delete Campaign

Delete a campaign.

DELETE/api/campaigns/{id}

Import Recipients

Import recipients from a CSV or JSON file.

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": {
    "message": "Recipients added successfully",
    "added_count": 2,
    "total_recipients": 1002
  }
}

added_count is the number of recipients in this request; total_recipients is the campaign’s new total.

Get Recipients

Get all recipients of a campaign with their per-recipient delivery status. This endpoint returns the full recipient list for the campaign — it is not paginated.

GET/api/campaigns/{id}/recipients

Response

The recipients array holds every recipient; total is the count.

{
  "status": "success",
  "data": {
    "recipients": [
      {
        "id": "uuid",
        "campaign_id": "uuid",
        "phone_number": "1234567890",
        "recipient_name": "John Doe",
        "status": "delivered",
        "template_params": { "customer_name": "John", "coupon": "SAVE20" },
        "header_params": { "season": "Summer" },
        "whatsapp_message_id": "wamid.xxx",
        "error_message": "",
        "sent_at": "2024-01-01T10:00:10Z",
        "delivered_at": "2024-01-01T10:00:15Z",
        "read_at": "2024-01-01T10:05:00Z"
      }
    ],
    "total": 1000
  }
}

Field	Type	Description
phone_number	string	Recipient phone number
recipient_name	string	Recipient display name
status	string	pending, sent, delivered, read, or failed
template_params	object	Body parameter values used for this recipient
header_params	object	TEXT-header parameter values (if any)
whatsapp_message_id	string	Meta message ID once sent
error_message	string	Failure reason when status is failed
sent_at / delivered_at / read_at	string	Delivery timestamps (null until reached)

Note

When phone-number masking is enabled for the organization, phone_number and any phone-like recipient_name values are masked in the response.

Delete Recipient

Remove a single recipient from a campaign. Only allowed while the campaign is in draft status.

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

Response

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

Upload Campaign Media

Upload the media asset for a campaign whose template has a media header (image, video, or document). Allowed only for draft campaigns whose template has a non-TEXT header. The file is uploaded to WhatsApp and stored locally for preview.

POST/api/campaigns/{id}/media

Send the request as multipart/form-data with a file field (max 16 MB).

curl -X POST "http://your-server:8080/api/campaigns/{id}/media" \
  -H "X-API-Key: soosh_your_api_key" \
  -F "[email protected]"

Response

{
  "status": "success",
  "data": {
    "media_id": "meta-media-id",
    "filename": "banner.jpg",
    "mime_type": "image/jpeg",
    "local_path": "campaigns/uuid.jpg",
    "message": "Media uploaded successfully"
  }
}

Get Campaign Media

Serve the previously uploaded campaign media file (used for previews). Returns the raw media bytes, not a JSON envelope.

GET/api/campaigns/{id}/media

Campaign Actions

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

Re-queue every recipient whose delivery failed. Allowed only on completed, paused, or failed campaigns. Failed recipients are reset to pending, the campaign moves back to processing, and the messages are re-enqueued.

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

Response

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

Get Progress

Fetch live progress for a campaign. This returns the same payload as Get Campaign (status plus sent/delivered/read/failed counts) and is convenient for polling while a campaign is sending.

GET/api/campaigns/{id}/progress

Campaign Status

Status	Description
draft	Campaign created, not yet started
scheduled	Campaign scheduled for future sending
queued	Recipients have been pushed onto the Redis job queue
processing	Workers are actively sending messages
paused	Campaign is paused. When the system paused it (such as at the monthly broadcast limit), paused_reason says why
completed	All messages have been processed
cancelled	Campaign was cancelled
failed	The campaign could not be processed

Monthly Broadcast Limit

A super administrator can give a workspace a monthly limit on campaign messages (the broadcast_messages_per_month workspace limit). Every campaign message sent counts, and a retried one counts again; a send that fails doesn’t count. Months are calendar months in UTC.

• When the month is used up, running campaigns pause with paused_reason set, and their unsent recipients stay pending. Resume them next month, or once the limit is raised.
• Start and Retry Failed answer 403 with the reason while the month is used up.

GET/api/campaigns/usage

{
  "status": "success",
  "data": { "used": 8200, "limit": 10000, "period": "2026-10", "resets_at": "2026-11-01T00:00:00Z" }
}

limit is null when the workspace has no monthly limit; messages are counted either way.

Throughput

Sends are dispatched through a Redis Streams job queue and consumed by worker processes. Throughput is governed by how many workers you run (-workers=N on server or worker), not by a built-in per-second throttle — Soosh does not shape traffic to your Meta messaging tier. If you exceed your tier, Meta rejects the sends and the affected recipients are marked failed; use Retry Failed once your limits allow.

Tip

Start with smaller campaigns to warm up your account and improve your messaging tier.