Skip to main content

​
Overview

Connecting Meta Ads lets the dashboard:
  • Create, update, pause, resume, and remove campaigns, ad sets, and ads.
  • Upload creative assets (image, video, carousel) into the connected ad account.
  • Pull spend, impressions, clicks, conversions, and conversion value via the Insights API.
  • Run native creative experiments via Meta’s A/B Split Test feature.
  • Receive realtime ad-disapproval and account-status events via webhooks.
The integration uses the Graph API v19.0 with OAuth 2.0 authentication.

​
Prerequisites

Before connecting, make sure you have:
  1. A Meta Ads account in good standing.
  2. Admin role on the Meta Business account that owns the ad account.
  3. (Optional) A Meta Pixel or Conversions API source if you want conversion-based optimization.

​
OAuth scopes

The connection requests: 
ads_management
ads_read
business_management
read_insights

​
Connect

  1. Open the Paid UA → Integrations page in the dashboard.
  2. Click Connect on the Meta Ads tile.
  3. Sign in with the Facebook account that has access to your Business Manager.
  4. Approve the requested scopes.
  5. Pick the ad account to use.
The dashboard exchanges the short-lived user token for a long-lived token (60-day expiry); a background cron rotates it before expiry, so you don’t need to reconnect manually unless the user revokes scope.

​
What lives on the platform vs the dashboard

Lives on MetaLives on the dashboard
Campaign / ad-set / ad idsSpend caps + agent-control matrix
Creative libraryVendor-neutral creative briefs
Audience configurationsIdempotency keys + retry attempts
Insights (spend / impressions / clicks)Daily roll-ups in ua_daily_metrics

​
Webhooks

Meta posts ad-status, account-status, and disapproval events to: 
POST /api/v1/integrations/webhooks/meta
Signature: X-Hub-Signature-256 HMAC-SHA256 over the raw body, keyed by the platform-side META_WEBHOOK_SIGNING_KEY_CURRENT secret. The META_WEBHOOK_SIGNING_KEY_PREVIOUS secret is also accepted during a 7-day rotation window.

​
Disconnect

Disconnecting revokes the dashboard’s stored OAuth token and stops all background syncs. Campaigns created via the dashboard remain on the platform — disconnect does not pause or delete them.

​
Limits

  • Token rotation: long-lived token, rotated before expiry by the hourly token-refresh cron.
  • Rate limits: per-ad-account token bucket; 429s back off via the Retry-After header.
  • Creative size: image up to 8 MB, video up to 4 GB; format-specific limits enforced server-side before upload.