Skip to content

CreateCallAdRequest.md

Latest commit

 

History

History
82 lines (76 loc) · 8.15 KB

CreateCallAdRequest.md

File metadata and controls

82 lines (76 loc) · 8.15 KB
Raw

Zernio::CreateCallAdRequest

Properties

Name Type Description Notes
account_id String Facebook or Instagram SocialAccount ID.
ad_account_id String Meta ad account ID, e.g. `act_123456789`.
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.
headline String Single-creative shape only. Mutually exclusive with `creatives[]`. [optional]
body String Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`. [optional]
image_url 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. [optional]
video CtwaAdRequestBodyVideo [optional]
creatives Array<CtwaAdRequestBodyCreativesInner> 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`. [optional]
ad_set_id 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. [optional]
budget_amount Float 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. [optional]
budget_type String Required unless `adSetId` is set. [optional]
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). [optional]
end_date Time ISO 8601 datetime. Required when `budgetType` is `lifetime`. [optional]
countries Array<String> ISO 3166-1 alpha-2 country codes. Defaults to `[&quot;US&quot;]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied. [optional]
cities Array<CtwaAdRequestBodyCitiesInner> 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). [optional]
regions Array<CtwaAdRequestBodyRegionsInner> Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region). [optional]
zips Array<CtwaAdRequestBodyZipsInner> ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /v1/ads/targeting/search. [optional]
metros Array<CtwaAdRequestBodyZipsInner> DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`). [optional]
custom_locations Array<CreateStandaloneAdRequestCustomLocationsInner> 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. [optional]
age_min Integer [optional]
age_max Integer [optional]
interests Array<CreateStandaloneAdRequestBehaviorsInner> [optional]
audience_id String Custom audience ID to target. [optional]
placements CtwaAdRequestBodyPlacements [optional]
advantage_audience 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). [optional]
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. [optional]
bid_strategy 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. [optional]
bid_amount Float 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. [optional]
roas_average_floor Float 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. [optional]
dsa_beneficiary 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. [optional]
dsa_payor 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. [optional]
phone_number String E.164 number the CALL_NOW CTA dials (e.g. +34600111222).
link_url String Website shown as the creative's link. Required: Meta rejects tel: as link_data.link; the phone number rides only the CTA.

Example

require 'zernio-sdk'

instance = Zernio::CreateCallAdRequest.new(
  account_id: null,
  ad_account_id: null,
  name: null,
  headline: null,
  body: null,
  image_url: null,
  video: null,
  creatives: null,
  ad_set_id: null,
  budget_amount: null,
  budget_type: null,
  currency: null,
  end_date: null,
  countries: null,
  cities: null,
  regions: null,
  zips: null,
  metros: null,
  custom_locations: null,
  age_min: null,
  age_max: null,
  interests: null,
  audience_id: null,
  placements: null,
  advantage_audience: null,
  objective: null,
  bid_strategy: null,
  bid_amount: null,
  roas_average_floor: null,
  dsa_beneficiary: null,
  dsa_payor: null,
  phone_number: null,
  link_url: null
)