Meta Ads

Meta Ads uses the existing Meta authorization flow to obtain an organization credential, then runs operational discovery and tools through Oblive’s direct Marketing API provider. Reporting, campaign delivery, Pages and Instagram assets, audiences, catalogs, measurement, custom conversions, experiments, and activity logs call fixed graph.facebook.com/v25.0 endpoints from the backend. They do not depend on Meta enabling the hosted Ads MCP rollout for an ad account.

Images, videos, catalog feeds, video creatives, and hashed customer-audience membership use the same connected Meta identity through Oblive’s private action gateway. The hosted Ads MCP remains an explicit deployment rollback mode, not the default operational path.

Before You Connect

The Oblive deployment administrator must first configure one Meta-approved OAuth client ID. For the local stack, set metaAdsOAuth.clientId and its public HTTPS redirectUri, then regenerate the environment and restart the frontend and backend. The Meta client and metaAdsOAuth.redirectUri must contain the identical URL ending in /oauth/mcp/callback.

Set publicFrontendUrl to the public app origin. Route that hostname to port 3001 and a separate callback/API hostname to port 3000; the app route must forward WebSockets for Vite HMR. Oblive does not manage the tunnel. Protect both routes with an external access policy because the local control plane has no end-user authentication gate.

This setup is deployment-scoped. Each organization connecting an ad account does not create its own developer app or supply a client secret. Use a Meta identity that can access the required businesses, ad accounts, and Pages; Oblive stores that organization’s authorization separately.

Choose:

• Read-only for reporting, discovery, and analysis; or
• Full access for reviewed campaign, creative, catalog, signal, experiment, or audience changes.

Chat remains read-only even when the organization selected full access. Consequential work runs only as a Growth task through the normal approval policy.

Connect Meta

1. Open Integrations and select Meta Ads.
2. Choose read-only or full access.
3. Select Continue to Meta.
4. Approve the requested advertising and business permissions.
5. Return to Oblive and confirm that the integration reports ready.

Oblive validates the resulting authorization against permissions and accessible ad accounts, then uses it for its backend Graph provider and private file gateway. The credential remains encrypted in the backend and is never exposed to a worker, workspace, action summary, or log. Meta currently does not return a refresh token in this flow. The observed token lifetime is approximately 60 days, but provider metadata is authoritative; reconnect when the access token expires.

After upgrading an existing installation from hosted operations, disconnect and reinstall or reconnect Meta so the integration selects the current local tool set. Catalog reconciliation drops obsolete hosted-only selections.

Direct Tool Surface

• Campaign hierarchy creation and updates, previews, errors, and activity logs.
• Curated or advanced insights, plus explicit schedule and poll tools for large reports.
• Pages, Instagram accounts and media, reusable creatives, images, and videos.
• Custom audiences and ad-set usage; member-file changes remain in the private companion.
• Typed catalogs and resources, health, event sources, and private CSV or TSV feed uploads.
• Dataset and pixel discovery, diagnostics, event configuration, and custom conversions.
• A/B and conversion-lift study reads, eligibility checks, creation, updates, and launch actions.

Nested targeting, creative, filter, catalog, and experiment inputs are structured objects. There is no arbitrary Graph URL, path, method, or unrestricted field passthrough.

Campaign and Creative Safety

• Campaigns, ad sets, and ads are created paused for review.
• Activation, budget changes, boosts, experiment launches, and destructive mutations remain separate actions under organization policy.
• Each local file becomes a separate durable action and approval.
• An invocation can include up to 20 files, 1 GB per file, and 5 GB in aggregate.
• Creative inputs are JPEG, PNG, MP4, or MOV.
• Catalog feeds are CSV or TSV and stream directly into the selected Meta product feed.
• Customer-audience JSON is capped at 50 MB and must contain only provider-ready lowercase SHA-256 identifiers. Raw customer identifiers are rejected before proposal.
• Video processing is verified through Meta before a video creative or ad is created.
• An uncertain provider outcome is never retried under a new idempotency key. Resolve it from the Human Inbox after checking Meta.

Private Files and Local Deployments

The worker uploads each file directly to the configured private object store with a short-lived, exact-key PUT grant. The backend then streams or chunks the verified object to Meta Graph. Meta never receives a Garage, CDN, localhost, or Oblive URL.

This works in the supported local stack because the worker, backend, and Garage share the Compose network. No public CDN is needed. In a split deployment, the configured S3 endpoint must be reachable from worker and backend execution networks; it does not need to be publicly reachable or reachable from Meta.

Successful and rejected actions remove their staged files. Configure a 24-hour object lifecycle for abandoned integration staging objects in production.

Troubleshooting

• Meta Ads connection is unavailable: configure metaAdsOAuth.clientId and its public redirectUri, run bun run stack env, and restart the frontend and backend.
• The deployment client is rejected: confirm Meta approved the client for this authorization flow and registered the exact META_ADS_OAUTH_REDIRECT_URI; then regenerate the environment and restart the frontend and backend.
• The integration previously used hosted tools: reconnect or reinstall it so the enabled tool set is reconciled to the direct provider.
• is_ads_mcp_enabled is false: leave metaAds.operationsProvider as graph. That flag affects Meta’s hosted rollout, not Oblive’s direct Marketing API operations.
• The credential expired: reconnect Meta. This flow currently has no refresh token.
• Meta Ads is unavailable: confirm that the integration is connected, enabled, and granted to the Growth profile.
• A change is blocked: confirm full access, task execution, and the organization approval state.
• A file is rejected: check its extension, content signature, size, and local workspace path.
• A catalog feed is rejected: use CSV or TSV, confirm the product-feed ID, and keep the file within the shared 1 GB limit.
• An audience file is rejected: confirm the JSON contains only lowercase 64-character SHA-256 values and no raw identifiers.
• A video is not ready: use Meta’s video status read later; do not run a sleeping or unbounded polling task.
• Approval or reconciliation is required: resolve the exact Human Inbox item instead of changing the idempotency key.