Create a campaign

Create and submit a bulk WhatsApp campaign in one call.

POSThttps://nextgenpanelstaging.cloudshope.com/api/v1/whatsapp/campaigns/createCampaign

Creates the campaign and immediately queues the sends — this is not a draft. Credit is checked and reserved up front; invalid, duplicate and blacklisted numbers are trimmed automatically.

Provide one of template_id (a Meta-approved message template), flow_id (a WhatsApp Flow) or automation_flow_id (an Automation-module flow). If you send more than one, automation_flow_id is used first, then flow_id, then template_id. contacts is one row per recipient, each with its own variables map for template placeholders.

Omit scheduled_at to send now, or pass a future ISO 8601 timestamp to schedule. A past or current timestamp is treated as send-now. Scheduled sends, MM Lite, WhatsApp Flows and Automation campaigns each need that feature on your plan.

Automation campaigns finish immediately: the response already has status: "completed" and type: "automation". The response carries a Location header pointing at the new campaign.

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. A 429 adds Retry-After. Limits are per account: 100 requests per minute for reads, 20 per minute for writes (create, cancel, relaunch, duplicate).

Authentication

Send Authorization: Bearer <token>. The account needs the Bulk WhatsApp feature. Agent logins also need the Bulk WhatsApp permission on their role, and can only use their assigned WABA numbers.

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	Yes	A unique key you choose per operation. A retry with the same key returns the original response (with an `Idempotency-Replayed: true` header) instead of sending again. Use a different key for each distinct operation.

Body parameters

Name	Type	Required	Description
`name`	string	Yes	Campaign name, up to 255 characters.
`waba_number_id`	integer	Yes	Id of the WABA number to send from.
`template_id`	integer	No	Approved message template id. One of template_id / flow_id / automation_flow_id.
`flow_id`	integer	No	WhatsApp Flow id.
`automation_flow_id`	string	No	Automation-module flow id.
`automation_flow_name`	string	No	Display label for the Automation flow, 1–255 characters. Only used with `automation_flow_id`.
`contacts`	object[]	Yes	`{ phone_number, variables }` per recipient; at least one valid number is needed. `phone_number` must be 10–15 digits (non-digits are stripped); invalid, duplicate and blacklisted numbers are dropped, and repeats are not sent or charged. `variables` is a `{ key: value }` map of strings. Reserved keys `header_media_url` (an http(s) URL) and `header_filename` set a per-recipient header file.
`scheduled_at`	string · ISO 8601	No	Future UTC timestamp (e.g. `2026-09-25T10:00:00Z`) to schedule. Omit or null to send now.
`mm_lite`	boolean	No	Marketing-template routing hint. Needs a Marketing-category template; ignored for Flow campaigns.

Request

curl -X POST https://nextgenpanelstaging.cloudshope.com/api/v1/whatsapp/campaigns/createCampaign \
  -H "Authorization: Bearer cs_live_9f2c…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c2f9e1a-order-updates-2026-09-20" \
  -d '{
    "name": "Order updates",
    "waba_number_id": 4,
    "template_id": 88,
    "contacts": [
      { "phone_number": "919876543210", "variables": { "1": "Ravi", "2": "#4021" } }
    ]
  }'

Response

{
  "id": 905,
  "name": "Order updates",
  "type": "template",
  "status": "running",
  "scheduled_at": null,
  "total_contacts": 1,
  "invalid_count": 0,
  "duplicate_count": 0,
  "sent_count": 0,
  "delivered_count": 0,
  "read_count": 0,
  "failed_count": 0,
  "pending_count": 1,
  "response_count": 0,
  "templates": { "name": "order_shipped", "category": "UTILITY", "language": "en" },
  "waba_numbers": { "whatsapp_name": "Acme", "whatsapp_number": "918000000000" },
  "created_at": "2026-09-20T11:03:00.000Z",
  "updated_at": "2026-09-20T11:03:00.000Z"
}

201 — example response

Errors

Status	Type	When
400	`bad-request`	The `Idempotency-Key` header is missing.
403	`forbidden`	The plan does not include scheduled sends, MM Lite, WhatsApp Flows or Automation campaigns, whichever the request uses.
404	`not-found`	The WABA number, template, Flow or Automation flow does not exist on the account.
409	`insufficient-credit`	Not enough WhatsApp credit for the recipient count.
422	`validation-error`	None of template_id / flow_id / automation_flow_id given; the template is not Approved or the Flow is not Published; `mm_lite` with a non-Marketing template; or no valid contacts remain after removing invalid, duplicate and blacklisted numbers.
429	`rate-limited`	Too many writes in the current window. Retry after `Retry-After` seconds.
422	`validation-failed`	A field failed validation. The `errors` array names each field and why.
401	`unauthorized`	The `Authorization` header is missing, malformed or the token is invalid or expired.
403	`forbidden`	The token is valid but the account is not allowed to perform this action.