Connect Facebook Ads to Antigravity

Create a new ad set in an existing Meta Ads campaign (Facebook or Instagram). Created paused by default so it does not spend until enabled. Budget amounts are in the account currency minor unit (e.g. cents: 5000 means 50.00). Currencies without cents (CLP, COP, CRC, HUF, IDR, ISK, JPY, KRW, PYG, TWD, VND) use whole units: 300000 means 300000 COP. Provide at most one of daily_budget or lifetime_budget; omit both only when the campaign uses campaign budget optimization. lifetime_budget requires end_time. Some optimization goals require promoted_object, a Meta spec naming what is optimized (e.g. {"pixel_id": "<id>", "custom_event_type": "PURCHASE"} for conversions, or {"page_id": "<id>"} for page likes). destination_type sets where the ad sends people; for boosting an existing post (boost_post) use ON_POST with optimization_goal POST_ENGAGEMENT to keep engagement on the post (no call to action needed). A website or undefined destination instead makes Meta require a website URL and call to action in the creative. start_time and end_time are ISO 8601 timestamps (e.g. 2027-01-01T00:00:00-0800); start_time defaults to now and cannot be changed once the ad set has started, even while paused. An ad set with its own budget is created with bid_strategy LOWEST_COST_WITHOUT_CAP (highest volume) unless bid_strategy or bid_amount is given; pass bid_amount with a capped strategy (LOWEST_COST_WITH_BID_CAP or COST_CAP). Under campaign budget optimization the campaign's bid strategy applies and none is sent. Ads delivered to the EU require dsa_beneficiary and dsa_payor, naming who benefits from and who pays for the ad. Ads delivered to Taiwan, Singapore, Thailand, Brazil, Australia, Malaysia or India require regional_regulated_categories (e.g. SINGAPORE_UNIVERSAL) together with regional_regulation_identities holding the matching beneficiary and payer ids (e.g. {"singapore_universal_beneficiary": "<id>", "singapore_universal_payer": "<id>"}; THAILAND_UNIVERSAL, BRAZIL_REGULATION, AUSTRALIA_UNIVERSAL and MALAYSIA_UNIVERSAL use "universal_beneficiary" and "universal_payer"; financial service ads in Australia also declare AUSTRALIA_FINSERV with "australia_finserv_beneficiary" and "australia_finserv_payer"). These are verified identity ids from Meta Business settings > Verified identities (not page or business ids); ad account defaults are not inherited by ad sets created through the API. Meta also asks some accounts for a verified advertiser on any ad set ("Advertiser is missing"); then pass regional_regulation_identities with "universal_beneficiary" and "universal_payer" and add regional_regulated_categories only when the targeted country has a value listed above. extra_params passes further Meta ad set fields straight to the Graph API for anything this action does not model yet, e.g. {"attribution_spec": [{"event_type": "CLICK_THROUGH", "window_days": 7}]}. Prefer the named parameters where they exist: a key that repeats one already set is rejected, since only one of the two values could win.

Create a new Meta Ads campaign (Facebook or Instagram). Created paused by default so it does not spend until enabled. objective is a Meta campaign objective (e.g. OUTCOME_TRAFFIC, OUTCOME_LEADS, OUTCOME_SALES). special_ad_categories must list any regulated categories the ads fall under (e.g. HOUSING, EMPLOYMENT, CREDIT) or be empty; country declarations such as SINGAPORE_UNIVERSAL or TAIWAN_UNIVERSAL belong to regional_regulated_categories on the ad set instead. Setting a campaign budget enables campaign budget optimization; amounts are in the account currency minor unit (e.g. cents: 5000 means 50.00). Currencies without cents (CLP, COP, CRC, HUF, IDR, ISK, JPY, KRW, PYG, TWD, VND) use whole units: 300000 means 300000 COP. Provide at most one of daily_budget or lifetime_budget. A campaign with a budget (or with ad set budget sharing enabled) is created with bid_strategy LOWEST_COST_WITHOUT_CAP (highest volume) unless bid_strategy is given; its ad sets inherit it and cannot override it. Without a campaign budget leave bid_strategy unset and choose it per ad set in create_adset. When no campaign budget is set, some accounts require is_adset_budget_sharing_enabled to be specified.

Create a new ad in an existing Meta Ads ad set (Facebook or Instagram). Created paused by default so it does not spend until enabled. The simplest way is to provide page_id and link plus optional text (message, headline, description), image_url or image_hash (from create_ad_image) and call_to_action_type; these build a single-image link ad creative automatically. For a Click-to-Message ad, set messaging_destination (MESSENGER or INSTAGRAM_DIRECT) instead of link; the message opens a conversation with the page. For a video ad, upload the video first with create_ad_video and pass its video_id here with page_id and a required thumbnail image_url or image_hash; message becomes the primary text, headline the title, description the caption, and call_to_action_type (with link) adds a button. For advanced cases, pass a full Meta creative spec via creative instead (e.g. {"creative_id": "<id>"} to reuse an existing creative, or {"object_story_spec": {...}}). Provide either the individual creative fields or creative, not both.

Update editable attributes of a Meta Ads campaign (Facebook or Instagram). Provide only the fields to change; at least one is required. spend_cap is a lifetime spend limit in the account currency minor unit (e.g. cents: 5000 means 50.00). Currencies without cents (CLP, COP, CRC, HUF, IDR, ISK, JPY, KRW, PYG, TWD, VND) use whole units: 300000 means 300000 COP. special_ad_categories lists the regulated categories the ads fall under (e.g. HOUSING, EMPLOYMENT, CREDIT) or is empty; country declarations such as SINGAPORE_UNIVERSAL or TAIWAN_UNIVERSAL belong to regional_regulated_categories on the ad set (update_adset) instead. Use pause_campaign/enable_campaign to change status and set_campaign_budget to change the budget. objective is fixed at creation and cannot be updated.

Update editable attributes of a Meta Ads ad set (Facebook or Instagram). Provide only the fields to change; at least one is required. bid_amount is in the account currency minor unit (e.g. cents: 500 means 5.00). Currencies without cents (CLP, COP, CRC, HUF, IDR, ISK, JPY, KRW, PYG, TWD, VND) use whole units: 300000 means 300000 COP. Switching bid_strategy to a capped strategy (LOWEST_COST_WITH_BID_CAP or COST_CAP) requires bid_amount in the same call. start_time and end_time are ISO 8601 timestamps (e.g. 2027-01-01T00:00:00-0800); end_time less than one year ahead. Use pause_adset/enable_adset to change status and set_adset_budget to change the budget. Ads delivered to the EU require dsa_beneficiary and dsa_payor, naming who benefits from and who pays for the ad. Ads delivered to Taiwan, Singapore, Thailand, Brazil, Australia, Malaysia or India require regional_regulated_categories (e.g. SINGAPORE_UNIVERSAL) together with regional_regulation_identities holding the matching beneficiary and payer ids (e.g. {"singapore_universal_beneficiary": "<id>", "singapore_universal_payer": "<id>"}; THAILAND_UNIVERSAL, BRAZIL_REGULATION, AUSTRALIA_UNIVERSAL and MALAYSIA_UNIVERSAL use "universal_beneficiary" and "universal_payer"; financial service ads in Australia also declare AUSTRALIA_FINSERV with "australia_finserv_beneficiary" and "australia_finserv_payer"). These are verified identity ids from Meta Business settings > Verified identities (not page or business ids); ad account defaults are not inherited by ad sets created through the API. Meta also asks some accounts for a verified advertiser on any ad set ("Advertiser is missing"); then pass regional_regulation_identities with "universal_beneficiary" and "universal_payer" and add regional_regulated_categories only when the targeted country has a value listed above. extra_params passes further Meta ad set fields straight to the Graph API for anything this action does not model yet, e.g. {"attribution_spec": [{"event_type": "CLICK_THROUGH", "window_days": 7}]}. Prefer the named parameters where they exist: a key that repeats one already set is rejected, since only one of the two values could win.

Pause an active Meta Ads campaign (Facebook or Instagram). Reversible via enable_campaign.

Set the daily or lifetime budget of a Meta Ads campaign (Facebook or Instagram). The amount is in the account currency minor unit (e.g. cents: 5000 means 50.00). Currencies without cents (CLP, COP, CRC, HUF, IDR, ISK, JPY, KRW, PYG, TWD, VND) use whole units: 300000 means 300000 COP. Only one budget type applies at a time; setting one replaces the other. Meta rejects frequent budget changes on the same campaign; space out repeated changes instead of adjusting in rapid succession.

Activate a paused Meta Ads campaign (Facebook or Instagram). Reversible via pause_campaign.

Activate a paused Meta Ads ad (Facebook or Instagram). Reversible via pause_ad.

Activate a paused Meta Ads ad set (Facebook or Instagram). Reversible via pause_adset.

Pause an active Meta Ads ad (Facebook or Instagram). Reversible via enable_ad.

Edit the creative of an existing Meta Ads ad (Facebook or Instagram): ad copy (message), headline, description, destination link, image, call-to-action button, URL tracking tags and Advantage+ enhancement settings. Meta treats ad creatives as immutable, so this copies the ad's current creative (keeping its name, url_tags and degrees_of_freedom_spec), applies the changes, creates the result as a new creative and re-points the ad at it; the ad keeps its id, but the returned creative id is new. Provide ad_id plus at least one field to change. Editable content fields depend on the creative's media type: link ads support all of them; video ads support message, headline, description, image_url (thumbnail), link and call_to_action_type (the link lives on the button, so adding a link to a video ad without a button also requires call_to_action_type); photo ads only message (the caption) and image_url; text ads only message. For carousel ads (link ads with cards), message edits the text above the cards; headline, description, link, image_url and call_to_action_type live on the cards, so also pass card_index (0-based) to edit one specific card. url_tags (e.g. 'utm_source=x&utm_medium=y') and degrees_of_freedom_spec (a raw Meta spec) can be edited on any creative, including ads that promote an existing organic post (e.g. boosted posts) — but content fields on those ads cannot be edited; edit the post itself instead. Dynamic/catalog creatives cannot be edited at all. Omitted fields keep their current values; to clear url_tags pass an empty string, and to reset degrees_of_freedom_spec to Meta's default enhancement behavior pass an empty object. To swap the ad to a different existing creative, use update_ad instead.

Pause an active Meta Ads ad set (Facebook or Instagram). Reversible via enable_adset.

Set the daily or lifetime budget of a Meta Ads ad set (Facebook or Instagram). The amount is in the account currency minor unit (e.g. cents: 5000 means 50.00). Currencies without cents (CLP, COP, CRC, HUF, IDR, ISK, JPY, KRW, PYG, TWD, VND) use whole units: 300000 means 300000 COP. Only one budget type applies at a time; setting one replaces the other. Meta allows at most 4 budget changes per ad set per hour; further changes are rejected until the hour passes.

Update editable attributes of a Meta Ads ad (Facebook or Instagram). Provide only the fields to change; at least one is required. creative swaps the ad to a different creative and is a Meta creative reference (e.g. {"creative_id": "<id>"}). conversion_domain is the registrable domain the ad drives conversions to (e.g. example.com), used for conversion attribution. display_sequence orders the ad within a sequenced campaign. Use pause_ad/enable_ad to change status.

Boost (promote) an existing organic Facebook or Instagram post by creating a paid ad for it in an existing Meta Ads ad set. Provide the full post id (in '{page_id}_{post_id}' form, as it appears in the connector data) and the ad set to place the ad in. The ad reuses the published post as its creative via object_story_id, so no new copy or media is created. The target ad set MUST belong to an engagement campaign (objective OUTCOME_ENGAGEMENT) and name the post's page in its promoted_object; build it with create_campaign and create_adset first if needed. Two ad set shapes work: an ON_POST destination with optimization_goal POST_ENGAGEMENT (engagement on the post itself, no call-to-action needed), or a FACEBOOK_PAGE destination with optimization_goal PROFILE_AND_PAGE_ENGAGEMENT, which additionally requires a call-to-action button on the ad — pass call_to_action_type (e.g. VISIT_PROFILE) for that case, otherwise Meta rejects the ad with a 'call-to-action required' error. The page promoted by the ad set and the post's page must match, and the access token must have ads permission on that page. Created paused by default so it does not spend until enabled; use enable_ad to activate it.

Set or update the automated welcome message (greeting / ice breaker) shown when a user opens the conversation from a Meta Ads Click-to-Message ad (Messenger or Instagram, OUTCOME_ENGAGEMENT / CONVERSATIONS). The welcome message lives on the ad creative, which Meta treats as immutable, so this builds a new creative that copies the ad's existing creative and only swaps the welcome message, then re-points the ad at it. Provide ad_id plus either welcome_message (plain greeting text, the common case) or welcome_message_spec (a full page_welcome_message structure for ice breakers / quick replies), not both. The change is verified by reading the new creative back; the action fails if Meta did not persist the value.

Upload a video to a Meta Ads ad account from a public URL so it can be used in a video ad. Meta fetches the file from video_url and transcodes it; the action waits until the video is ready and returns its video_id. Pass that video_id to create_ad together with page_id and a thumbnail image_url to build the video ad. The upload cannot be undone via an action.

Duplicate an existing Meta Ads ad set (Facebook or Instagram). The copy keeps the source targeting, budget and schedule. Copied paused by default so it does not spend until enabled. Set status_option to active to launch it, or inherited to keep the source status. Set campaign_id to move the copy to another campaign, or omit it to keep the copy in the source campaign. Set deep_copy to also duplicate the ads in the ad set; a synchronous copy is limited to 3 ads. There is no delete action, so pausing the copy does not remove it.

Upload one or more images (JPEG, PNG or GIF, up to 30 MB each, at most 20 images and 100 MB per request) to a Meta Ads ad account and return one image_hash per image, in the order the files were sent. The images are sent as files uploaded with the request, not as params or URLs; Meta's image endpoint has no URL option. Each image appears in the account's image library under its filename. Use each image_hash in create_ad via the creative field, e.g. object_story_spec.link_data.child_attachments[].image_hash for carousel cards. Meta deduplicates images by content, so re-uploading the same file returns the same image_hash. The upload cannot be undone via an action.