Facebook (Meta) Integration

The Facebook integration provides comprehensive access to the Facebook Marketing API, enabling ad account management, campaign operations, lead generation, and detailed analytics reporting.

Overview

The Facebook integration supports three distinct use cases through a multi-source architecture:

Integration Sources

Source	Purpose	OAuth Scopes	Collections
meta-ads	Campaign management & analytics	ads_management, ads_read, business_management, read_insights	integrations.facebookads.key, analytics-facebook.ads.userconfig
facebook-leads	Lead generation with Facebook Lead Ads	leads_retrieval, pages_read_engagement, pages_manage_ads	integrations.facebookads.key, campaign-data, facebook-webhooks
reputation	Page management for reviews	pages_show_list, pages_manage_metadata, pages_read_user_content	integrations.facebookads.key

Key Capabilities

• OAuth 2.0 Authentication: Long-lived access tokens (60 days)
• Ad Account Management: Business Manager and Ad Account hierarchy
• Campaign Operations: Full CRUD for Campaigns, Ad Sets, and Ads
• Lead Generation: Webhook-based lead capture from Facebook Lead Ads
• Analytics & Insights: Comprehensive performance metrics with breakdowns
• Token Management: Automatic refresh and invalidation handling
• Multi-Tenant Support: Sub-account integration management

Architecture

Resource Hierarchy

Business Manager (optional)
  └── Ad Accounts
       └── Campaigns
            └── Ad Sets
                 └── Ads

API Versioning

The integration uses Facebook Graph API with configurable version (FACEBOOK_API_VERSION):

// Current: v18.0 (configurable via environment)
const baseURL = `https://graph.facebook.com/${process.env.FACEBOOK_API_VERSION}`;

Multi-Source Token Management

Each source type gets its own separate token for the same account:

graph TB
    A[Account] --> B[meta-ads token]
    A --> C[facebook-leads token]
    A --> D[reputation token]

    B --> E[Analytics Dashboard]
    C --> F[Lead Campaign Webhooks]
    D --> G[Review Management]

OAuth 2.0 Flow

Required OAuth Scopes

const scopes = [
  'public_profile',
  'ads_management', // Create/edit campaigns
  'ads_read', // Read campaign data
  'pages_show_list', // List Facebook Pages
  'pages_manage_ads', // Manage page ads
  'pages_manage_metadata', // Page settings
  'business_management', // Business Manager access
  'leads_retrieval', // Lead Ads data
  'pages_read_engagement', // Page engagement metrics
  'read_insights', // Ad performance data
  'pages_read_user_content', // Page content
  'pages_manage_engagement', // Manage page interactions
];

Authentication Endpoints

Endpoint	Method	Purpose
/v1/e/facebook/auth/login	GET	Initiate OAuth flow
/v1/e/facebook/auth/callback	GET	Handle OAuth callback
/v1/e/facebook/auth/delete	DELETE	Disconnect integration

Long-Lived Token Exchange

Facebook provides short-lived tokens (1 hour) initially. The integration automatically exchanges for long-lived tokens (60 days):

// Short-lived token from OAuth callback
const shortToken = result.data.access_token;

// Exchange for long-lived token
const longURL =
  `https://graph.facebook.com/${version}/oauth/access_token?` +
  `grant_type=fb_exchange_token&` +
  `client_id=${CLIENT_ID}&` +
  `client_secret=${CLIENT_SECRET}&` +
  `fb_exchange_token=${shortToken}`;

// Result: 60-day token stored in database

Data Collections

integrations.facebookads.key

Stores OAuth tokens with source-specific isolation:

{
    account_id: ObjectId,      // DashClicks account
    created_by: ObjectId,      // User who connected
    source: String,            // 'meta-ads' | 'facebook-leads' | 'reputation'
    token: {
        access_token: String,  // Long-lived token
        token_type: 'bearer',
        expires_in: Number     // Unix timestamp (not seconds from now)
    },
    token_invalidated: Boolean, // Set true on OAuth errors
    deleted: Date              // Soft delete timestamp
}

analytics-facebook.ads.userconfig

User preferences for analytics dashboard:

{
    account_id: ObjectId,
    ad_accountid: String      // Selected Facebook Ad Account ID (act_XXXXX)
}

facebook-webhooks

Webhook registrations for lead generation:

{
    account_id: ObjectId,
    owner: ObjectId,
    webhook_url: String       // Callback URL for lead events
}

Common Query Parameters

Date Filtering

// Used by insights endpoints
{
    since: '2024-01-01',      // Start date (YYYY-MM-DD)
    until: '2024-01-31'       // End date (YYYY-MM-DD)
}

// Automatically converted to Facebook time_range format:
{
    time_range: {
        since: '2024-01-01',
        until: '2024-01-31'
    }
}

Pagination

{
    limit: 25,                // Results per page (default: 25)
    after: 'cursor_string'    // Pagination cursor from previous response
}

Sorting

{
    sort: 'impressions',      // Field to sort by
    order: 'descending'       // 'ascending' | 'descending'
}

// Converted to: sort: ['impressions_descending']

Filtering

// Campaign IDs
{
    campaignids: '123,456,789'  // Comma-separated IDs
}

// Ad Set IDs
{
    adsetids: '111,222,333'
}

// Ad IDs
{
    adids: '777,888,999'
}

// Status filtering
{
    campaignstatus: 'ACTIVE,PAUSED',    // Campaign effective_status
    adsetstatus: 'ACTIVE,PAUSED',       // Ad Set effective_status
    adstatus: 'ACTIVE,PAUSED'           // Ad effective_status
}

Metrics & Fields

Campaign-Level Metrics

Available through insights API:

const campaignMetrics = [
  // Performance
  'impressions',
  'reach',
  'frequency',

  // Engagement
  'clicks',
  'ctr', // Click-through rate
  'cpc', // Cost per click
  'cpp', // Cost per 1000 impressions

  // Conversions
  'actions', // Array of action types
  'conversions',
  'cost_per_action_type',

  // Spend
  'spend',
  'cost_per_result',

  // Video
  'video_play_actions',
  'video_avg_time_watched_actions',

  // Quality
  'quality_ranking',
  'engagement_rate_ranking',
  'conversion_rate_ranking',
];

Ad Set Metrics

const adSetMetrics = [
  'campaign_id', // Parent campaign
  'optimization_goal', // e.g., 'OFFSITE_CONVERSIONS'
  'bid_strategy', // 'LOWEST_COST_WITHOUT_CAP', etc.
  'daily_budget',
  'lifetime_budget',
  'targeting', // JSON object with audience criteria
  ...campaignMetrics, // Plus all campaign metrics
];

Ad-Level Metrics

const adMetrics = [
  'adset_id', // Parent ad set
  'creative', // Ad creative details
  'effective_status', // Current ad status
  ...adSetMetrics, // Plus all ad set metrics
];

Status Values

Campaign/Ad Set/Ad Statuses

// effective_status (computed status considering parent and schedule)
const effectiveStatuses = [
  'ACTIVE', // Running
  'PAUSED', // Manually paused
  'DELETED', // Soft deleted
  'ARCHIVED', // Archived
  'IN_PROCESS', // Being created
  'WITH_ISSUES', // Has errors/warnings
];

// configured_status (user-set status)
const configuredStatuses = ['ACTIVE', 'PAUSED', 'DELETED'];

Error Handling

OAuth Error Detection

The integration automatically detects and handles token invalidation:

// Error codes that trigger token_invalidated flag:
const OAuthErrorCodes = [
  100, // Invalid parameter
  102, // Session expired
  190, // Access token expired/invalid
  200 - 299, // Various permission errors
];

// On OAuthException with these codes:
await faceBookAdsKey.updateMany({ account_id: accountId }, { $set: { token_invalidated: true } });

Error Response Structure

{
    success: false,
    errno: 400,
    message: 'TOKEN_INVALIDATED', // or other error message
    additional_info: 'Original API error message'
}

Environment Configuration

Required Variables

# OAuth Credentials
FACEBOOK_CLIENT_ID=your_app_id
FACEBOOK_CLIENT_SECRET=your_app_secret
FACEBOOK_API_VERSION=v18.0

# OAuth Redirect
FACEBOOK_ADS_REDIRECT_URL=https://api.dashclicks.com/v1/e/facebook/auth/callback

# Webhooks (Lead Generation)
FACEBOOK_ADS_WEBHOOK_URL=https://api.dashclicks.com/webhooks/facebook/leads
FACEBOOK_VERIFY_TOKEN=your_webhook_verification_token

# JWT for state parameter
APP_SECRET=your_jwt_secret

Integration Checklist

Initial Setup

• Create Facebook App in Meta for Developers
• Configure OAuth redirect URI
• Add required permissions (scopes)
• Set up webhook endpoint (if using lead generation)
• Configure environment variables
• Test OAuth flow in sandbox

Production Deployment

• Submit app for review (required permissions)
• Enable Business Manager integration
• Configure webhook subscriptions
• Set up token refresh monitoring
• Implement error alerting for token invalidation
• Test multi-source isolation
• Verify sub-account support

Monitoring

• Track OAuth error rates
• Monitor token expiration
• Alert on webhook failures
• Log API rate limits
• Measure integration disconnection rate

Rate Limits

Facebook enforces rate limits based on:

1. App-level rate limits: Varies by app usage tier
2. User-level rate limits: 200 calls per hour per user per app
3. Ad Account-level rate limits: Based on ad spend

The integration does not implement automatic rate limit handling. Consider implementing:

• Exponential backoff on 429 errors
• Request queuing for bulk operations
• Rate limit header monitoring (X-App-Usage, X-Business-Use-Case-Usage)

Testing

Development Mode

Facebook provides test ad accounts and users for development:

1. Create test ad account in Business Manager
2. Use test users for OAuth flow
3. Test campaigns won't spend real money
4. Limited to test data in insights

Webhook Testing

Use fbwebhook tool for local webhook testing:

npm install -g fbwebhook
fbwebhook 3000

Related Documentation

• Authentication Flow - Complete OAuth implementation
• Accounts & Pages - Ad Accounts and Facebook Pages management
• Campaigns - Campaign, Ad Set, and Ad operations
• Analytics & Insights - Performance metrics and reporting
• Lead Generation - Webhook-based lead capture
• Breakdowns - Advanced analytics with dimension breakdowns

Additional Resources

• Facebook Marketing API Documentation
• Facebook Graph API Explorer
• Meta Business Help Center
• Webhooks Documentation