Create Meta Ad Set

Creates a Meta ad set. optimization_goal: LINK_CLICKS | LANDING_PAGE_VIEWS | IMPRESSIONS | REACH | POST_ENGAGEMENT | OFFSITE_CONVERSIONS | LEAD_GENERATION | THRUPLAY | CONVERSATIONS | APP_INSTALLS | VALUE | QUALITY_LEAD | PAGE_LIKES | QUALITY_CALL | PROFILE_VISIT. FOLLOWER / PROFILE GROWTH (Instagram): use optimization_goal PROFILE_VISIT + billing_event IMPRESSIONS + promoted_object page_id (the Facebook Page linked to the target Instagram account); build the ad with cta_type VIEW_INSTAGRAM_PROFILE and the Instagram actor, and favour Instagram Reels/Feed placements (publisher_platforms=instagram). This drives profile visits that convert to followers; there is no direct "gain followers" objective on Meta. countries: comma-separated country codes (TR,US); empty = TR when no other location is given. LOCAL TARGETING: regions / cities take the numeric `key` from search_meta_interests(kind="adgeolocation") — pass that key, NOT the place name (Meta rejects a name). Leave countries EMPTY when targeting regions/cities inside that country: Meta rejects a country together with a city or region inside it ("Remove a conflicting location"). RADIUS / POINT TARGETING: places = a JSON list of pinned places WITH a radius ([{"key":"<adgeolocation key>","radius":5.7,"distance_unit":"mile"}]); the key is the adgeolocation `key` (like a city, but with a radius around it), distance_unit "mile" (1-50) or "kilometer" (1-80); custom_locations = a JSON list of raw coordinates with a radius ([{"latitude":41.01,"longitude":28.97,"radius":10,"distance_unit":"kilometer"}]). COPYING A WINNING SET VERBATIM: geo_locations = the raw Meta geo_locations object read from an existing ad set (list_meta_adsets → targeting.geo_locations) passed through unchanged (countries/regions/cities/places/custom_locations all preserved) — the exact way to reproduce a proven radius/place target on a new ad set; it overrides countries/regions/cities/places/custom_locations when given (the deprecated location_types key is dropped and radius is clamped for you). BUDGET: give EITHER daily_budget OR lifetime_budget (main currency) — leave BOTH empty if the campaign has a budget (CBO). A lifetime_budget REQUIRES end_time. SCHEDULING: start_time / end_time in ISO 8601 with offset (2026-08-15T09:00:00+0300). BIDDING: bid_strategy LOWEST_COST_WITHOUT_CAP (automatic, default) | LOWEST_COST_WITH_BID_CAP | COST_CAP — the last two REQUIRE bid_amount (max bid / target cost per result, main currency). Bidding/budget live on the CAMPAIGN when it is CBO. Age 18-65. DETAILED TARGETING: genders (1=male,2=female), interest_ids (from search_meta_interests). DEMOGRAPHICS & BEHAVIOURS (Ads Manager’s "Relationship status", "Parents", "Life events", "Industry", "Behaviours" boxes). HOW THEY COMBINE: relationship_statuses and education_statuses are ALWAYS AND-ed with everything else (Meta gives no choice), so "married AND interested in couples therapy" is expressible. interest_ids, behaviors, family_statuses, life_events and industries are combined by combine_mode: "or" (default, and what Ads Manager itself does) puts them in ONE flexible_spec block so someone matching ANY of them qualifies; "and" puts each in its own block, which requires ALL of them at once and shrinks reach a lot. "and" returns the intersection of the groups. Codes: relationship_statuses = comma-separated codes 1=single 2=in a relationship 3=MARRIED 4=engaged 5=not specified 6=civil union 7=domestic partnership 8=open relationship 9=complicated 10=separated 11=divorced 12=widowed; education_statuses = codes 1=in high school 2=in college 3=graduated 4=some college 5=associate degree 6=some grad school 7=master’s 8=professional degree 9=doctorate 10=unspecified 11=some high school 12=high-school grad 13=bachelor’s; family_statuses / life_events / industries / behaviors = comma-separated numeric IDs from search_meta_interests(kind="adTargetingCategory", category_class="family_statuses" | "life_events" | "industries" | "behaviors" | "income") (parents of toddlers, newly-weds, recently moved…). Only IDs work, not names. custom_audience_ids / excluded_custom_audience_ids (from list_meta_audiences), publisher_platforms (facebook,instagram,audience_network,messenger,whatsapp,threads; empty = automatic). PLACEMENTS (which slot inside a platform): facebook_positions / instagram_positions / whatsapp_positions / messenger_positions / audience_network_positions / threads_positions, comma-separated. Leave empty and Meta runs every slot of the chosen platform (Feed, Reels, Explore, Search...). Story-only setup: publisher_platforms="facebook,instagram,whatsapp" + facebook_positions="story" + instagram_positions="story" + whatsapp_positions="status". Valid slots — facebook: feed, profile_feed, story, facebook_reels, marketplace, video_feeds, search, instream_video, right_hand_column, notification; instagram: stream, story, reels, explore, explore_home, profile_feed, profile_reels, ig_search; messenger: messenger_home, story, sponsored_messages; audience_network: classic, rewarded_video; whatsapp: status; threads: threads_feed. Narrowing placements turns Advantage+ placements OFF, which is intended but reduces reach. For conversion/lead promoted_object: OFFSITE_CONVERSIONS → pixel_id + custom_event_type (PURCHASE|LEAD|COMPLETE_REGISTRATION|ADD_TO_CART...) OR custom_conversion_id (from list_meta_custom_conversions) to optimize for a specific Meta CUSTOM CONVERSION — custom_conversion_id is MUTUALLY EXCLUSIVE with pixel_id/custom_event_type (Meta rejects the combination with "Promoted Object Invalid"), pass one or the other; LEAD_GENERATION → page_id; app → application_id + object_store_url. CATALOG SALES / DPA: product_catalog_id + product_set_id (from list_meta_catalogs / list_meta_product_sets) with optimization_goal OFFSITE_CONVERSIONS — build the dynamic creative with create_meta_dynamic_ad. MESSAGING (Click-to-WhatsApp / click-to-Messenger): campaign objective OUTCOME_ENGAGEMENT, optimization_goal CONVERSATIONS, destination_type WHATSAPP (or MESSENGER / INSTAGRAM_DIRECT) and page_id (the Page needs a connected WhatsApp number for WHATSAPP). The ad (create_meta_link_ad/create_meta_video_ad) needs the CTA that matches the destination (WHATSAPP → WHATSAPP_MESSAGE, MESSENGER → SEND_MESSAGE, INSTAGRAM_DIRECT → INSTAGRAM_MESSAGE) so the button opens a chat; a mismatched button creates the ad but Meta never delivers it. CALL ADS (phone-call campaigns): optimization_goal QUALITY_CALL + billing_event IMPRESSIONS + page_id (the Page that carries the phone number); destination_type defaults to PHONE_CALL. EU/EEA TARGETING (DSA): when the ad set targets any EU country, Meta requires who the ad is for and who pays for it. dsa_beneficiary is the business benefiting (the brand name) and dsa_payor who pays (defaults to the beneficiary). Without them Meta rejects the ad set with error 100 and nothing is created. Non-EU targeting is unaffected. AUDIENCE EXPANSION: audience_expansion="on" turns Meta’s Advantage+ audience on (Meta may show the ad beyond your targeting). It is OFF by default here: expansion often brings low-intent leads and junk messages; it widens reach for small audiences or volume goals. confirm=false = preview.