Meta Ads Integration

Location: Advertising > Integrations > Meta

What It Does

The Meta Ads integration connects ILLIXIS to Meta's Marketing API, allowing you to sync retargeting audiences as Custom Audiences, create ad campaigns, and generate AI-written ad copy -- all without leaving the platform. Ads run across Facebook, Instagram, Messenger, and the Meta Audience Network.

ILLIXIS handles the full ad creation pipeline: Campaign, Ad Set, and Ad. Everything is created in a PAUSED state so you can review the ad in Meta Ads Manager, set your budget, and activate it when ready. The integration also syncs your ILLIXIS topic-based audiences to Meta as Custom Audiences built on your Meta Pixel data, so you can retarget readers of specific content clusters.

Because Meta uses long-lived tokens that expire after 60 days and cannot be auto-refreshed, you will need to re-authorize the connection roughly every two months. ILLIXIS warns you 7 days before expiry.

Prerequisites

| Requirement | Where to Get It | Why It's Needed |
|-------------|-----------------|-----------------|
| Meta Business account | business.facebook.com | Required for ads management access |
| Ad Account (act_123456789) | Business Settings > Ad Accounts | Container for campaigns, ad sets, and ads |
| Meta Pixel installed on your website | Events Manager > Data Sources | Tracks website visitors for Custom Audience creation |
| Facebook Page | Your Page settings | Every ad must be associated with a Page |

If you use Meta Business Manager, ensure your ad account is listed under Business Settings > Ad Accounts. Both personal ad accounts and Business Manager accounts are supported -- ILLIXIS fetches all accounts accessible by your token during setup.

Connecting Your Account

1. Go to Settings > Integrations and find the Meta section (under Advertising).
2. Click Connect Meta.
3. You are redirected to Facebook. Sign in if prompted.
4. Facebook shows a consent screen requesting these permissions:

• ads_management -- create and manage Custom Audiences and ads
• ads_read -- read audience and campaign data
• business_management -- access Business Manager resources

5. Click Continue to authorize.
6. ILLIXIS exchanges the authorization code for a long-lived token (valid ~60 days).
7. You are redirected to the Account Selection page.
8. Select your Ad Account from the dropdown. If your account does not appear, enter the Ad Account ID manually (format: act_123456789).
9. ILLIXIS automatically detects Meta Pixels associated with the selected ad account and assigns the first one. If you have multiple Pixels, verify the correct one was selected.
10. Click Save. The connection is now active.

After connecting, ILLIXIS also fetches your Facebook Pages and stores the first available page for ad creative purposes. If you manage multiple Pages, you can update the linked Page in the connection settings.

Syncing Audiences

ILLIXIS creates Custom Audiences in Meta from your existing retargeting audiences. These are website-traffic audiences built using your Meta Pixel, matching URL patterns that correspond to your content topics.

How Audience Sync Works

1. ILLIXIS analyzes your content clusters and builds URL-pattern rules (e.g., pages containing "sustainable" or "eco-friendly" in the path).
2. These rules are sent to Meta's Custom Audience API as website traffic rules attached to your Pixel.
3. Meta populates the audience with visitors matching those URL patterns over the retention window (default: 30 days, maximum: 180 days).
4. The audience is marked as "synced" in ILLIXIS with a meta_audience_id.

Triggering a Sync

Automatic: When you run a full audience sync from the Advertising dashboard, ILLIXIS creates GA4-based audiences first, then syncs them to Meta 30 seconds later (if Meta is connected and a Pixel is configured).

Manual (all audiences): Go to Advertising and click Sync to Meta. This pushes all unsynced audiences to Meta.

Manual (single audience): On any audience detail page, click Sync to Meta to push just that audience.

Audience Statuses

| Status | Meaning |
|--------|---------|
| Not Synced | Audience exists in ILLIXIS only; not yet pushed to Meta |
| Syncing | Sync in progress (background task running) |
| Synced | Live in Meta Ads Manager as a Custom Audience |
| Error | Sync failed; check error message for details |

Creating Ads

Once an audience is synced to Meta, you can create a full ad directly from ILLIXIS.

Step 1: Open the Ad Creator

On the audience detail page, click Create Meta Ad. ILLIXIS loads:

• A preview image (pulled from the first content item in the cluster that has a featured image)
• AI-generated ad copy (headline and primary text)
• A CTA selector
• A destination URL field

Step 2: Review and Edit Ad Copy

ILLIXIS generates ad copy using AI, tailored to the audience's content topics and your brand voice. You can:

• Edit the headline and primary text directly
• Regenerate the copy by clicking the regenerate button (calls AI again with fresh output)
• Save as draft to come back later without pushing to Meta

Character limits enforced by the system:

| Field | Maximum Length | Ideal Length |
|-------|---------------|--------------|
| Headline | 50 characters | 27 characters |
| Primary Text | 250 characters | 125 characters |

Step 3: Select a CTA

Choose the call-to-action button for your ad:

| CTA Value | Button Text | Best For |
|-----------|-------------|----------|
| LEARN_MORE | Learn More | Educational content, blog posts |
| SHOP_NOW | Shop Now | Product pages, e-commerce |
| SIGN_UP | Sign Up | Lead generation, email capture |
| CONTACT_US | Contact Us | Service businesses, consultations |
| GET_QUOTE | Get Quote | Custom pricing, B2B |

Step 4: Set Destination URL

Enter the URL where users land after clicking your ad. If left blank, ILLIXIS uses your tenant homepage. The URL must be set before the ad can be created.

Step 5: Push to Meta

Click Create Ad. ILLIXIS creates the following objects in your Meta Ad Account, all in PAUSED state:

1. Campaign -- named [ILLIXIS] {Audience Name} - {Date}, objective: OUTCOME_TRAFFIC
2. Ad Set -- named [ILLIXIS] {Audience Name} Ad Set, targeting the synced Custom Audience, default $10/day budget, optimized for link clicks, bid strategy: lowest cost
3. Ad Creative -- your image, headline, primary text, and CTA linked to your Facebook Page
4. Ad -- named [ILLIXIS] {Audience Name} Ad, linking the creative to the ad set

After creation, ILLIXIS stores the campaign ID, ad set ID, and ad ID on the audience record. You get a direct link to Meta Ads Manager to review, adjust budget, and activate.

Ad Draft System

You do not have to create the ad immediately. The draft system lets you:

• Save headline, primary text, CTA, and destination URL as a draft
• Return later to the same audience and your draft is preserved
• Regenerate copy without losing your draft (use the regenerate button)
• Push the draft to Meta when ready

Ad Formats and Campaign Types

Campaign Objectives

ILLIXIS supports these Meta campaign objectives:

| Objective | API Value | Use Case |
|-----------|-----------|----------|
| Traffic | OUTCOME_TRAFFIC | Drive website visits (default for retargeting) |
| Awareness | OUTCOME_AWARENESS | Brand awareness for prospecting campaigns |
| Engagement | OUTCOME_ENGAGEMENT | Post engagement, video views |
| Sales | OUTCOME_SALES | Purchase conversions (requires conversion tracking) |
| Leads | OUTCOME_LEADS | Lead form submissions |

Retargeting ads default to OUTCOME_TRAFFIC. Prospecting campaigns can use any objective.

Prospecting Campaigns

Beyond retargeting, ILLIXIS can create prospecting campaigns that target new audiences:

• Interest targeting -- target people by interests and behaviors (e.g., "Fitness Enthusiasts," "Online Shoppers")
• Lookalike audiences -- find people similar to your existing Custom Audience (1-10% similarity range)
• Demographic targeting -- filter by age (18-65), gender, and location
• Advantage+ Audience -- enable Meta's AI to expand targeting beyond your specifications

Use the interest search feature to find targetable interests by keyword. ILLIXIS returns matching interests with estimated audience sizes.

Ad Formats

The default ad format created by ILLIXIS is a single-image feed ad (works on Facebook Feed, Instagram Feed, and Stories). The ad creative uses:

• Image uploaded from your content's featured image
• Headline and primary text
• CTA button
• Link to your destination URL

For carousel, video, collection, or Stories-specific formats, create the initial ad through ILLIXIS and then edit the creative in Meta Ads Manager.

Token Management

Meta's OAuth implementation differs from other platforms. There are no refresh tokens. The long-lived access token expires after approximately 60 days, and the only way to renew it is to re-authorize.

Token Lifecycle

| Event | Timing |
|-------|--------|
| Token issued | When you click "Connect Meta" and complete OAuth |
| Token valid | ~60 days from issue date |
| Warning threshold | 7 days before expiry (ILLIXIS shows a warning) |
| Buffer zone | 1 day before expiry (token marked invalid, operations blocked) |
| Token expired | Must re-authorize to continue |

What Happens When the Token Expires

• Audience syncs fail with "Meta access token expired"
• Ad creation is blocked
• Existing ads in Meta Ads Manager continue running (they are independent of the ILLIXIS token)
• Your Custom Audiences remain active in Meta

Re-Authorization

1. Go to Settings > Integrations > Meta.
2. Click Reconnect.
3. Complete the OAuth flow again (same steps as initial connection).
4. Your ad account and Pixel selection are preserved -- you just need to re-authorize.

Set a calendar reminder for every 50 days to re-authorize before the token expires.

Automation Schedule

ILLIXIS automatically manages your Meta audiences on a regular schedule:

| Task | Frequency | Timing |
|------|-----------|--------|
| Audience sync to Meta | After GA4 audience creation | 30 seconds after audience creation completes |
| Token expiry check | Daily | Warns 7 days before expiry |

What this means for you:

• When you trigger a full audience sync, Meta audiences are created automatically after the GA4 audiences are built. No separate action needed.
• If your token is approaching expiry, you will see a warning banner in the Integrations page. Re-authorize before the token expires to avoid interruption.

Manual refresh: Click "Sync to Meta" on any audience or on the dashboard to push audiences outside the automated schedule.

Troubleshooting

"Meta not connected"

Cause: No active, authorized MetaConnection found for your tenant.

Fix: Go to Settings > Integrations and click "Connect Meta" to start the OAuth flow.

"Meta access token expired. Please reconnect."

Cause: The 60-day long-lived token has expired.

Fix: Click "Reconnect" in Settings > Integrations > Meta and complete the OAuth flow again.

"Meta Pixel not configured"

Cause: The connection exists but no Pixel ID is stored. This happens if the ad account has no Pixels or the Pixel was not detected during setup.

Fix:

1. Verify your Meta Pixel exists in Events Manager > Data Sources.
2. Ensure the Pixel is associated with your ad account.
3. Reconnect Meta (the Pixel is fetched automatically during account selection).

"Audience not synced to Meta. Please sync audience first."

Cause: You tried to create an ad for an audience that hasn't been pushed to Meta as a Custom Audience yet.

Fix: Click "Sync to Meta" on the audience detail page, wait for the sync to complete, then try creating the ad again.

"No content with featured image in this cluster"

Cause: The ad creator needs an image from your content, but none of the content items in the audience's topic cluster have a featured image.

Fix: Add a featured image to at least one content item in the cluster, or use the Visual Ad Builder to create ads with custom images.

"Meta ad account not selected"

Cause: OAuth completed but you did not finish the account selection step.

Fix: Go to Settings > Integrations > Meta and complete the ad account selection.

Ad Creation Failed with API Error

Cause: Meta's API rejected the ad creation request. Common reasons include policy violations, missing Page permissions, or invalid audience.

Fix:

1. Check the error message returned (stored on the audience record).
2. Verify your Facebook Page has the required permissions.
3. Ensure the Custom Audience has enough users (Meta requires minimum audience sizes for delivery).
4. Check that your ad content complies with Meta's advertising policies.

Related Guides

• Advertising Overview -- Dashboard, audience management, and ad platform overview
• Prospecting Campaigns -- Interest targeting, lookalike audiences, and new customer acquisition
• GA4 Audiences -- How topic-based audiences are created from your analytics data