API reference

Campaigns

Bulk WhatsApp campaigns with pacing, stagger, warmth checks, scheduling, pause/stop/retry, and per-recipient analytics.

Create a draft with a message (or uploaded media), a session (accountId or sessionId), and an audience (recipients phone list, groupId, or groupIds). Start immediately or schedule. Campaigns require an active subscription and the campaigns feature flag.

Warmth, pacing, and audience

Call POST /api/campaigns/warmth-check before a large send. New linked devices should warm up. Recipients who have never messaged you can still be targeted; use smaller batches for cold lists. Number-check contacts first to skip numbers that are not on WhatsApp.

  • Sends are serialized per session with jittered delays.
  • One overlapping campaign per device is limited to protect the linked session.
  • Pause to halt temporarily; stop/cancel ends the run; retry re-queues failures.
  • Placeholders such as {{name}} are substituted from the contact record.
GET/api/campaigns

List campaigns

Returns paginated campaigns for your account.

URL: https://api.actiwapi.com/api/campaigns

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Query parameters

  • page — Page number
  • status — Filter by status: draft, running, paused, completed

Code examples

curl -X GET "https://api.actiwapi.com/api/campaigns" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

{
  "success": true,
  "data": [{ "id": "uuid", "name": "March Promo", "status": "running", "sentCount": 120 }],
  "pagination": { "page": 1, "total": 5 }
}

Try in Swagger UI

POST/api/campaigns

Create campaign

Create a draft campaign. Provide recipients[], groupId, or groupIds[]. Message is required unless mediaUrl is set.

URL: https://api.actiwapi.com/api/campaigns

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Request example

{
  "name": "March Promo",
  "accountId": "uuid",
  "message": "Hello {{name}}, check out our offer!",
  "recipients": ["919876543210", "918765432109"],
  "groupIds": []
}

Code examples

curl -X POST "https://api.actiwapi.com/api/campaigns" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"
  -d '{  "name": "March Promo",  "accountId": "uuid",  "message": "Hello {{name}}, check out our offer!",  "recipients": ["919876543210", "918765432109"],  "groupIds": []}'

Response example201

{ "success": true, "data": { "id": "uuid", "status": "draft" } }

Try in Swagger UI

POST/api/campaigns/{id}/start

Start campaign

Start sending messages immediately.

URL: https://api.actiwapi.com/api/campaigns/{id}/start

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Campaign UUID

Code examples

curl -X POST "https://api.actiwapi.com/api/campaigns/{id}/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

{ "success": true, "data": { "id": "uuid", "status": "running" } }

Try in Swagger UI

POST/api/campaigns/{id}/pause

Pause campaign

Pause a running campaign.

URL: https://api.actiwapi.com/api/campaigns/{id}/pause

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Campaign UUID

Code examples

curl -X POST "https://api.actiwapi.com/api/campaigns/{id}/pause" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

{ "success": true, "data": { "status": "paused" } }

Try in Swagger UI

POST/api/campaigns/{id}/schedule

Schedule campaign

Schedule a campaign for future delivery.

URL: https://api.actiwapi.com/api/campaigns/{id}/schedule

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Campaign UUID

Request example

{ "scheduledAt": "2026-06-01T10:00:00.000Z" }

Code examples

curl -X POST "https://api.actiwapi.com/api/campaigns/{id}/schedule" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"
  -d '{ "scheduledAt": "2026-06-01T10:00:00.000Z" }'

Response example200

{ "success": true, "data": { "status": "scheduled" } }

Try in Swagger UI

GET/api/campaigns/{id}/analytics

Campaign analytics

Delivery statistics for a campaign.

URL: https://api.actiwapi.com/api/campaigns/{id}/analytics

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Campaign UUID

Code examples

curl -X GET "https://api.actiwapi.com/api/campaigns/{id}/analytics" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

{
  "success": true,
  "data": {
    "totalRecipients": 500,
    "sentCount": 320,
    "failedCount": 2,
    "deliveredCount": 300
  }
}

Try in Swagger UI

POST/api/campaigns/{id}/stop

Stop campaign

Cancel a running campaign. Further recipients are not sent.

URL: https://api.actiwapi.com/api/campaigns/{id}/stop

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Campaign UUID

Code examples

curl -X POST "https://api.actiwapi.com/api/campaigns/{id}/stop" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

{ "success": true, "data": { "status": "cancelled" } }

Try in Swagger UI

POST/api/campaigns/{id}/retry

Retry failed recipients

Re-queue failed recipients. Optional scheduledAt for a later retry.

URL: https://api.actiwapi.com/api/campaigns/{id}/retry

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Campaign UUID

Request example

{ "scheduledAt": "2026-06-01T10:00:00.000Z" }

Code examples

curl -X POST "https://api.actiwapi.com/api/campaigns/{id}/retry" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"
  -d '{ "scheduledAt": "2026-06-01T10:00:00.000Z" }'

Response example200

{ "success": true, "data": { "status": "running" } }

Try in Swagger UI

GET/api/campaigns/{id}/recipients

List recipients

Per-number send status for a campaign.

URL: https://api.actiwapi.com/api/campaigns/{id}/recipients

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Campaign UUID

Code examples

curl -X GET "https://api.actiwapi.com/api/campaigns/{id}/recipients" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

{
  "success": true,
  "data": [{ "phone": "919876543210", "status": "sent" }]
}

Try in Swagger UI

POST/api/campaigns/warmth-check

Warmth check

Evaluate whether a session/audience is ready for bulk send.

URL: https://api.actiwapi.com/api/campaigns/warmth-check

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Request example

{ "accountId": "uuid", "recipientCount": 500 }

Code examples

curl -X POST "https://api.actiwapi.com/api/campaigns/warmth-check" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"
  -d '{ "accountId": "uuid", "recipientCount": 500 }'

Response example200

{
  "success": true,
  "data": { "ready": false, "warnings": ["Device is newly linked"] }
}

Try in Swagger UI

GET/api/campaigns/dashboard

Campaign dashboard

Aggregate campaign metrics for the workspace.

URL: https://api.actiwapi.com/api/campaigns/dashboard

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Code examples

curl -X GET "https://api.actiwapi.com/api/campaigns/dashboard" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

{
  "success": true,
  "data": { "running": 1, "completed": 12, "sentToday": 840 }
}

Try in Swagger UI

Error codes

Failed requests return a JSON envelope with success: false and a human-readable message.

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "phone": "Valid phone number is required"
  }
}
HTTPCodeDescription
400VALIDATION_ERRORRequest body or query failed validation.
401UNAUTHORIZEDMissing or invalid JWT / API key.
403FORBIDDENAuthenticated but lacking permission or entitlement.
403SUBSCRIPTION_INACTIVEAction not allowed on the current plan (including Free after trial). Upgrade or wait for entitlements.
403LIMIT_EXCEEDEDPlan limit reached (sessions, messages, API requests, etc.).
404NOT_FOUNDResource does not exist or is not in your account.
409CONFLICTDuplicate resource or invalid state transition.
429RATE_LIMITEDToo many requests; retry after backoff.
500INTERNAL_ERRORUnexpected server error.
502WHATSAPP_UNAVAILABLEWhatsApp session disconnected or provider error.