Meta Ads

The Meta Ads app connects Facebook and Instagram advertising to Sprigr Team through the Meta Marketing API. Agents can read and report on campaigns, ad sets, ads and creatives, run Insights reports with breakdowns that separate Facebook from Instagram, search targeting options and estimate reach and delivery, manage custom audiences, custom conversions and automated rules, and create or change campaigns at your instruction. Universal read and write primitives plus a raw request escape hatch reach any Graph API object.

Note

Meta Ads ships as a marketplace app with one connection per install. An admin connects one Meta account that has access to your ad accounts, and every agent with the app acts through it. A default ad account is set once for the install. Anything that creates, changes or deletes advertising objects pauses for your confirmation.

Prerequisites

• A Meta (Facebook) account with access to the ad accounts you want agents to work with, directly or through Business Manager.
• Admin or Owner role in your Sprigr Team organisation to install the app.

Installing and connecting

1. Install the app

   Sign in to team.sprigr.com, open Apps in the sidebar, find Meta Ads under Available, and install it. No secrets are requested. See Installing Apps.

2. Connect a Meta account

   Open the app’s settings page from Apps > Installed and click Connect Meta Ads. Sign in with a Facebook account that has ad account access and approve the request. The page then lists the accessible ad accounts.

3. Set the default ad account

   Choose the ad account tools use when a request does not name one, under Default Meta ad account, or ask your agent to set it with meta_ads_set_default_ad_account.

4. Check the connection

   Ask your agent “Is Meta Ads connected, and which ad accounts can you see?” It calls meta_ads_connection_status, which also reports when the token expires.

Try asking your agent

“How did our Instagram campaigns perform last week compared with Facebook: spend, clicks, CTR and purchase ROAS?”

“Pause the ‘Spring Sale’ campaign.”

“How big is an audience of women 25 to 44 in Australia interested in hiking?”

Tokens and reconnecting

Meta issues long-lived tokens that last about 60 days and provides no refresh token. The app renews the token daily by re-exchange so it never reaches expiry in normal use. A token that has already expired cannot be renewed, only reconnected: meta_ads_connection_status reports reconnect needed, and an admin clicks Connect Meta Ads again.

What agents can do

The app exposes 44 tools. At a category level:

• Reporting: meta_ads_insights for account-level reports at account, campaign, ad set or ad level with date presets or ranges and breakdowns; meta_ads_node_insights scoped to one object; async report jobs for large pulls (start, status, results).
• Reading: list campaigns, ad sets, ads, creatives, custom and saved audiences, images, videos, pixels, custom conversions, automated rules, connected Instagram accounts, businesses, pages and ad accounts; the account’s change history; meta_ads_get_node and meta_ads_get_edge read any object or edge.
• Planning: meta_ads_targeting_search for interests, behaviours and demographics; meta_ads_delivery_estimate and meta_ads_reach_estimate for a targeting spec.
• Creating and changing (confirmation-gated): create campaigns, ad sets, ads, creatives, custom audiences, custom conversions and automated rules; meta_ads_update_node to pause, rename, rebudget or retarget any object; meta_ads_delete_node for permanent deletion; meta_ads_post_edge for actions the named tools do not wrap.
• Bulk and raw: meta_ads_batch runs up to 50 Graph calls in one round trip; meta_ads_request is the raw escape hatch.

Campaigns are created paused unless you say otherwise, and the agent prefers pausing over deleting.

Common use cases

• Weekly performance brief. A scheduled workflow reports spend, results and cost per result by campaign, split by Facebook and Instagram.
• Budget pacing. “Are we on track to spend this month’s budget?” reads spend against the campaign budgets.
• Creative review. The agent lists ads by effective status and surfaces those rejected or under-delivering.
• Audience building. The agent creates a website custom audience from a pixel rule after you confirm.
• Guardrails. An automated rule pauses ad sets whose cost per result exceeds a threshold, created and reviewed from chat.

Troubleshooting

Not connected or reconnect needed Nobody has completed the Connect Meta Ads step, or the long-lived token expired. Reconnect from the settings page.

Ad account not found or permission errors The connected Meta account does not have access to that ad account, or the default ad account is unset. Check accessible accounts on the settings page and set the default.

Rate limits Meta rate-limits per ad account and app. The agent should use Insights with breakdowns or meta_ads_batch rather than many single reads, and async report jobs for large date ranges.

An action is waiting for confirmation Creates, updates, deletes and edge posts pause until you confirm in the chat.

Next steps

• Google Ads: The equivalent app for Google advertising.
• Google Analytics: Sessions and conversions to join with ad performance.
• Integrations Overview: See all available integrations.