Sign in
Messaging Ads

Create CTWA 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, or a platformPostId / objectStoryId reference. Creates 1 campaign + 1 ad set + 1 ad.

  • Multi-creative: supply a creatives[] array with N entries (each carrying fresh media and copy or an existing post reference). 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. Existing posts and reels are supported through platformPostId (alias existingPostId) or objectStoryId, either per creative or at the top level. Omit fresh media and copy for that creative. Optional whatsappPhoneNumber selects a number already paired with the Page (WhatsApp destination only).

Idempotency: this endpoint is not idempotent at the platform level (a blind retry creates a second campaign/ad set/ad). Send an Idempotency-Key header to make retries safe: the first request with a given key creates the ad and we store the response; a retry with the same key replays that exact response (with Idempotent-Replayed: true) instead of creating duplicates. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). Keys are scoped to your credential and expire after 24h.

post/v1/ads/ctwa

Headers

Idempotency-Keystring

Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409.

Request body

creativeFeaturesMetaCreativeFeatures

Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT. auto_promotion_tag is an Advantage+ enhancement, not the Ads Manager Promotion setting. The deprecated standard_enhancements bundle is rejected by Meta.

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.

campaignNamestring

Exact name for the campaign this request provisions. Omitted keeps <name> - Campaign. Ignored with adSetId (the ad set already has a campaign).

adSetNamestring

Exact name for the ad set this request provisions. Omitted keeps <name> - Ad Set. Ignored with adSetId.

platformPostIdstring

Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Facebook IDs become object_story_id; Instagram IDs become source_instagram_media_id using the connected Instagram identity. Mutually exclusive with objectStoryId and fresh creative fields.

existingPostIdstring

Alias of platformPostId, kept for existing callers. Sending both with different values is a 400.

objectStoryIdstring

Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields.

pageIdstring

Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages. Same semantics as pageId on POST /v1/ads/create.

whatsappPhoneNumberstring

WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. Sent to the creative CTA and, when creating a new ad set, its promoted_object. Attach requests do not change the existing ad set. Stored as creative.whatsappPhoneNumber on every created ad.

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 neither video nor an existing post reference is 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, audienceId and campaignStatus 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: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta (most currencies are cents; zero-decimal currencies like JPY/KRW are sent as-is).

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.

countryGroupsstring[]

Meta only. Continents and trade blocs (geo_locations.country_groups), for targeting a whole region without listing its countries. Combines with countries rather than replacing it, and is also accepted under excludedLocations. Discoverable via GET /v1/ads/targeting/search?dimension=geo&geoType=country_group.

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.

status'ACTIVE' | 'PAUSED'

Ad-level status. Defaults to ACTIVE. PAUSED skips activating the newly created ad(s) after Meta accepts them.

campaignStatus'ACTIVE' | 'PAUSED'

Campaign-level status, same semantics as POST /v1/ads/create. Defaults to ACTIVE. PAUSED holds activation at the campaign so it never spends before the advertiser reviews it, while the ad set and ad still switch on (one resume call brings the whole hierarchy live). Only meaningful when a new campaign is being created; rejected with a 400 alongside adSetId (the attach shape reuses an existing campaign).

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.

regionalRegulatedCategoriesstring[]

Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. BRAZIL_REGULATION, SINGAPORE_UNIVERSAL, TAIWAN_UNIVERSAL, THAILAND_UNIVERSAL, AUSTRALIA_FINSERV, INDIA_FINSERV, TAIWAN_FINSERV). Forwarded to the ad set.

regionalRegulationIdentitiesobject

Meta only. Beneficiary/payer entity IDs required alongside regionalRegulatedCategories. Values are numeric IDs from the advertiser's Meta verification/authorization setup. Keys depend on the declared category: BRAZIL_REGULATION and THAILAND_UNIVERSAL use universal_beneficiary / universal_payer; SINGAPORE_UNIVERSAL uses singapore_universal_beneficiary / singapore_universal_payer; TAIWAN_UNIVERSAL uses taiwan_universal_beneficiary / taiwan_universal_payer; TAIWAN_FINSERV uses taiwan_finserv_beneficiary / taiwan_finserv_payer; AUSTRALIA_FINSERV uses australia_finserv_beneficiary / australia_finserv_payer; INDIA_FINSERV uses india_finserv_beneficiary / india_finserv_payer. Both beneficiary and payer must be included. If omitted and the advertiser has set defaults in Meta Ads Manager advertising settings, Meta auto-fills them.

Example request

{
  "creativeFeatures": {
    "auto_promotion_tag": "OPT_IN"
  },
  "creatives": [
    {
      "creativeFeatures": {
        "auto_promotion_tag": "OPT_IN"
      }
    }
  ]
}

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

Changes

Changed in 15 of the 56 revisions of this API.52

  • e0122970214f1See the full diff
    • ○

      added the new optional header request parameter Idempotency-Key

      new-optional-request-parameter

  • 2c04683ce6948See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • dd3865482f9f4See the full diff
    • ○

      added the new optional request property //

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      request property // deprecated

      request-property-deprecated

    • ○

      request property deprecated

      request-property-deprecated

  • 106013ac73b83See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

  • eded32b628232See the full diff
    • ○

      added the new optional request property /

      new-optional-request-property

    • ○

      the request property / became optional

      request-property-became-optional

  • 3e6ddf2a99ea2See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • 0dba7d004d754See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • a23eb241746a1See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

  • e70ed06e71502See the full diff
    • ○

      added the media type application/json for the response with the status

      response-media-type-added

    • ○

      added the non-success response with the status

      response-non-success-status-added

  • 222e3a38a38210See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property //

      new-optional-request-property

    • ○

      added the new optional request property //

      new-optional-request-property

    • ○

      added the new optional request property //

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      the request property // became optional

      request-property-became-optional

    • ○

      the request property // became optional

      request-property-became-optional