Create Click-to-WhatsApp ad(s)
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 ofimageUrl/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.
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.
API key authentication - use your Zernio API key as a Bearer token
In: header
Facebook or Instagram SocialAccount ID.
1 <= lengthMeta ad account ID, e.g. act_123456789.
1 <= lengthAd 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.
1 <= lengthSingle-creative shape only. Mutually exclusive with
creatives[].
1 <= length <= 255Primary text shown above the image / video. Single-creative
shape only. Mutually exclusive with creatives[].
1 <= lengthImage asset for single-creative shape. Mutually exclusive
with video and with creatives[]. Required on the
single-creative shape if video is not supplied.
uriVideo creative for single-creative shape. Mutually
exclusive with imageUrl and with creatives[]. Required
on the single-creative shape if imageUrl is not supplied.
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.
1 <= itemsBudget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0.
0 <= value"daily" | "lifetime"ISO 4217 currency code matching the ad account's currency
(e.g. USD). Optional; Meta infers from the ad account
when omitted.
3 <= length <= 3ISO 8601 datetime. Required when budgetType is lifetime.
date-timeISO 3166-1 alpha-2 country codes. Defaults to ["US"] only
when no other geo (cities, regions, zips, metros,
customLocations) is supplied.
City-level geo targeting for local CTWA campaigns (e.g.
25km radius around Milan). Each entry maps to Meta's
TargetingGeoLocationCity. key is Meta's city ID
(lookupable via GET /v1/ads/targeting/search). radius
and distance_unit are coupled: set both or neither.
Region / state-level geo targeting. key is Meta's region
ID (lookupable via GET /v1/ads/targeting/search?type=region).
ZIP / postal-code geo targeting. key is the platform's
postal id resolved via /v1/ads/targeting/search.
DMA / metro-area geo targeting. key is Meta's metro id
(e.g. DMA:807).
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.
13 <= value <= 6513 <= value <= 65Custom audience ID to target.
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).
0 | 1Defaults 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 rejected by Meta if missing.
"OUTCOME_ENGAGEMENT" | "OUTCOME_SALES" | "OUTCOME_LEADS"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.
"LOWEST_COST_WITHOUT_CAP" | "LOWEST_COST_WITH_BID_CAP" | "COST_CAP" | "LOWEST_COST_WITH_MIN_ROAS"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.
0 <= valueDecimal 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.
0 <= valueName 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 states.
length <= 100Name 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).
length <= 100Response Body
application/json
application/json
import Zernio from '@zernio/node';const zernio = new Zernio({ apiKey: process.env.ZERNIO_API_KEY });const { data } = await zernio.ads.createCtwaAd({ body: { accountId: 'account_abc123', adAccountId: 'adaccount_abc123', name: 'Example', budgetAmount: 0, budgetType: 'daily', },});console.log(data);{
"adType": "single",
"ad": {},
"message": "string"
}{
"error": "Unauthorized"
}Create a conversion destination (LinkedIn, Google Ads) POST
Create a new conversion destination on the platform. Supported for LinkedIn (conversion rule) and Google Ads (conversion action). Meta manages destinations in its own UI and returns 405. **LinkedIn:** creation is NOT idempotent. A retry creates a second destination. Deduplicate before retrying. **Google Ads:** calling with a name that already exists reuses the existing conversion action transparently (the response is identical to a fresh create). Calling with the same name but a different category returns a typed `IDEMPOTENCY_CONFLICT` (409) rather than silently returning the mismatched action. **LinkedIn:** the rule is created with `conversionMethod=CONVERSIONS_API` and (by default) auto-associated with all of the ad account's campaigns via `autoAssociationType=ALL_CAMPAIGNS`. Pass `autoAssociationType: NONE` to opt out and manage associations explicitly via the associations endpoints below. 365-day attribution windows are only valid for `SUBMIT_APPLICATION`, `PURCHASE`, `ADD_TO_CART`, `QUALIFIED_LEAD`, and `LEAD` rule types; the API rejects other combinations locally. **Google Ads:** the conversion action is created with `type=UPLOAD_CLICKS` (required for API-uploaded offline conversions, immutable after creation). The `type` field carries the Google `ConversionActionCategory` enum value, e.g. `PURCHASE`, `SUBSCRIBE_PAID`, `SIGNUP`, `IMPORTED_LEAD`, `BOOK_APPOINTMENT`. Unified standard event names (e.g. `Purchase`, `Subscribe`, `CompleteRegistration`, `Lead`, `Schedule`) are resolved to their Google category equivalents automatically. The action defaults to secondary (non-primary) to avoid immediately steering Smart Bidding; pass `primaryForGoal: true` to opt in.
Create a Lead Gen (Instant) form POST
Creates a Lead Gen form on the connected Facebook Page (POST /{page-id}/leadgen_forms). NOT idempotent — a retry creates a second form. Prefilled question types (EMAIL, PHONE, FULL_NAME, …) must omit label/key; CUSTOM questions require both. Requires the Ads add-on.