Zernio
Zernio
API Reference

Messaging & Call Ads

Create Click-to-Call adPOSTCreate click-to-message ad (WhatsApp / Messenger / Instagram Direct)POST
Dashboard
llms.txtOpenAPI
OverviewPlatformsAPI ReferenceResources
Messaging & Call Ads

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

PlatformsMeta
POST
/v1/ads/messaging

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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.

Response Body

application/json

Empty
Was this page helpful?

Create Click-to-Call ad

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

Creates an R&F prediction. This is 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. Top-level `placements` wins; when it is omitted, `targeting.placements` is used; when neither is set, placements default to Facebook feed (+ Instagram stream when a linked IG professional account resolves). Instagram placements require that IG account.

accountId*string

Facebook or Instagram SocialAccount ID.

Length1 <= length
adAccountId*string

Meta ad account ID, e.g. act_123456789.

Length1 <= length
name*string

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.

Length1 <= length
headline?string

Single-creative shape only. Mutually exclusive with creatives[].

Length1 <= length <= 255
body?string

Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with creatives[].

Length1 <= length
imageUrl?string

Image asset for single-creative shape. Mutually exclusive with video and with creatives[]. Required on the single-creative shape if video is not supplied.

Formaturi
video?

Video creative for single-creative shape. Mutually exclusive with imageUrl and with creatives[]. Required on the single-creative shape if imageUrl is not supplied.

welcomeMessage?

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.

creatives?array<>

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 must supply its own headline, body, and exactly one of imageUrl / video.

Items1 <= items
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.

Range0 < value
budgetType?string

Required unless adSetId is set.

Value in

  • "daily"
  • "lifetime"
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).

Length3 <= length <= 3
endDate?string

ISO 8601 datetime. Required when budgetType is lifetime.

Formatdate-time
countries?array<>

ISO 3166-1 alpha-2 country codes. Defaults to ["US"] only when no other geo (cities, regions, zips, metros, customLocations) is supplied.

cities?array<>

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

regions?array<>

Region / state-level geo targeting. key is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region).

zips?array<>

ZIP / postal-code geo targeting. key is the platform's postal id resolved via /v1/ads/targeting/search.

metros?array<>

DMA / metro-area geo targeting. key is Meta's metro id (e.g. DMA:807).

customLocations?array<>

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.

ageMin?integer
Range13 <= value <= 65
ageMax?integer
Range13 <= value <= 65
interests?array<>
audienceId?string

Custom audience ID to target.

placements?

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.

advantageAudience?integer

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

Value in

  • 0
  • 1
objective?string

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.

Value in

  • "OUTCOME_ENGAGEMENT"
  • "OUTCOME_SALES"
  • "OUTCOME_LEADS"
status?string

Ad-level status. Defaults to ACTIVE. PAUSED skips activating the newly created ad(s) after Meta accepts them.

Value in

  • "ACTIVE"
  • "PAUSED"
campaignStatus?string

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

Value in

  • "ACTIVE"
  • "PAUSED"
bidStrategy?string

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.

Value in

  • "LOWEST_COST_WITHOUT_CAP"
  • "LOWEST_COST_WITH_BID_CAP"
  • "COST_CAP"
  • "LOWEST_COST_WITH_MIN_ROAS"
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.

Range0 < value
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.

Range0 < value
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.

Lengthlength <= 100
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.

Lengthlength <= 100
regionalRegulatedCategories?array<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?

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.

destination*string

Where the conversation opens when the ad is tapped.

Value in

  • "whatsapp"
  • "messenger"
  • "instagram_direct"