Update Meta Ad Set

Updates a Meta ad set (only the fields provided). status: ACTIVE | PAUSED | ARCHIVED. Budget increases are subject to the safety cap. DELIVERY SETTINGS (existing targeting is preserved; only these fields change): • publisher_platforms narrows placement; comma-separated: facebook,instagram,audience_network,messenger,whatsapp,threads ("instagram" = Instagram only). • facebook_positions / instagram_positions / whatsapp_positions / messenger_positions / audience_network_positions / threads_positions = the slot INSIDE a platform, comma-separated (facebook/instagram: story, feed, reels…; whatsapp: status). "Story + WhatsApp Status only" = publisher_platforms="facebook,instagram,whatsapp" + facebook_positions="story" + instagram_positions="story" + whatsapp_positions="status". Pass "-" to drop the restriction for that platform (all of its slots come back). See create_meta_adset for the full slot list. • audience_expansion — "off" (turns off Advantage custom audience / audience expansion; prevents a retargeting set from drifting from the list to a cold audience) or "on". • location_expansion — "off" | "on": Meta's LOCATION EXPANSION (targeting_automation.individual_setting.geo). When on, Meta also shows the ad to people OUTSIDE the selected locations whom it considers interested in them (intent to travel or buy there). It is a separate switch from audience_expansion: turning Advantage+ audience off does NOT turn this off. Read the current value in list_meta_adsets → targeting.targeting_automation.individual_setting.geo (1 = on). "off" keeps delivery to the selected locations, so messages stop arriving from cities that are not served. TARGETING (omitted fields keep their current value; Meta replaces targeting atomically, so the tool reads the live spec and merges): • age_min / age_max — 18..65. • genders — "1" (men), "2" (women) or "1,2"; "-" CLEARS the restriction (all genders). "" means leave unchanged. Anything else is REJECTED — an invalid value used to silently clear the restriction and widen the ad set to everyone. • countries / regions / cities — comma-separated; region & city KEYS are the numeric `key` from search_meta_interests(kind="adgeolocation") (NOT the place name). Passing any of them replaces the location set. • places / custom_locations — RADIUS targeting (JSON). places = [{"key":"2034720566774469","radius":5.7,"distance_unit":"mile"}] (a pinned place + drop-radius; key from search_meta_interests(kind="adgeolocation")); custom_locations = [{"latitude":41.01,"longitude":28.97,"radius":10,"distance_unit":"kilometer"}]. distance_unit "mile" (1-50) or "kilometer" (1-80), clamped for you. Either one replaces the location set. • geo_locations = the raw Meta geo_locations object (from another ad set's targeting.geo_locations), passed through verbatim to reproduce a proven radius/place target; it overrides countries/regions/cities/places/custom_locations, drops the deprecated location_types and clamps radius. • excluded_countries / excluded_regions / excluded_cities EXCLUDE locations (Meta targeting.excluded_geo_locations): a radius around one city minus a neighbouring region is geo_locations plus excluded_regions=<region key>. Same keys as regions/cities (search_meta_interests(kind="adgeolocation") `key`), countries as ISO codes. Each field replaces only that exclusion dimension and keeps the included locations and the other exclusions; "-" removes that dimension's exclusions. excluded_geo_locations — the raw Meta excluded_geo_locations object (JSON) replacing ALL exclusions; "-" removes every exclusion. • interest_ids — comma-separated interest IDs; OMIT to preserve current interests, pass an empty string to clear only interest targeting (demographic entries are kept). • relationship_statuses / education_statuses — comma-separated numeric codes (3 = MARRIED; see create_meta_adset for the full code list). AND-ed with interests, so you can add "married" to an existing interest-targeted set without touching it. • family_statuses / life_events / industries / behaviors — comma-separated IDs from search_meta_interests(kind="adTargetingCategory", category_class=...) — parents & child age brackets, newly-weds/recently-moved, industry, behaviours. Each field you pass replaces only that dimension; the ones you omit are preserved. OPTIMIZATION: • optimization_goal (OFFSITE_CONVERSIONS and so on) • pixel_id + custom_event_type (PURCHASE and so on) fix an ad set optimizing for the wrong conversion event without rebuilding the campaign. • custom_conversion_id (from list_meta_custom_conversions) points the ad set at a specific Meta CUSTOM CONVERSION instead of a standard pixel event, with optimization_goal OFFSITE_CONVERSIONS. custom_conversion_id is MUTUALLY EXCLUSIVE with pixel_id / custom_event_type (Meta rejects the combination with "Promoted Object Invalid"). Meta forbids changing the conversion/optimization of an ALREADY-PUBLISHED ad set (error subcode 3260011 "Can't Make Edits to Published Ad Set"); a live ad set's conversion changes only through a new ad set. The same applies when the new goal needs a different attribution window (OFFSITE_CONVERSIONS with 7-day click → LINK_CLICKS, which only allows 1-day click): Meta does not allow the attribution window to change after an ad set is created (copies keep it too), so the path is a new ad set via create_meta_adset in the same campaign. MESSAGING (Click-to-WhatsApp / click-to-Messenger): • destination_type WHATSAPP | MESSENGER | INSTAGRAM_DIRECT | PHONE_CALL (+ page_id) — pins a CONVERSATIONS ad set's chat destination without rebuilding it (the Page needs a WhatsApp number connected for WHATSAPP). page_id also sets/overrides the messaging promoted_object. BIDDING: • bid_strategy LOWEST_COST_WITHOUT_CAP (automatic) | LOWEST_COST_WITH_BID_CAP | COST_CAP. The last two REQUIRE a positive bid_amount in the account's main currency. A bid_amount is never accepted without its strategy, so an intended bid cap cannot silently become a different bidding mode. CBO campaigns own bid settings at campaign level; this tool refuses an ad-set bid edit there instead of sending a misleading write. After a confirmed bid edit, it reports success only if Meta's live read-back confirms the intended effective strategy and, for bid/cost caps, the exact minor-unit amount. confirm=false = preview.