---
title: "Create CTWA ad (deprecated)"
method: POST
path: "/v1/ads/ctwa"
tags: ["Messaging Ads"]
deprecated: true
---

# Create CTWA ad (deprecated)

`POST /v1/ads/ctwa`

> **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).

## Request body

- CtwaAdRequestBody — In addition to the `required` list, the request must use EXACTLY ONE of the two shapes: - Single-creative: `headline`, `body`, and one of `imageUrl` / `video`, OR `platformPostId` / `objectStoryId` to reuse an organic post. - Multi-creative: a non-empty `creatives[]` array. Top-level creative fields must NOT be set on this shape. Existing post references work on messaging and CTWA only (not call ads). They cannot be combined with each other or with headline, body, imageUrl, video, or welcomeMessage. No media is uploaded and the organic post is retained. Fresh creatives still require headline, body, and image or video. The route enforces this at the Zod boundary; OpenAPI's `required` cannot express the OR cleanly.
  - `creativeFeatures` MetaCreativeFeatures — 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.
  - `tracking` AdTracking — Meta only. Attaches pixel measurement to the ad regardless of the optimization goal (the "Website events" tracking row in Ads Manager). `pixelId` becomes the ad's `tracking_specs` (offsite_conversion + fb_pixel); `urlTags` is stored on the new creative as `url_tags` and retained on the ad for compatibility. Applied on the legacy single-creative shape, every ad of the multi-creative shape, and the attach shape. NOTE: tracking lives on the AD object and is not inherited from the ad set, so pass it on EVERY attach call that should carry the pixel.
    - `pixelId` string — Meta Pixel ID to attach for offsite-conversion measurement.
    - `urlTags` object[] — Click-URL params stored on the creative as `url_tags` and returned by GET /v1/ads/{adId}/tracking-tags. App-promotion linkUrl stays byte-identical to promotedObject.objectStoreUrl. Meta dynamic macros ({{ad.id}}, {{campaign.id}}, {{placement}}, ...) are sent through unescaped so Meta expands them; every other character is percent-encoded.
      - `key` string, required
      - `value` string, required
  - `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. 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.
  - `campaignName` string — Exact name for the campaign this request provisions. Omitted keeps `<name> - Campaign`. Ignored with `adSetId` (the ad set already has a campaign).
  - `adSetName` string — Exact name for the ad set this request provisions. Omitted keeps `<name> - Ad Set`. Ignored with `adSetId`.
  - `platformPostId` string — 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.
  - `existingPostId` string — Alias of platformPostId, kept for existing callers. Sending both with different values is a 400.
  - `objectStoryId` string — 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.
  - `pageId` string — 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.
  - `whatsappPhoneNumber` string — 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.
  - `headline` string — Single-creative shape only. Mutually exclusive with `creatives[]`.
  - `body` string — Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`.
  - `imageUrl` string, 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.
  - `video` object — Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if neither `imageUrl` nor an existing post reference is supplied.
    - `url` string, uri — Public URL of the video to upload. Provide either `url` or `id`.
    - `id` string — Reuse a video already uploaded to this ad account (list them with GET /v1/ads/videos) instead of re-uploading. Wins over `url`. Provide either `url` or `id`.
    - `thumbnailUrl` string, uri — OPTIONAL: when omitted, the poster is auto-generated from Meta's own preferred video thumbnail. When Meta produces no candidate the request fails with a 502 platform_error (reason: video_thumbnail_unavailable). Retry, or supply this field to control the poster frame exactly.
  - `welcomeMessage` object — Custom chat welcome message (Meta's `page_welcome_message`, "Mensaje de bienvenida" / "Mensaje predefinido" in Ads Manager). Single-creative shape only; for `creatives[]` set it per entry.
    - `text` string, required — Greeting shown when the chat opens. Replaces Meta's default ("Hi! Can we help you?").
    - `prefillText` string — Message put into the user's text input, ready to send. Replaces Meta's default ("Hi! I want more info."). Lets one ad steer the opening message toward what it promotes (e.g. a specific product). Exactly one of prefillText or quickReplies.
    - `quickReplies` object[] — Tappable chips under the greeting instead of a prefilled message. Exactly one of prefillText or quickReplies. Put your own campaign or ad key in each payload: the tap arrives on the messages webhook with that payload even where Meta delivers no ad referral (Pages owned by an EU business under the Europe/Japan Messenger restrictions).
      - `title` string, required — Chip label the person taps.
      - `payload` string, required — Opaque string you choose; delivered on the message.received webhook as interactiveMetadata.quickReplyPayload when the chip is tapped.
  - `creatives` object[] — Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Mutually exclusive with the top-level single-creative fields (`headline` / `body` / `imageUrl` / `video`): setting both is a 400, unlike `POST /v1/ads/create` where the top-level fields are silently ignored in multi-creative mode. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId reference. Fresh and existing creatives can be mixed.
    - `platformPostId` string — 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.
    - `existingPostId` string — Alias of platformPostId, kept for existing callers. Sending both with different values is a 400.
    - `objectStoryId` string — 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.
    - `creativeFeatures` MetaCreativeFeatures — 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.
    - `headline` string
    - `body` string — Primary text shown above the image / video.
    - `imageUrl` string, uri — Image asset. Mutually exclusive with this entry's `video`. Required if neither `video` nor an existing post reference is supplied.
    - `video` object — Video creative. Mutually exclusive with this entry's `imageUrl`. Required if neither `imageUrl` nor an existing post reference is supplied.
      - `url` string, uri — Public URL of the video to upload. Provide either `url` or `id`.
      - `id` string — Reuse a video already uploaded to this ad account (list them with GET /v1/ads/videos) instead of re-uploading. Wins over `url`. Provide either `url` or `id`.
      - `thumbnailUrl` string, uri — OPTIONAL: when omitted, the poster is auto-generated from Meta's own preferred video thumbnail. When Meta produces no candidate the request fails with a 502 platform_error (reason: video_thumbnail_unavailable).
    - `welcomeMessage` object — Custom chat welcome message for this entry. See the top-level `welcomeMessage` for the single-creative shape.
      - `text` string, required — Greeting shown when the chat opens. Replaces Meta's default.
      - `prefillText` string, required — Message put into the user's text input, ready to send. Replaces Meta's default.
  - `adSetId` string — 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.
  - `budgetAmount` number — 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.
  - `currency` string — 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).
  - `endDate` string, date-time — ISO 8601 datetime. Required when `budgetType` is `lifetime`.
  - `countries` string[] — ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied.
  - `cities` object[] — City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity. `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither. Meta enforces a minimum city radius (~17 km / 10 mi); smaller values resolve to a 0-size audience and the ad fails at launch. For a tighter catchment use customLocations (lat/lng).
    - `key` string, required
    - `radius` number
    - `distance_unit` 'mile' | 'kilometer'
  - `regions` object[] — Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region).
    - `key` string, required
  - `zips` object[] — ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /v1/ads/targeting/search.
    - `key` string, required
    - `name` string
  - `metros` object[] — DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`).
    - `key` string, required
    - `name` string
  - `countryGroups` string[] — 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`.
  - `customLocations` object[] — Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required.
    - `latitude` number, required
    - `longitude` number, required
    - `radius` number, required
    - `distanceUnit` 'mile' | 'kilometer', required
    - `name` string
    - `address` string
  - `ageMin` integer
  - `ageMax` integer
  - `interests` object[]
    - `id` string, required
    - `name` string
  - `audienceId` string — Custom audience ID to target.
  - `placements` object — Manual ad placements on the shared ad set. Omit for automatic placements. When set, restricts delivery to the chosen surfaces, mapped onto the ad set's `targeting.{publisher_platforms, facebook_positions, instagram_positions, messenger_positions, audience_network_positions, threads_positions, whatsapp_positions, device_platforms}`. Enum membership is validated here; Meta additionally enforces co-selection rules and restricts which placements are eligible for click-to-WhatsApp ads, returning an actionable error which we surface.
    - `publisherPlatforms` string[] — Top-level platforms to deliver on. A position field below is only honoured when its parent platform is included here.
    - `facebookPositions` string[]
    - `instagramPositions` string[]
    - `messengerPositions` string[]
    - `audienceNetworkPositions` string[]
    - `threadsPositions` string[]
    - `whatsappPositions` string[]
    - `devicePlatforms` string[] — Restrict by device. Omit to deliver on both mobile and desktop.
  - `advantageAudience` 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 (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.
  - `bidAmount` number — 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.
  - `roasAverageFloor` number — 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.
  - `dsaBeneficiary` string — 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.
  - `dsaPayor` string — 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.
  - `regionalRegulatedCategories` string[] — 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.
  - `regionalRegulationIdentities` object — 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.

## Response `201`

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.

- union
  - CtwaSingleResponse — Response returned by `POST /v1/ads/ctwa` when the request used the single-creative shape (top-level headline / body / imageUrl|video). `adType` is the union discriminator.
    - `adType` 'single', required
    - `ad` object, required — The persisted Ad document.
    - `message` string, required
  - CtwaMultiResponse — Response returned by `POST /v1/ads/ctwa` when the request used the multi-creative shape (`creatives[]`). N persisted Ad documents share the returned `platformCampaignId` and `platformAdSetId`. `adType` is the union discriminator.
    - `adType` 'multi', required
    - `ads` object[], required — The persisted Ad documents (one per creative), all sharing the same `platformCampaignId` and `platformAdSetId`.
    - `platformCampaignId` string, required
    - `platformAdSetId` string, required
    - `message` string, required

## Other responses

- `400` — Invalid body.
- `401` — Unauthorized
- `403` — Forbidden. Also returned with code `ads_allowance_exceeded` when the team has no payment method on file and has reached the 500 free live ads: add a card to resume.
- `404` — The account or requested resource was not found or is not accessible. An account ID may have been disconnected and removed. Read GET /v1/accounts for current account IDs.
- `409` — The account exists but is inactive or needs reconnection. Reconnect it, then read GET /v1/accounts for its current account ID before retrying. Code: ads_connection_required.
- `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.

## Changes

- **2026-09-23** `dd3865482f9f` — 4 info
  - added the new optional request property `creatives/items/platformPostId`
  - added the new optional request property `platformPostId`
  - request property `creatives/items/existingPostId` deprecated
  - request property `existingPostId` deprecated
- **2026-09-22** `106013ac73b8` — 3 info
  - added the new optional request property `adSetName`
  - added the new optional request property `campaignName`
  - added the new optional request property `pageId`
- **2026-09-18** `eded32b62823` — 2 info
  - added the new optional request property `welcomeMessage/quickReplies`
  - the request property `welcomeMessage/prefillText` became optional
- **2026-09-16** `3e6ddf2a99ea` — 2 info
  - added the optional property `details/budgetScope` to the response with the `404` status
  - added the optional property `details/budgetScope` to the response with the `409` status
- **2026-09-15** `0dba7d004d75` — 4 info
  - added the optional property `details/quotaExhausted` to the response with the `404` status
  - added the optional property `details/quotaExhausted` to the response with the `409` status
  - added the optional property `details/quotaScope` to the response with the `404` status
  - added the optional property `details/quotaScope` to the response with the `409` status

[Full history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/ads/ctwa/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/dd3865482f9f?raw)