Campaigns
List campaigns
Lists the campaigns of the organization, newest first. Read only. It is safe to repeat.
Required scope: whatsapp:read.
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
statusHeaders
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List campaigns › Responses
objecthasMorenextCursorCreate a campaign
Starts as a draft. Nothing goes out until you launch it, and no person has to approve it. Use dryRun=true to run the same checks (audience, schedule, template, variables, onReply) and get 200 with the draft as it would be saved; nothing is saved and its id is not saved.
Required scope: whatsapp:write.
query Parameters
dryRunWhen true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus dryRun: true; an id in it is not saved. It does not use the Idempotency-Key.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Create a campaign › Request Body
nametemplateIdcontactFilter or externalRefs.
Template variable to contact.name, contact.phone, contact.email or contact.externalRef. Any other text is used as is.
What the template needs besides its variables: image or video header, products, Flow data, cards.
Create a campaign › Responses
dryRun=true: the draft as it would be saved.
objectidnamestatustemplateIdThe components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.
The document header saved on the campaign, as you sent it. null when it has none.
Who continues the conversation if the contact answers, as you sent it. null when it was not set.
pauseReasonWhy it paused by itself, if it did.
launchedAtcreatedAtupdatedAtdryRunPresent and true when the request had dryRun=true.
Retrieve a campaign
Returns one campaign by id. Use it to refresh a single record you already know; to find records, use the list route. It includes the counts by recipient status. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.
Required scope: whatsapp:read.
path Parameters
id^cmp_[0-9A-Za-z]{22}… · requiredThe id of the campaign (cmp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Retrieve a campaign › Responses
objectidnamestatustemplateIdThe components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.
The document header saved on the campaign, as you sent it. null when it has none.
Who continues the conversation if the contact answers, as you sent it. null when it was not set.
pauseReasonWhy it paused by itself, if it did.
launchedAtcreatedAtupdatedAtDelete a campaign
Cancel a running campaign first: answers 409 while it is scheduled, sending or paused.
Required scope: whatsapp:write.
path Parameters
id^cmp_[0-9A-Za-z]{22}… · requiredThe id of the campaign (cmp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Delete a campaign › Responses
Update a campaign
Only a draft can be edited. Answers 409 otherwise. Use dryRun=true to run the same checks and get the campaign as it would be saved, without saving it.
Required scope: whatsapp:write.
path Parameters
id^cmp_[0-9A-Za-z]{22}… · requiredThe id of the campaign (cmp_…).
query Parameters
dryRunWhen true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus dryRun: true; an id in it is not saved. It does not use the Idempotency-Key.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Update a campaign › Request Body optional
nametemplateIdSend null to remove the saved document header.
What the template needs besides its variables: image or video header, products, Flow data, cards. Send null to remove the saved components.
Send null to remove who continues if they answer.
Update a campaign › Responses
objectidnamestatustemplateIdThe components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.
The document header saved on the campaign, as you sent it. null when it has none.
Who continues the conversation if the contact answers, as you sent it. null when it was not set.
pauseReasonWhy it paused by itself, if it did.
launchedAtcreatedAtupdatedAtdryRunPresent and true when the request had dryRun=true.
Preview a campaign
Who gets it, who is skipped and why, a rendered sample and the estimated cost at the list rate of the Meta rate card (never null).
Required scope: whatsapp:read.
path Parameters
id^cmp_[0-9A-Za-z]{22}… · requiredThe id of the campaign (cmp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Preview a campaign › Responses
objectrecipientsContacts that would get the message.
sampleList price of the messages that would be sent: the rate of the template category in the market of each phone number, from the WhatsApp Business Platform rate card published by Meta (https://developers.facebook.com/docs/whatsapp/pricing). It is the list rate before the volume tiers of utility and authentication messages, so the real charge can be lower; it is zero when nobody would receive the message.
Launch a campaign
Freezes the recipient list and starts at schedule.at, in batches inside the daily window. Launching twice answers 409; a restart in the middle never sends twice to the same contact. It sends messages that cost money and cannot be undone: use dryRun=true first, which checks the template and the state and answers with the campaign in the status it would take (scheduled or sending), without freezing the list or sending anything; use POST /v2/campaigns/{id}/preview for the recipients and the cost.
Required scope: whatsapp:write.
path Parameters
id^cmp_[0-9A-Za-z]{22}… · requiredThe id of the campaign (cmp_…).
query Parameters
dryRunWhen true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus dryRun: true; an id in it is not saved. It does not use the Idempotency-Key.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Launch a campaign › Responses
objectidnamestatustemplateIdThe components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.
The document header saved on the campaign, as you sent it. null when it has none.
Who continues the conversation if the contact answers, as you sent it. null when it was not set.
pauseReasonWhy it paused by itself, if it did.
launchedAtcreatedAtupdatedAtdryRunPresent and true when the request had dryRun=true.
Pause a campaign
Pauses a campaign that is scheduled or sending. Messages already sent are not recalled; the pending recipients wait until you resume. 409 conflict when the campaign is in any other state. Pausing a paused campaign is a 409, not a second pause.
Required scope: whatsapp:write.
path Parameters
id^cmp_[0-9A-Za-z]{22}… · requiredThe id of the campaign (cmp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Pause a campaign › Responses
objectidnamestatustemplateIdThe components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.
The document header saved on the campaign, as you sent it. null when it has none.
Who continues the conversation if the contact answers, as you sent it. null when it was not set.
pauseReasonWhy it paused by itself, if it did.
launchedAtcreatedAtupdatedAtResume a campaign
Resumes a paused campaign and queues its pending recipients, so messages leave and cost money. A campaign whose schedule is still in the future goes back to scheduled. 409 conflict when the campaign is not paused. Use dryRun=true to check the state and see the status it would take, without queueing anything.
Required scope: whatsapp:write.
path Parameters
id^cmp_[0-9A-Za-z]{22}… · requiredThe id of the campaign (cmp_…).
query Parameters
dryRunWhen true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus dryRun: true; an id in it is not saved. It does not use the Idempotency-Key.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Resume a campaign › Responses
objectidnamestatustemplateIdThe components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.
The document header saved on the campaign, as you sent it. null when it has none.
Who continues the conversation if the contact answers, as you sent it. null when it was not set.
pauseReasonWhy it paused by itself, if it did.
launchedAtcreatedAtupdatedAtdryRunPresent and true when the request had dryRun=true.
Cancel a campaign
What was not sent yet is not sent. What already went out stays.
Required scope: whatsapp:write.
path Parameters
id^cmp_[0-9A-Za-z]{22}… · requiredThe id of the campaign (cmp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Cancel a campaign › Responses
objectidnamestatustemplateIdThe components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.
The document header saved on the campaign, as you sent it. null when it has none.
Who continues the conversation if the contact answers, as you sent it. null when it was not set.
pauseReasonWhy it paused by itself, if it did.
launchedAtcreatedAtupdatedAtList recipients
Lists the recipients of a campaign with the status of each one: pending, queued, sent, delivered, read, failed or skipped. Use it to see who did not receive the message and why. Read only. It is safe to repeat.
Required scope: whatsapp:read.
path Parameters
id^cmp_[0-9A-Za-z]{22}… · requiredThe id of the campaign (cmp_…).
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
statusHeaders
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List recipients › Responses
objecthasMorenextCursor