Facebook Marketing¶

Overview¶

The Facebook Marketing task integrates BaseCloud CRM with Facebook Marketing API v18.0, enabling automated campaign management, performance reporting, and ad optimization across Facebook and Instagram.

Key Features:

• 6 Actions: Campaign/ad set/ad performance, campaign list, status updates
• OAuth 2.0 Authentication: Secure Facebook integration with long-lived tokens
• Multi-Level Reporting: Campaign, ad set, and individual ad metrics
• Status Management: Pause, activate, or archive campaigns and ads
• Flexible Date Ranges: 15+ preset ranges plus custom date selection
• Instagram Support: Unified reporting for Facebook and Instagram ads

Use Cases:

• Automated daily performance reporting
• Campaign budget monitoring
• Ad performance optimization
• Multi-account agency management
• A/B testing analysis
• ROI tracking and alerts

Prerequisites¶

1. Facebook Business Manager¶

Setup Business Manager:

1. Go to https://business.facebook.com
2. Create or access Business Manager account
3. Add Ad Accounts under Business Settings
4. Verify business (required for production API access)
5. Ensure you have Admin or Advertiser role

2. Facebook App¶

Create Facebook App:

1. Go to https://developers.facebook.com
2. Click My Apps → Create App
3. Select Business app type
4. Enter app details and create
5. Add Marketing API product
6. Configure OAuth redirect URI:
7. https://yourapp.basecloudglobal.com/oauth/callback
8. Note App ID and App Secret

3. Ad Account Access¶

Get Ad Account ID:

1. Open Facebook Ads Manager
2. Click account dropdown (top left)
3. Copy Ad Account ID (format: act_123456789)
4. Or from URL: https://business.facebook.com/adsmanager/manage/accounts?act=123456789

Account ID Format:

• Displayed: 123456789
• API format: act_123456789 (auto-prefixed by BaseCloud)

4. OAuth Configuration in BaseCloud¶

Create App Connection:

1. Navigate to BaseCloud CRM → Settings → App Connections
2. Click + New App Connection
3. Select Facebook Marketing from dropdown
4. Enter credentials:
5. App ID: From Facebook App Dashboard
6. App Secret: From Facebook App Dashboard
7. Click Authorize with Facebook
8. Authorize permissions:
9. pages_show_list - List pages
10. pages_read_engagement - Read page data
11. ads_read - Read ad data
12. ads_management - Manage ads (for status updates)
13. read_insights - Access performance metrics
14. Select ad accounts to access
15. Save connection

OAuth Scopes Required:

pages_show_list,pages_read_engagement,ads_read,ads_management,read_insights

Long-Lived Tokens:

Facebook access tokens expire after 60 days. BaseCloud uses long-lived tokens but doesn't auto-refresh. Re-authorize periodically.

Connections live in Settings → App Connections, not on the task. Connect the app once and every task that needs it can use it. The badge on each tile says how it authenticates — OAuth2 sends you to the provider to sign in, API Key expects a key you paste in.

Outputs¶

Which fields appear depends on the action.

Reference fields as {{task_<ID>_<field>}}.

Always emitted¶

Configuration¶

Builder fields¶

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Action 1: get_campaign_performance¶

Retrieve campaign-level advertising performance metrics.

Date Range Presets:

Available Metrics:

Basic Performance:

• impressions - Ad impressions
• clicks - Link clicks
• reach - Unique people reached
• frequency - Average impressions per person

Cost Metrics:

• spend - Amount spent
• cpc - Cost per click
• cpm - Cost per 1000 impressions
• cpp - Cost per person reached
• ctr - Click-through rate
• unique_clicks - Unique link clicks
• unique_ctr - Unique CTR

Conversions:

• All standard Facebook conversion events
• Custom conversion events
• Purchase events
• Lead events

Engagement:

• Post engagement metrics
• Video views
• Page likes
• Event responses

Output Variables:

task_57001_run; // true/false
task_57001_run_text; // "get_campaign_performance completed successfully."
task_57001_action; // "get_campaign_performance"
task_57001_campaigns; // Array of campaign objects
task_57001_count; // Number of campaigns
task_57001_date_range; // Date range used
task_57001_metrics; // Array of metrics requested
task_57001_data; // Raw API response

Campaign Object Structure:

{
  campaign_id: "23850123456789",
  campaign_name: "Summer Sale 2024",
  impressions: "125000",
  clicks: "4500",
  spend: "1250.50",
  reach: "85000",
  ctr: "3.6",
  cpc: "0.28",
  cpm: "10.00"
}

How It Works:

1. Validates OAuth connection and ad account access
2. Auto-formats account ID with act_ prefix if missing
3. Converts date_range to Facebook API format (last_7_days → last_7d)
4. Parses metrics (accepts JSON array or CSV string)
5. Calls: GET https://graph.facebook.com/v18.0/{campaign_id}/insights (specific campaign) OR GET https://graph.facebook.com/v18.0/{ad_account_id}/insights?level=campaign (all campaigns)
6. Returns campaigns array with requested metrics

Action 2: get_adset_performance¶

Retrieve ad set level performance metrics.

Output Variables:

task_57001_run; // true/false
task_57001_run_text; // "get_adset_performance completed successfully."
task_57001_action; // "get_adset_performance"
task_57001_adsets; // Array of ad set objects
task_57001_count; // Number of ad sets

Ad Set Object Structure:

{
  adset_id: "23850234567890",
  adset_name: "Summer Sale - Mobile 25-34",
  campaign_id: "23850123456789",
  impressions: "45000",
  clicks: "1500",
  spend: "420.30",
  ctr: "3.33"
}

How It Works:

Similar to campaign performance but queries at ad set level:

• API: GET /v18.0/{adset_id}/insights or /v18.0/{ad_account_id}/insights?level=adset
• Can filter by campaign_id to get ad sets for specific campaign
• Returns adsets array with metrics

Action 3: get_ad_performance¶

Retrieve individual ad performance metrics.

Output Variables:

task_57001_run; // true/false
task_57001_run_text; // "get_ad_performance completed successfully."
task_57001_action; // "get_ad_performance"
task_57001_ads; // Array of ad objects
task_57001_count; // Number of ads

Ad Object Structure:

{
  ad_id: "23850345678901",
  ad_name: "Summer Sale - Image 1",
  adset_id: "23850234567890",
  campaign_id: "23850123456789",
  impressions: "15000",
  clicks: "540",
  spend: "150.10",
  ctr: "3.6"
}

How It Works:

Similar to campaign/ad set but at individual ad level:

• API: GET /v18.0/{ad_id}/insights or /v18.0/{ad_account_id}/insights?level=ad
• Can filter by adset_id or campaign_id
• Returns ads array with creative performance

Action 4: get_campaign_list¶

Retrieve list of campaigns without performance metrics (faster).

Output Variables:

task_57001_run; // true/false
task_57001_run_text; // "get_campaign_list completed successfully."
task_57001_action; // "get_campaign_list"
task_57001_campaigns; // Array of campaign objects
task_57001_count; // Number of campaigns

Campaign Object Structure (List):

{
  id: "23850123456789",
  name: "Summer Sale 2024",
  status: "ACTIVE",
  effective_status: "ACTIVE",
  objective: "CONVERSIONS",
  daily_budget: "10000",  // In cents
  lifetime_budget: null,
  created_time: "2024-01-15T10:30:00+0000",
  updated_time: "2024-02-01T14:20:00+0000"
}

API Endpoint:

GET https://graph.facebook.com/v18.0/{ad_account_id}/campaigns?fields=id,name,status,effective_status,objective,daily_budget,lifetime_budget,created_time,updated_time

How It Works:

1. Queries campaigns endpoint (not insights)
2. Returns campaign metadata without metrics
3. Much faster than get_campaign_performance
4. Use for dropdown population or status checks

Action 5: update_campaign_status¶

Change campaign status (pause, activate, archive, delete).

Status Values:

• ACTIVE - Campaign running
• PAUSED - Campaign paused (can reactivate)
• DELETED - Soft delete (can restore via UI)
• ARCHIVED - Archived (for historical data)

Output Variables:

task_57001_run; // true/false
task_57001_run_text; // "update_campaign_status completed successfully."
task_57001_action; // "update_campaign_status"
task_57001_success; // true/false
task_57001_campaign_id; // Campaign ID updated
task_57001_status; // New status
task_57001_data; // API response

API Endpoint:

POST https://graph.facebook.com/v18.0/{campaign_id}?status={status}

How It Works:

1. Validates status value
2. Sends POST request with new status
3. Returns success confirmation
4. Campaign changes take effect immediately

Action 6: update_ad_status¶

Change individual ad status.

Output Variables:

task_57001_run; // true/false
task_57001_run_text; // "update_ad_status completed successfully."
task_57001_action; // "update_ad_status"
task_57001_success; // true/false
task_57001_ad_id; // Ad ID updated
task_57001_status; // New status

API Endpoint:

POST https://graph.facebook.com/v18.0/{ad_id}?status={status}

Real-World Examples¶

Report campaign performance weekly¶

Schedule  (weekly)
  └─ Facebook Marketing   pull campaign metrics
      └─ Email            send the summary

Keep a running record in a sheet¶

Schedule
  └─ Facebook Marketing   pull metrics
      └─ Google Sheets    append_row

Using a sheet keeps the history somewhere a non-technical reader can open.

Act on a lead the moment it arrives¶

Facebook Lead Ads Trigger
  └─ Match to Client   contact_email: {{task_56001_fields_email}}
      └─ Email         send the follow-up

Troubleshooting¶

Error: "No app connection selected"¶

Cause: OAuth connection not configured

Solutions:

1. Go to Settings → App Connections
2. Create Facebook Marketing connection
3. Enter App ID and App Secret
4. Complete OAuth authorization
5. Grant all required permissions

Error: "Invalid OAuth 2.0 Access Token"¶

Cause: Access token expired (60-day lifetime)

Solutions:

1. Re-authorize app connection:
2. Settings → App Connections → Edit
3. Click Re-authorize with Facebook
4. Grant permissions again
5. Long-lived tokens last 60 days (no auto-refresh)
6. Set reminder to re-authorize quarterly

Error: "Ad account not found" or Permission Denied¶

Cause: No access to specified ad account

Solutions:

1. Verify ad account ID format: 123456789 or act_123456789
2. Check Facebook Business Manager:
3. Business Settings → Accounts → Ad Accounts
4. Verify you have Admin or Advertiser role
5. Ensure ad account linked to Business Manager
6. Re-authorize OAuth with correct account selection

Metrics List Empty or Invalid¶

Cause: Metrics field format incorrect

Solutions:

1. Accepts JSON array: ["impressions","clicks","spend"]
2. Or CSV string: impressions,clicks,spend
3. Remove spaces around commas
4. Use valid metric names (see Available Metrics)
5. Default used if omitted: impressions,clicks,spend,reach,ctr,cpc,cpm

Date Range Returns No Data¶

Cause: No data for specified range or invalid format

Solutions:

1. Check campaigns ran during date range
2. Use valid preset: last_7_days, yesterday, etc.
3. For custom range, provide both start_date and end_date
4. Date format: YYYY-MM-DD
5. Recent data may take 24-48 hours to appear

Campaign/Ad Status Update Failed¶

Cause: Invalid status value or permission issue

Solutions:

1. Use valid status: ACTIVE, PAUSED, DELETED, ARCHIVED
2. Ensure ads_management scope authorized
3. Verify you have edit permissions on ad account
4. Cannot change status of deleted campaigns
5. Check campaign isn't in Facebook review

Rate Limiting / API Throttling¶

Cause: Exceeded Facebook API rate limits

Solutions:

1. Rate Limits:
2. 200 calls/hour per user

3. 200 calls/hour per app-user pair

4. Immediate Actions:

5. Add delays in multi-account loops (2-5 seconds)
6. Reduce frequency of metric fetches

7. Cache results when possible

8. Long-term:

9. Spread large queries over time
10. Use get_campaign_list instead of performance for lists
11. Implement exponential backoff
12. Apply for higher rate limits (requires verification)

Empty Campaigns/Ads Array¶

Cause: No data matches filters

Solutions:

1. Remove status filter (may be filtering all)
2. Check date range has data
3. Verify correct ad account ID
4. Increase limit parameter
5. Confirm campaigns exist in Facebook Ads Manager

Best Practices¶

Authentication Management¶

1. Long-Lived Tokens:
2. Facebook tokens expire after 60 days
3. Set calendar reminders to re-authorize
4. Monitor connection status in BaseCloud

5. Re-authorize before expiration

6. Permissions:

7. Grant all required scopes during authorization
8. ads_management needed for status updates
9. read_insights required for performance data

10. Review requested permissions before accepting

11. Multi-Account:

12. Create separate connections per ad account
13. Or use one connection with multiple account access
14. Store connection IDs in client records for dynamic selection

Metrics Strategy¶

1. Metric Selection:
2. Request only needed metrics to reduce API calls
3. Use default metrics for general reporting
4. Add conversion metrics for ROI tracking

5. Include engagement for brand campaigns

6. Date Ranges:

7. Use presets when possible (standardized)
8. yesterday for daily reports (data complete)
9. last_7_days for weekly trends
10. last_30_days for monthly reviews

11. Be aware 24-48 hour data lag for some metrics

12. Performance Tiers:

13. Campaign-level for executive summaries
14. Ad set-level for audience analysis
15. Ad-level for creative optimization
16. Use get_campaign_list for faster metadata only

Reporting Strategy¶

1. Automated Reports:
2. Daily: Yesterday's performance summary
3. Weekly: 7-day trends and insights
4. Monthly: Full campaign analysis

5. Real-time: Budget alerts and thresholds

6. Data Storage:

7. Append metrics to a sheet with Google Sheets for historical trends
8. Create time-series for visualization
9. Archive raw responses for auditing

10. Maintain client-level reporting tables

11. Stakeholder Communication:

12. Executives: High-level KPIs (ROAS, conversions)
13. Marketing: Detailed campaign breakdowns
14. Finance: Spend tracking and budget adherence
15. Clients: Campaign-specific results and insights

Campaign Management¶

1. Status Updates:
2. Always validate before pausing campaigns
3. Include reason in workflow notes
4. Log status changes to database

5. Alert relevant teams

6. Optimization:

7. Set minimum data thresholds (1000+ impressions)
8. Use multiple metrics for decisions (CTR + CPC)
9. Implement gradual changes (test before scaling)

10. Monitor after automation runs

11. Error Handling:

12. Wrap critical updates in If Conditions
13. Log failures for troubleshooting
14. Provide manual override workflows
15. Alert admins on persistent issues

Performance Optimization¶

1. Caching:
2. Cache campaign lists (reload hourly)
3. Store account structure (reload daily)
4. Cache metric results for dashboards

5. Reduce redundant API calls

6. Rate Limiting:

7. Add 2-3 second delays in loops
8. Batch operations where possible
9. Schedule large queries off-peak

10. Implement exponential backoff

11. Efficiency:

12. Use get_campaign_list for dropdowns (faster)
13. Filter by status to reduce dataset
14. Set appropriate limits (don't fetch all)
15. Query specific campaigns when possible

FAQ¶

Q: What's the difference between Facebook Marketing and Facebook Lead Ads?

A:

• Facebook Marketing: Campaign management and performance reporting
• Facebook Lead Ads: Lead capture from Lead Ads campaigns
• Different use cases: Marketing for optimization, Lead Ads for lead generation

Q: Can I create new campaigns via API?

A: This task focuses on reporting and status management. Campaign creation requires additional actions not currently implemented. Use Facebook Ads Manager for creation.

Q: How accurate is the performance data?

A: Data matches Facebook Ads Manager but may have 24-48 hour lag for some metrics. Use yesterday for fully complete data.

Q: Can I manage Instagram ads?

A: Yes, Instagram ads managed through Facebook Ads Manager appear in same API. No separate configuration needed.

Q: What happens when token expires?

A: API calls fail with "Invalid OAuth token" error. Re-authorize connection in BaseCloud. Set 60-day reminder.

Q: Can I get data older than 90 days?

A: Yes, use custom date range or maximum preset. Historical data available based on account age.

Q: How do I track specific conversion events?

A: Include conversion event names in metrics field. Example: purchase,lead,add_to_cart. Must be configured in Facebook Events Manager.

Q: Can I manage multiple ad accounts?

A: Yes, create separate app connections per account or grant one connection access to multiple accounts. Use account selector in task.

Q: What's the difference between status and effective_status?

A:

• status: Status you set (ACTIVE, PAUSED)
• effective_status: Actual status including Facebook's decision (may be CAMPAIGN_PAUSED due to budget)

Q: Can I pause ads based on performance automatically?

A: Yes, use Example 3 workflow. Set appropriate thresholds (minimum impressions, CTR, spend) to avoid premature decisions.

Q: How do I calculate ROAS?

A: ROAS = Conversion Value / Spend. Get conversion value with purchase_roas metric or calculate: (conversions × average_order_value) / spend

Q: Can I export data to Google Sheets?

A: Yes, use Google Sheets task after getting metrics. Store in variables and write to sheets.

Related Tasks¶

• Google Ads - Google advertising analytics
• Google Sheets - Export metrics to spreadsheets
• Loop - Process multiple accounts/campaigns
• If Statement - Performance-based logic
• Email - Send performance reports
• Variable - Calculate custom metrics

Technical Details¶

• Type ID: 57
• Function: taskFacebookMarketing() in automationService.js (lines 10049-10097)
• Service: facebookService.js (1086 lines)
• API Version: Facebook Marketing API v18.0
• Authentication: OAuth 2.0 (60-day tokens, no auto-refresh)
• Scopes: pages_show_list,pages_read_engagement,ads_read,ads_management,read_insights
• Output Prefix: task_57001_*
• Rate Limits: 200 calls/hour per user/app-user pair
• Base URL: https://graph.facebook.com/v18.0/
• Documentation: https://developers.facebook.com/docs/marketing-api