Facebook Marketing¶

Overview¶

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

What it does:

• Report on campaigns, ad sets and ads over a date range, or list the account's campaigns
• Pause or activate a campaign or an ad
• Send a conversion — a CRM lead or sale — back to a Meta dataset, so Meta can attribute and optimise for it

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¶

• A Facebook Marketing connection in Settings → App Connections — you sign in with Facebook and grant access; no Facebook app of your own is needed.
• The Facebook user who connects must have access to the ad accounts (and, for conversions, the datasets) you want to use. The Ad Account and Dataset lists on the task show what the connection can reach.
• Facebook can end a connection's access (a password change, a removed permission); the task then fails asking for the connection to be renewed — reconnect it in Settings → App Connections.

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/v25.0/{campaign_id}/insights (specific campaign) OR GET https://graph.facebook.com/v25.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 /v25.0/{adset_id}/insights or /v25.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 /v25.0/{ad_id}/insights or /v25.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/v25.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/v25.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/v25.0/{ad_id}?status={status}

Action 7: send_conversion¶

Send one CRM event — a lead, a qualified lead, a booking, a sale — to a Meta dataset through the Conversions API, so Meta can attribute it to your ads and optimise for it.

• Dataset is picked from the datasets your connection can use. Event is a standard event (Lead, Schedule, Purchase…) or a custom name. Where It Happened says where the event took place.
• Customer Identifiers are the details Meta matches the event on — the Meta Lead ID is the most accurate. Each is normalised and hashed before it leaves BaseCloud, and none is output. An identifier that cannot be used is skipped and named in run_text (Email address was not used: …); if nothing usable is left, the task fails without sending.
• Value and Currency (and Order / Deal ID) go with a Purchase.
• BaseCloud sets the event's ID itself: a live run uses one id per task and record, so a retry is never counted twice.
• A test event code also lists the event under Test Events in Meta Events Manager. Meta does not set it aside: the event is still recorded on the dataset and counted like any other. Test Events lists by channel: an event sent as In the CRM only appears there with the channel set to CRM, not the default Website.

Outputs: event_name, event_id, event_time, dataset_id, matched_keys (which identifiers Meta received), events_received (Meta's count) and fbtrace_id.

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 a Facebook Marketing connection and sign in with Facebook
3. Grant the access Facebook asks for, then pick the connection on the task

Error: "Invalid OAuth 2.0 Access Token"¶

Cause: Facebook ended the connection's access

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

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. BaseCloud already backs off and retries a rate-limited call by itself
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. BaseCloud already backs off and retries a rate-limited call by itself

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
• Service: facebookService.js (1086 lines)
• API Version: Graph API v25.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/v25.0/
• Documentation: https://developers.facebook.com/docs/marketing-api