Meta Ads Integration

Connect your AI agents to Meta (Facebook and Instagram) Ads to automate campaign and creative management for storm-response and other time-sensitive marketing workflows. Agents can create campaigns, build audiences, set geographic targeting, produce ad creatives, and publish ads. The integration uses Meta's Facebook Login for Business OAuth flow and enforces publish-safety gates so that agents cannot spend money without explicit controls in place.

Overview

The Meta Ads Integration creates a single per-tenant connection using OAuth with a long-lived (~60-day) token. On connection, five agent tools are created automatically. Because publishing campaigns and creatives spends real money, the platform defaults to a human-in-the-loop model - all campaigns are created in a PAUSED/draft state until an admin approves them via the Publish Approval Queue (or until you enable autonomous publishing, which enforces a daily budget cap).

Tools Created on Connection

Tool	Description
meta_create_campaign	Create a new campaign (starts PAUSED by default)
meta_create_audience	Define a custom or lookalike audience
meta_create_geo_targeting	Add geographic targeting rules to a campaign
meta_create_creative	Build ad creatives (image, copy, call-to-action)
meta_publish_ads	Take a campaign live (requires approval or autonomous-publish enabled)

warning

meta_publish_ads moves real money. Campaigns are created paused by default and require an explicit approval action in the Publish Approval Queue before going live. Review the Publish Safety section below before enabling autonomous publishing.

info

Meta Ads Integration requires the custom.meta feature code on your subscription. Contact your Outermind account manager if this is not included.

Getting Started

Prerequisites

Before connecting, you will need:

1. A Meta Business account with access to at least one active Ad Account.
2. Admin permissions on the Ad Account in Meta Business Manager.
3. The ads_management and business_management scopes granted during OAuth authorization.

Step 1: Navigate to Meta Connection

1. Go to Capabilities > Connections.
2. Click Meta (under the Marketing and Social category).
3. Click Connect Meta.

Step 2: Authorize with Facebook Login for Business

1. A Facebook Login for Business popup opens.
2. Sign in with a Meta account that has access to your Business Manager.
3. Review the requested permissions and click Allow.
4. The popup closes automatically when authorization completes.

Step 3: Select an Ad Account

After authorization, the wizard moves to the Select Ad Account step:

1. A list of your Meta ad accounts is displayed (name, act_<id>, currency, status).
2. Select one ad account to associate with this connection.
3. Disabled or closed accounts are shown but cannot be selected.
4. Click Continue.

Step 4: Assign Tools to Agents

1. Select the agents, SMEs, or CAIOO that should have access to Meta tools.
2. Choose All Tools or select individual tools from the list.
3. Note the callout - meta_publish_ads is the money-spend tool and autonomous publishing is off by default.
4. Click Continue (or Skip and Complete if no agents exist yet).

Step 5: Complete

The wizard shows a confirmation of your connected ad account, account currency, and current safety settings. Click Complete to go to the connection page.

---

Connection Page

Navigate to Capabilities > Connections > Meta Ads to manage your tenant's Meta Ads connection.

Connected State

When a connection is active, the page shows:

• Ad account name and account ID (act_<id>)
• Business name associated with the account
• Currency badge for the connected ad account
• Granted OAuth scopes for the connection
• Status badge (Connected / Token Expired / Error)
• Tools list - each of the five tools and how many agents are currently assigned to it (with meta_publish_ads highlighted as the money-spend tool)
• Publish Safety panel - the two safety-gate controls (see below)
• Test Connection button - verifies the stored token is still valid without triggering any API side effects
• Disconnect button in the Danger Zone

Token Expiry Banner

Meta uses long-lived tokens (~60 days) that cannot be silently refreshed. When your token is within the expiry warning window or has already expired, a banner appears:

• Amber banner (expiry approaching): "This Meta connection expires on {date}. Reconnect to keep managing ads." with a Reconnect button.
• Red banner (token expired): connection is broken and agents cannot use Meta tools until you reconnect.

Click Reconnect to re-run the OAuth flow. Your connection configuration and safety settings are preserved.

Error State

If the connection encounters a non-expiry error, a red banner appears with the error message and a Test Connection button. If retrying does not resolve the issue, disconnect and reconnect.

Not-Connected State

If no connection exists, the page shows a Connect Meta button that launches the setup wizard.

---

Publish Safety

The Publish Safety panel controls the two money-movement guardrails for the connected account. These settings apply to the meta_publish_ads tool.

Autonomous Publishing

State	Behavior
Off (default)	Ad publishing requires explicit human approval via the Publish Approval Queue before anything goes live.
On	Agents may publish ads directly, up to the daily budget cap, without a human approval step each time.

To enable autonomous publishing:

1. On the connection page, locate the Publish Safety panel.

2. Toggle Autonomous Publishing to ON.

3. A confirmation dialog appears with an explicit money-spend warning:

   With autonomous publishing on, agents can take campaigns live and spend up to your daily budget cap WITHOUT asking for approval each time.

4. Confirm to persist the change.

danger

Enabling autonomous publishing means agents can launch live, money-spending campaigns without human review for every action. Only enable this if you have a reliable daily budget cap in place and fully trust the agent's campaign-creation logic.

Max Daily Budget

The max daily budget is the hard ceiling on the daily budget for any campaign an agent publishes. Campaigns that would exceed this cap require manual approval even when autonomous publishing is on.

To set the budget:

1. In the Publish Safety panel, locate the Max Daily Budget field.
2. Enter a non-negative number. The currency displayed matches your connected ad account.
3. Changes are saved automatically on blur.

tip

Start with a conservative daily budget (for example, your typical per-campaign daily spend) and increase it after validating agent behavior.

---

Disconnecting

To remove the Meta connection:

1. On the connection page, scroll to the Danger Zone section.
2. Click Delete Connection.
3. A confirmation modal shows the number of agents that will lose access to the five Meta tools.
4. Confirm to delete.

All five tools are removed and agent assignments are revoked. Safety settings are cleared. You can reconnect at any time via the setup wizard.

---

Frequently Asked Questions

Why do I see a token expiry warning so soon after connecting?

Meta long-lived tokens are valid for approximately 60 days and cannot be automatically refreshed. You will receive an advance warning when the expiry date is approaching. Reconnect before the token expires to avoid interrupting agent access.

Can I connect multiple Meta ad accounts?

No - the Meta integration supports one ad account per tenant. To switch ad accounts, disconnect and reconnect selecting the new account.

What happens to running campaigns if I disconnect?

Disconnecting removes agent tool access; it does not affect existing Meta campaigns. Campaigns that are already live in Meta continue to run. Only new agent-driven actions are blocked.

An agent tried to publish an ad but got an error. What does it mean?

Common agent-facing errors:

• "Autonomous publishing is disabled" - An approval request has been sent to the account owner. Check the Publish Approval Queue.
• "Exceeds configured daily budget cap" - The campaign's requested daily budget exceeds MaxDailyBudget. Increase the cap or have the agent reduce the campaign budget.
• "Meta connection token expired" - Reconnect the Meta integration from the connection page.

Does the integration store Meta credentials?

No Meta credentials (passwords, developer secrets) are stored. Only the OAuth long-lived token is stored, encrypted, in the Outermind platform.