Sign in

v2

latestOpenAPI 3.1.02026-08-075421692.0 MB
Messaging Ads

Create Click-to-WhatsApp ad (deprecated)

Deprecated: use POST /v1/ads/messaging with destination: whatsapp. This endpoint stays available for back-compat; no removal planned.

Creates one or more Click-to-WhatsApp (CTWA) ads on Meta under a single campaign and ad set. When tapped, each ad opens a WhatsApp conversation with the business attached to the supplied Facebook Page. The full hierarchy (campaign, ad set, creative(s), ad(s)) is created and activated in one call. The CTA is locked to WHATSAPP_MESSAGE and the destination is hard-coded to api.whatsapp.com/send; Meta resolves the actual WhatsApp number from the Page-to-WA pairing configured in Page settings or Business Manager.

Supports two mutually-exclusive shapes:

  • Single-creative: supply top-level headline, body, and one of imageUrl / video. Creates 1 campaign + 1 ad set + 1 ad.

  • Multi-creative: supply a creatives[] array with N entries (each carrying its own headline, body, and image/video). Creates 1 campaign + 1 ad set + N ads sharing budget and targeting so Meta A/Bs the creatives inside a single auction instead of fragmenting budget across N parallel campaigns. Recommended when launching multiple creative variants for the same campaign.

Attach shape. Send adSetId (with either creative shape) to add the ads to an EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase — the way to refresh a CTWA creative without resetting delivery. The ad set then owns budget, targeting and schedule, so budgetAmount, budgetType, endDate, objective, countries, interests and audienceId are rejected with a 400 alongside it rather than silently dropped. The target ad set's destination_type must match the ad's destination (a WhatsApp ad needs a WHATSAPP ad set), otherwise Meta would accept an ad that never delivers.

Prerequisites enforced by Meta (surfaced as platform_error on failure): the Facebook Page must be paired with a verified WhatsApp Business number, the WhatsApp Business Account must be business-verified, and the Meta access token must carry ads_management.

post/v1/ads/ctwa

Request body

accountIdstring required

Facebook or Instagram SocialAccount ID.

adAccountIdstring required

Meta ad account ID, e.g. act_123456789.

namestring required

Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a " #N" suffix (1-indexed) so Ads Manager shows them as a numbered batch.

headlinestring

Single-creative shape only. Mutually exclusive with creatives[].

bodystring

Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with creatives[].

imageUrlstring uri

Image asset for single-creative shape. Mutually exclusive with video and with creatives[]. Required on the single-creative shape if video is not supplied.

adSetIdstring

Attach the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. It then owns budget, targeting and schedule, so budgetAmount, budgetType, endDate, objective, countries, interests and audienceId are rejected with a 400 alongside it. Its destination_type must match the ad's destination.

budgetAmountnumber

Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless adSetId is set, where the ad set owns it.

budgetType'daily' | 'lifetime'

Required unless adSetId is set.

currencystring

ISO 4217 currency code matching the ad account's currency (e.g. USD). Optional; Meta infers from the ad account when omitted.

endDatestring date-time

ISO 8601 datetime. Required when budgetType is lifetime.

countriesstring[]

ISO 3166-1 alpha-2 country codes. Defaults to ["US"] only when no other geo (cities, regions, zips, metros, customLocations) is supplied.

ageMininteger
ageMaxinteger
audienceIdstring

Custom audience ID to target.

advantageAudience0 | 1

Meta's Advantage+ audience expansion. 0 (default) keeps targeting strict; 1 lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it).

objective'OUTCOME_ENGAGEMENT' | 'OUTCOME_SALES' | 'OUTCOME_LEADS'

Defaults to OUTCOME_ENGAGEMENT. OUTCOME_SALES and OUTCOME_LEADS require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing.

bidStrategy'LOWEST_COST_WITHOUT_CAP' | 'LOWEST_COST_WITH_BID_CAP' | 'COST_CAP' | 'LOWEST_COST_WITH_MIN_ROAS'

Meta bid strategy applied to the shared ad set. Defaults to LOWEST_COST_WITHOUT_CAP (auto-bid) when omitted. LOWEST_COST_WITH_BID_CAP and COST_CAP require bidAmount. LOWEST_COST_WITH_MIN_ROAS requires roasAverageFloor. CTWA's optimization_goal is fixed to CONVERSATIONS, but the bid strategy is independent.

bidAmountnumber

Whole currency units (e.g. 5 = $5.00 on a USD account). Required when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP; rejected otherwise.

roasAverageFloornumber

Decimal ROAS multiplier (e.g. 2.0 = 2.0× ROAS floor). Required when bidStrategy is LOWEST_COST_WITH_MIN_ROAS; rejected otherwise. Meta enforces its own upper bound server-side.

dsaBeneficiarystring

Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via PATCH /v1/ads/accounts or in Meta Ads Manager, and Meta fills it in whenever the field is omitted.

dsaPayorstring

Legal entity that pays for the ad. Can differ from dsaBeneficiary (for example, an agency paying for a client's ads). Same rules as dsaBeneficiary: required for EU targeting unless the ad account has a default payor.

Response

CTWA ad(s) created and submitted to Meta for review. Response is a tagged union discriminated by adType:

  • adType: "single" → single-creative request: { adType, ad, message } where ad is the persisted Ad document.
  • adType: "multi" → multi-creative request: { adType, ads, platformCampaignId, platformAdSetId, message } where ads is the array of N persisted Ad documents all sharing the returned campaign and ad set IDs.

Generated SDK clients can narrow on adType instead of sniffing for field presence.

OR