Zernio
APIFor you
Zernio
APIFor you
API Reference

Messaging & Call Ads

Create Click-to-Call adPOSTCreate messaging adPOST
Dashboard
OverviewPlatformsAPI ReferenceResources
Messaging & Call Ads

Create messaging ad

Creates a Meta ad that opens a chat with you on WhatsApp, Messenger or Instagram Direct when someone taps it.

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. destinations puts two or three of them on one ad set and lets Meta pick the app per viewer. 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). 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). accountId is a Facebook, Instagram or Meta ads (business login) connection; pageId picks the Page when that connection was granted several.

Required fields per shape (a missing one is a 400 naming it in param):

  • Always accountId, adAccountId, name, and exactly one of destination / destinations.
  • budgetAmount and budgetType unless adSetId or existingCampaignId is set, plus endDate for a lifetime budget.
  • Single image or video: headline, body, and exactly one of imageUrl / video. With placementAssets, headline and body only (the media comes from placementAssets).
  • carouselCards: body and the 2-10 cards; headline is optional, imageUrl / video / top-level description are a 400.
  • Existing post (platformPostId or objectStoryId): no copy or media fields.
  • creatives[]: the same rules per entry, with no top-level creative fields.
  • welcomeMessage, when sent: text plus exactly one of prefillText / quickReplies.

WhatsApp number prerequisite. For the WhatsApp destination, link the WhatsApp number to the Facebook Page used for the ad before creating it: Meta checks the pairing at creation. Link it from the WhatsApp Business app (Settings > Business tools > Facebook & Instagram) or from the Page settings (Linked accounts > WhatsApp). Linking does not affect the number's WhatsApp connection in Zernio (Cloud API or coexistence), so no reconnect or re-sync is needed. If Meta creates a new ad set without the requested whatsappPhoneNumber, the 201 response carries a warnings entry. This can happen even when the number is linked (Meta can drop a Page's second linked number).

Idempotency: this endpoint is not idempotent at the platform level (a blind retry creates a second campaign/ad set/ad). Send an Idempotency-Key header to make retries safe: the first request with a given key creates the ad and we store the response; a retry with the same key replays that exact response (with Idempotent-Replayed: true) instead of creating duplicates. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). If the first request is cut off mid-create (for example by a function timeout), its key can stay in progress and keep returning 409 until it expires; use a new key to retry sooner, after checking whether the ad was created. Keys are scoped to your credential and expire after 24h.

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

Header Parameters

Idempotency-Key?string

Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409. A request cut off mid-handler (for example by a function timeout) can leave its key in progress, answering 409 until the key expires after 24 hours.

Lengthlength <= 255

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, OR platformPostId / objectStoryId to reuse an organic post. On POST /v1/ads/messaging, placementAssets can replace imageUrl / video.
  • Carousel (messaging and CTWA): body and carouselCards (2-10 image cards) instead of imageUrl / video, top level or per creatives[] entry.
  • 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 or video. welcomeMessage works on them (it lives on the ad, not the post). 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.

Campaign, ad set and targeting fields match POST /v1/ads/create on Meta and run through the same builders: the full targeting set (including rawTargeting, languages, gender, exclusions and savedTargetingId), budgetLevel (campaign budget), startDate / endDate in the ad account timezone, and existingCampaignId to add a new ad set to a campaign you already have.

Response Body

application/json

application/json

application/json

application/json

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',    destination: 'whatsapp',    destinations: [      'whatsapp',    ],    placementAssets: {      defaultImageUrl: 'https://example.com/feed-4x5.jpg',      rules: [        {          imageUrl: 'https://example.com/feed-4x5.jpg',          headline: 'Build with Zernio',          body: 'Schedule social posts from your app.',          description: 'One API for your social content.',          placements: {            publisherPlatforms: [              'facebook',            ],            facebookPositions: [              'feed',            ],          },        },        {          imageUrl: 'https://example.com/story-9x16.jpg',          headline: 'Your next story',          body: 'Bring your social workflow to Zernio.',          placements: {            publisherPlatforms: [              'facebook',            ],            facebookPositions: [              'story',              'facebook_reels',            ],          },        },      ],    },  },});console.log(data);
{  "validateOnly": true,  "results": [    {      "node": "campaign",      "status": "validated",      "reason": "string"    }  ],  "message": "string"}
Was this page helpful?

Create Click-to-Call ad

Creates a Meta ad with a Call Now button that dials your phone number, optimized for quality calls. 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. **Idempotency:** this endpoint is not idempotent at the platform level (a blind retry creates a second campaign/ad set/ad). Send an `Idempotency-Key` header to make retries safe: the first request with a given key creates the ad and we store the response; a retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). If the first request is cut off mid-create (for example by a function timeout), its key can stay in progress and keep returning 409 until it expires; use a new key to retry sooner, after checking whether the ad was created. Keys are scoped to your credential and expire after 24h.

Create reach-frequency prediction

Quotes the reach or budget for a Meta reach and frequency campaign over a date range, without buying anything. 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.

creativeFeatures?

Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object.

tracking?

Meta, plus urlTags on ChatGPT (OpenAI) and pixelId on Reddit. Meta: 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. ChatGPT (OpenAI): urlTags becomes the ad's landing_page_configuration.query_string_template, which OpenAI appends to linkUrl on click. Reddit: pixelId picks the pixel of the new ad group, like promotedObject.pixelId (which wins when both are sent).

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
campaignName?string

Exact name for the campaign this request provisions. Omitted keeps <name> - Campaign. Ignored with adSetId (the ad set already has a campaign).

Lengthlength <= 255
adSetName?string

Exact name for the ad set this request provisions. Omitted keeps <name> - Ad Set. Ignored with adSetId.

Lengthlength <= 255
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 run as the media owner (resolved from the media on a Meta ads business-login connection, so no Instagram connection is needed). Mutually exclusive with objectStoryId and fresh creative fields.

Length1 <= length
existingPostId?string
Deprecated

Alias of platformPostId, kept for existing callers. Sending both with different values is a 400.

Length1 <= length
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.

Match^\d+_\d+$
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. Meta can accept the number yet create the ad set without it; the response then carries a warnings entry. Attach requests do not change the existing ad set. Stored as creative.whatsappPhoneNumber on every created ad.

Match^\+[1-9]\d{6,14}$
headline?string

Single-creative shape only. Mutually exclusive with creatives[]. Required on a single image or video ad (including one built with placementAssets); not used by a carouselCards ad and not accepted with an existing post reference.

Length1 <= length <= 255
body?string

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

Length1 <= length
description?string

Link description, independent of headline and body (Meta's link_data.description, video_data.link_description on video, and the shared description of a placementAssets feed). Meta shows it mainly on Facebook Feed placements, under the headline, when there is room; Instagram, Stories, Reels and Messenger placements do not display it. Also accepted per entry in creatives[]. Not allowed with an existing post creative.

Length1 <= length <= 255
imageUrl?string

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.

Formaturi
video?

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.

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.

carouselCards?array<>

Messaging and CTWA only (a 400 on POST /v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the order given as link_data.child_attachments (by default Meta may reorder them for performance, since multi_share_optimized defaults to true; optimizeCardOrder: false keeps the order given); every card (and the carousel itself) carries the destination's messaging call to action (WHATSAPP_MESSAGE, MESSAGE_PAGE or INSTAGRAM_MESSAGE), so a tap on any card opens the conversation. Replaces imageUrl / video (sending either is a 400). body is required as the primary text; headline is optional and only names the creative (each card has its own headline); a top-level description is a 400 (set it per card). welcomeMessage, whatsappPhoneNumber and destinations apply as on a single-image ad. Also a 400 with placementAssets, platformPostId, existingPostId or objectStoryId. Single-creative shape; for creatives[] set it per entry.

Items2 <= items <= 10
optimizeCardOrder?boolean

Only with carouselCards (a 400 without them). Sets the creative's link_data.multi_share_optimized. false keeps the cards in the order given; Meta then takes at most 5 cards, so false with more than 5 carouselCards is a 400. true lets Meta pick and reorder the cards for performance (up to 10). Omitted, nothing is sent and Meta's default (true) applies. Single-creative shape; 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 supplies headline, body, and image/video, or a platformPostId or objectStoryId reference. Fresh and existing creatives can be mixed.

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, budgetLevel, startDate, endDate, objective, campaignStatus, adSetStatus, existingCampaignId, the special ad category fields and every targeting field except ageMin, ageMax, placements and advantageAudience are rejected with a 400 alongside it. Its destination_type must match the ad's destination.

existingCampaignId?string

Create the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. The campaign's objective must be OUTCOME_ENGAGEMENT, OUTCOME_SALES or OUTCOME_LEADS (400 otherwise). If the campaign has a campaign budget, omit budgetAmount and budgetType (400 if sent); otherwise they are required and land on the new ad set. objective, campaignName, campaignStatus, budgetLevel, specialAdCategories, specialAdCategoryCountry and adSetId are rejected alongside it. To add ads to an existing ad set instead, use adSetId.

Match^\d+$
budgetLevel?string

Where the budget lives. adset (default) puts it on the new ad set. campaign creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /v1/ads/create. Not allowed with adSetId or existingCampaignId.

Value in

  • "adset"
  • "campaign"
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 (the ad set owns it) or existingCampaignId names a campaign with a campaign budget.

Range0 < value
budgetType?string

Required unless adSetId is set or existingCampaignId names a campaign with a campaign budget. lifetime requires endDate.

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
startDate?string

When the ad set starts delivering. ISO 8601 date or date-time. A value with an offset (2027-01-15T10:00:00+01:00, ...Z) is used as is; one without an offset (2027-01-15T10:00:00) is read in the ad account's timezone, and a date-only value starts at 00:00 local. Defaults to now.

endDate?string

ISO 8601 date or date-time, read like startDate; a date-only value ends at 23:59:59 local. Required when budgetType is lifetime.

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

countryGroups?array<>

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

gender?string

Restrict the audience by gender (Meta genders). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in targeting.gender.

Value in

  • "all"
  • "male"
  • "female"
languages?array<string>

Audience languages (Meta locales). A bare ISO 639-1 code targets all regional variants ("en" = all English), a region-qualified code a specific one ("en_GB", "pt_BR"); unknown codes are rejected.

places?array<>

Meta place keys (from GET /v1/ads/targeting/search).

neighborhoods?array<>

Meta neighborhood keys (from GET /v1/ads/targeting/search).

excludedLocations?

Geo to exclude, same shape as POST /v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).

behaviors?array<>

Behavior ids from /v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across). TikTok: video/creator interaction categories, sent as the ad group's actions.

workPositions?array<>
workEmployers?array<>
workIndustries?array<>
incomeTier?string

Normalized household-income tier, same as POST /v1/ads/create. Incompatible with housing, employment and credit specialAdCategories.

Value in

  • "top_5"
  • "top_10"
  • "top_10_25"
  • "top_25_50"
userOs?array<string>

Meta user_os, e.g. ["iOS_ver_14.0_and_above"].

Items1 <= items
userDevice?array<string>

Meta user_device.

Items1 <= items
audienceInclude?array<string>

Custom or lookalike audience ids to include.

Items1 <= items
audienceExclude?array<string>

Custom or lookalike audience ids to exclude.

Items1 <= items
savedTargetingId?string

ID of a saved_targeting audience (POST /v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then targeting, then the flat fields.

targeting?

Nested targeting object, same contract as POST /v1/ads/create and boost. Flat fields win per key.

rawTargeting?

Meta targeting spec sent as the BASE layer of the ad set's targeting, exactly as POST /v1/ads/create does: use it for anything the flat fields cannot express, such as a layered flexible_spec (entries AND together, ids inside one entry OR). Flat fields you also send are layered on top and win per key. With rawTargeting present the US geo and advantage_audience: 0 defaults are not injected, so include targeting_automation in it (or send advantageAudience), as Meta requires it on create.

specialAdCategories?array<>

Meta special ad categories on the new campaign.

specialAdCategoryCountry?array<string>

Countries the special ad category applies to. Requires specialAdCategories.

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

Defaults to ACTIVE. PAUSED pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with adSetId, the new ads themselves.

Value in

  • "ACTIVE"
  • "PAUSED"
campaignStatus?string

Campaign-level status, same semantics as POST /v1/ads/create. Defaults to status. PAUSED holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live); ACTIVE with status: PAUSED switches the campaign on and pauses the new ad set instead. 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"
adSetStatus?string

Ad-set-level status, same semantics as POST /v1/ads/create. Sets the new ad set's switch alone and overrides status for it. A level status (campaignStatus, adSetStatus, adStatus) always wins for its level, and status: PAUSED adds a hold of its own only when none of them is PAUSED. Rejected with a 400 alongside adSetId (that ad set already exists).

Value in

  • "ACTIVE"
  • "PAUSED"
adStatus?AdActivationStatus

Ad-level status, same semantics as POST /v1/ads/create. Sets the new ads' switch and overrides status for them, also with adSetId. Send campaignStatus, adSetStatus and adStatus all PAUSED to create every object paused.

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. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV, TAIWAN_UNIVERSAL, THAILAND_UNIVERSAL). Forwarded to the ad set.

regionalRegulationIdentities?

Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Meta may require them on ad sets created through the API even when a default beneficiary and payer are set in Ads Manager advertising settings (seen on AUSTRALIA_FINSERV), so sending them explicitly is the reliable path. The value is the Verified identity ID (Meta Business Settings > Verified identities), not a Page or Business ID, and beneficiary and payer may be the same ID. Send each ID as a string of digits: Verified identity IDs can have 17 digits, more than a JSON number holds exactly, and a number that arrives rounded is rejected. Numbers up to 9007199254740991 are still accepted. The IDs reach Meta unchanged. Keys by category: AUSTRALIA_FINSERV uses australia_finserv_beneficiary / australia_finserv_payer; TAIWAN_FINSERV uses taiwan_finserv_beneficiary / taiwan_finserv_payer; INDIA_FINSERV uses india_finserv_beneficiary / india_finserv_payer; TAIWAN_UNIVERSAL uses taiwan_universal_beneficiary / taiwan_universal_payer; SINGAPORE_UNIVERSAL uses singapore_universal_beneficiary / singapore_universal_payer; AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, MALAYSIA_UNIVERSAL and THAILAND_UNIVERSAL use universal_beneficiary / universal_payer. When Meta rejects the ad set for a missing verified advertiser, the error carries param regionalRegulationIdentities, details.expectedIdentityKeys (the keys the declared categories expect), details.suggestedCategories (the markets Meta ties to that subcode) and Meta's metaCode, metaSubcode and fbtraceId. Ignored when adSetId adds the ad to an existing ad set.

destination?string

Where the conversation opens when the ad is tapped. Set this OR destinations, not both.

Value in

  • "whatsapp"
  • "messenger"
  • "instagram_direct"
destinations?array<>

Two or three messaging apps on ONE ad set, like Ads Manager's "all messaging apps": the ad set gets Meta's combined destination_type (e.g. MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP) and the creative one CTA per app, so Meta opens the app each viewer is likeliest to answer from. WhatsApp in the list still needs the Page paired with a WhatsApp Business number. With adSetId, the existing ad set must already use that combined destination_type. Set this OR destination, not both.

Items2 <= items <= 3
placementAssets?

A different image or video per placement on one messaging ad, e.g. a 4:5 image on Feed and a 9:16 image on Stories/Reels. Replaces top-level imageUrl / video (sending either alongside is a 400); headline and body stay required as the default copy. The CTA, welcomeMessage and whatsappPhoneNumber apply to every placement. Works on the single-creative shape and on attach (adSetId).

Single destination only: Meta cannot combine per-placement media with destinations (it drops the placement rules from a multi-destination creative, or refuses more than one call to action per placement rule with error 1885878), so that combination is a 400. Also a 400 with creatives[], platformPostId, existingPostId or objectStoryId, and on POST /v1/ads/call.

workflowId?string

A workflow in the ad account's profile. When someone clicks the ad, that workflow starts in the conversation the click opens (on the first message, a postback or a standalone referral carrying the ad id), ahead of keyword-matched workflows, if it is active on the receiving account. Stored on the ad. 404 when no such workflow exists in the profile.

Match^[a-fA-F0-9]{24}$
validateOnly?boolean

Dry-runs the ad on Meta with execution_options validate_only as ONE inline campaign + ad set + creative + ad (or creative + ad on the existing ad set with adSetId). Nothing is uploaded or created and nothing is stored; media is checked by URL. Supports one creative with imageUrl, image placementAssets, carouselCards, an existing video.id, or an existing post. Several creatives, a new video.url and video placementAssets need uploads first and return 400. Success returns 200 with per-node results; a Meta rejection returns the Meta error.