Create click-to-message ad (WhatsApp / Messenger / Instagram Direct)
Creates a click-to-message ad; destination selects where the tapped ad opens a
conversation: WhatsApp, the Page's Messenger inbox or the linked Instagram account's Direct inbox.
The ad set is created with the matching destination_type and
CONVERSATIONS optimization; the campaign objective defaults to OUTCOME_ENGAGEMENT.
Supports single-creative and multi-creative shapes. Supersedes POST /v1/ads/ctwa
(deprecated, equivalent to destination: whatsapp).
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. 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).
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.
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.
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. 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 < valueLegal 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.
length <= 100Legal 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.
length <= 100Where the conversation opens when the ad is tapped.
"whatsapp" | "messenger" | "instagram_direct"Response Body
application/json
import Zernio from '@zernio/node';const zernio = new Zernio({ apiKey: process.env.ZERNIO_API_KEY });const { data } = await zernio.messagingads.createMessagingAd({ body: { accountId: 'account_abc123', adAccountId: 'adaccount_abc123', name: 'Example', budgetAmount: 0, budgetType: 'daily', destination: 'whatsapp', },});console.log(data);{
"error": "Unauthorized"
}Create Click-to-Call ad POST
Same shape and flow as POST /v1/ads/ctwa, but the CTA is CALL_NOW dialing `phoneNumber` via a tel: link. The ad set is destination_type PHONE_CALL optimizing QUALITY_CALL and the campaign objective defaults to OUTCOME_LEADS. Supports the same single-creative and multi-creative shapes as CTWA.
Create a Reach & Frequency prediction POST
Creates an R&F prediction — a QUOTE, nothing is bought and no ad entities are created. Provide a date range plus exactly one of `budgetAmount` (Meta predicts reach) or `reach` (Meta predicts the budget). The response carries the estimate and its allowed bounds (min/max budget and reach). Predictions expire on their own; to buy, reserve one via POST /v1/ads/rf-predictions/{predictionId}/reserve and pass the RESERVED id to POST /v1/ads/create with `buyingType: "RESERVED"`. Reservation campaigns reject automatic placements, so omitted `placements` default to Facebook feed (+ Instagram stream when a linked IG professional account resolves); Instagram placements require that IG account.