MCP is live.Set upAsk the community
OmniDimension
Dashboard
DocumentationAPI referenceSDKsMCP
WhatsApp

Launch a campaign

Start a draft campaign: every pending contact is queued once. Needs at least one contact, unless the campaign's data_source is webhook. The plan's monthly broadcast allowance and the wallet balance are checked here. Idempotency-Key is required, so a retry does not start it twice.

Set up WhatsApp first. Connect a WhatsApp number in the dashboard or with Connect numbers. Included on every paid plan. See plans.

POST/whatsapp/campaigns//launch
Path parameters
campaign_idrequired
curl -X POST 'https://backend.omnidim.io/api/v1/whatsapp/campaigns/{campaign_id}/launch' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Example response
synthetic
{
  "id": 0,
  "name": "string",
  "status": "draft",
  "pause_reason": "human",
  "campaign_mode": "broadcast",
  "send_mode": "review",
  "data_source": "csv",
  "is_dynamic": false,
  "phone_number_id": 0,
  "template": {
    "id": 0,
    "name": "string"
  },
  "agent_id": 0,
  "variable_mapping": "string",
  "counts": {
    "total": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "replied": 0,
    "failed": 0,
    "skipped": 0,
    "opted_out": 0
  },
  "receipts_reported": false,
  "delivery_rate": 0,
  "read_rate": 0,
  "reply_rate": 0,
  "spend": {
    "amount": 0,
    "currency": "USD"
  },
  "created_at": "string",
  "enqueued": 0
}

Authorization

BearerAuth
headerAuthorizationBearer <token>

Bearer token authentication. Obtain your API key from the OmniDimension dashboard.

Path Parameters

campaign_id*integer

Id of a WhatsApp campaign, from listWhatsappCampaigns.

Header Parameters

Idempotency-Key*string

A unique string you choose, up to 255 characters. Required on this route. The same key with the same body replays the first answer for 24 hours instead of acting twice. A different body with the same key answers 409.

Lengthlength <= 255

Response body

application/json

Response Body

The campaign, with the number of contacts queued.

application/json
id?integer
name?string
status?string
Value in"draft""scheduled""in_progress""paused""completed""failed""cancelled"
pause_reason?string

Why it paused, or null. Only human waits for you; the rest resume on their own.

Value in"human""balance""channel_down""monthly_limit"
campaign_mode?string
Value in"broadcast""broadcast_reply"
send_mode?string
Value in"review""on_arrival"
data_source?string
Value in"csv""webhook"
is_dynamic?boolean
phone_number_id?integer
template?
agent_id?integer

The agent that answers replies, when one is attached.

variable_mapping?

Template field to contact field or static text.

counts?
receipts_reported?boolean

This number reports delivery and read receipts, so the rates are real.

delivery_rate?number

Delivered as a percentage of sent. Null when receipts are not reported.

read_rate?number

Read as a percentage of delivered. Null when receipts are not reported.

reply_rate?number

Replied as a percentage of sent.

spend?

What the campaign cost so far. Null without billing access.

created_at?string
enqueued?integer

Add campaign contacts

Add one contact, or up to 500 at once. On a draft they are stored for launch. On a running campaign they are sent now. A contact already in the campaign is skipped, so a retry is safe. Each contact needs a phone_number; every other key is kept and can fill a template parameter through variable_mapping.

Pause a campaign

Stop sending until you resume. Only a running campaign can be paused. A pause you make by hand is never resumed automatically.