Create Campaign

post

https://api.lodgestory.com/api/wp-crm/campaigns/{organisationId}

Create a campaign for a saved segment or up to 1,000 recipients, with an approved template (WhatsApp Official), a text (WhatsApp unofficial) or an email. Every slot of the template must be mapped — call Preview Campaign first to see the problems and a rendered sample without creating anything.

The campaign is prepared in the background (recipients matched to their chats, messages rendered): preparation.state is preparing until it is ready and the campaign sends at scheduleAt (or right away). Recipients who can't be messaged on the channel are skipped and counted in preparation.stats. Use GET …/{campaignId} or the campaign.completed webhook to follow it.

Security:

The organisationId in the URL must match the organisation your JWT was issued for — requests for a different organisation fail with 401.
Requires CRM_ADMIN, ACCOUNT_OWNER, or CRM_BOT role; other roles receive 403.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

organisationId

string

required

Your organisation UUID (returned as org from the /token endpoint).

Body Params

name

string

required

length ≤ 200

channelId

string

required

The channel to send from (WHATSAPP_OFFICIAL, WHATSAPP_UNOFFICIAL or EMAIL).

audience

object

required

message

object

What to send.

WhatsApp Official — an approved template. template is { "id": "…" } or { "name": "…", "language": "en_US" }; then map every slot the template has:

body — variables by placeholder: "1", "2"… (positional templates) or parameter names (named templates).
header.media (IMAGE / VIDEO / DOCUMENT header URL) or header.text (TEXT header variables).
buttons — by button position ("0", "1"…): the dynamic part of a URL button, or a copy-code offer code (≤ 15 characters).
limitedTimeOffer.expiresAt — when the template's offer has an expiry.
cards — carousel templates: one entry per card with media, body, buttons (URL suffixes, optional quick-reply payloads).

A value is a string (the same for everyone) or { "source": …, "value": …, "fallback": … } per recipient:

attribute — a segment / recipient attribute (e.g. offer_code),
member — name, phone, email or countrycode,
contact_field — the linked contact's field (firstName, lastName, email, phoneNumber, countryCode or a custom field id),
static — same as a plain string.

fallback is sent when the recipient has no value. "trackClicks": true on a body URL variable or a dynamic URL button counts clicks.

WhatsApp (unofficial) — { "text": "Hi {{name}}" }. Email — { "subject": "…", "html": "…", "text": "plain fallback" }; {{tokens}} resolve from attributes, then the contact.

messageFromCampaignId

string

Instead of message: reuse the message of one of your past campaigns (template, text or email), checked against the template as it is now.

scheduleAt

string

When to send (ISO 8601). Omit to send as soon as the audience is prepared.

silent

boolean

Defaults to true

Default true: chats the campaign creates stay out of the top of the chat list and sends don’t bump it — a reply surfaces the chat. Ignored on WhatsApp (unofficial).

retryFailedDelivery

boolean

Defaults to false

WhatsApp Official: re-send messages WhatsApp held for a temporary reason (e.g. the marketing frequency cap).

maxDeliveryRetries

number

1 to 10

Defaults to 3

deliveryRetrySpacingHours

number

2 to 72

Defaults to 6

maxAttempts

number

1 to 10

Defaults to 3

Send attempts per message on network / provider errors.

Headers

Idempotency-Key

string

Any unique string (≤ 255 printable characters), e.g. a UUID per campaign you intend to create. Repeating a request with the same key returns the campaign it created (200, Idempotent-Replayed: true) instead of creating another; the same key with a different body is a 422. Strongly recommended — retries after a timeout then never double-send.

Responses

200

Replayed — the campaign this Idempotency-Key already created

400

Bad request — the body is invalid; problems lists what does not fit the template or which recipients are invalid

401

Unauthorized — invalid/expired JWT or organisation ID does not match the token

403

Forbidden — role not permitted

404

Channel, template, segment or source campaign not found

422

Idempotency-Key reused with a different body

429

Too many requests

503

Campaign audiences are not available yet on this server

201Created