Create Click-to-WhatsApp ad

Creates a Click-to-WhatsApp (CTWA) ad on Meta. When tapped, the ad opens a WhatsApp conversation with the business attached to the supplied Facebook Page, and the full hierarchy (campaign, ad set, creative, ad) 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. 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

Creates a Click-to-WhatsApp (CTWA) ad on Meta. When tapped, the ad opens a WhatsApp conversation with the business attached to the supplied Facebook Page, and the full hierarchy (campaign, ad set, creative, ad) 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. 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.

Request body

Content-Type: application/json

• accountId (string) required — Facebook or Instagram SocialAccount ID.
• adAccountId (string) required — Meta ad account ID, e.g. act_123456789.
• name (string) required — Ad display name. Used to derive campaign / ad set names.
• headline (string) required
• body (string) required — Primary text shown above the image / video.
• imageUrl (string) — Image asset for image creatives. Mutually exclusive with video. Required if video is not supplied.
• video (object) — Video creative. Mutually exclusive with imageUrl. Required if imageUrl is not supplied.
• budgetAmount (number) required — Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0.
• budgetType (string) required (enum: daily, lifetime)
• currency (string) — ISO 4217 currency code matching the ad account's currency (e.g. USD). Optional; Meta infers from the ad account when omitted.
• endDate (string) — ISO 8601 datetime. Required when budgetType is lifetime.
• countries (array) — ISO 3166-1 alpha-2 country codes. Defaults to ["US"].
• ageMin (integer)
• ageMax (integer)
• interests (array)
• audienceId (string) — Custom audience ID to target.
• advantageAudience (integer) (enum: 0, 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 (Met...
• objective (string) (enum: OUTCOME_ENGAGEMENT, OUTCOME_SALES, OUTCOME_LEADS) — Defaults to OUTCOME_ENGAGEMENT (the broadly-supported CTWA objective). OUTCOME_SALES and OUTCOME_LEADS require additional account configuration (Dataset linked to the WABA for sales) and may be...
• dsaBeneficiary (string) — Name of the legal entity benefiting from the ad. Required by Meta when targeting EU users (DSA Article 26). Not enforced at schema level; enforced server-side when targeting intersects EU member state...
• dsaPayor (string) — Name of the legal entity paying for the ad. Required by Meta when targeting EU users (DSA Article 26). Note Meta API spelling: dsa_payor (not dsa_payer).

Responses

201 — CTWA ad created and submitted to Meta for review.

• ad (object) — The persisted Ad document.
• message (string)

400 — Invalid body.

401

403 — Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

404 — SocialAccount not found.

422 — Page is not connected to a verified WhatsApp number.

502 — Meta rejected the request (e.g. WABA business verification missing). Inspect platformError for the upstream Meta payload.