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

# Create Click-to-WhatsApp 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`. 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.

## 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` (mutually exclusive). - Multi-creative: a non-empty `creatives[]` array. Top-level `headline` / `body` / `imageUrl` / `video` must NOT be set on this shape. The route enforces this at the Zod boundary; OpenAPI's `required` cannot express the OR cleanly.
  - `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.
  - `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 `video` is not supplied.
  - `video` object — Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if `imageUrl` is not supplied.
    - `url` string, uri, required
    - `thumbnailUrl` string, uri, required — Required by Meta for every video creative. Used as the ad thumbnail.
  - `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`). Each entry must supply its own headline, body, and exactly one of `imageUrl` / `video`.
    - `headline` string, required
    - `body` string, required — Primary text shown above the image / video.
    - `imageUrl` string, uri — Image asset. Mutually exclusive with this entry's `video`. Required if `video` is not supplied.
    - `video` object — Video creative. Mutually exclusive with this entry's `imageUrl`. Required if `imageUrl` is not supplied.
      - `url` string, uri, required
      - `thumbnailUrl` string, uri, required — Required by Meta for every video creative. Used as the ad thumbnail.
  - `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` and `audienceId` 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; Meta infers from the ad account when omitted.
  - `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
  - `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.
  - `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.

## 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` — 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.

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/51932b099b2f/schema)