# App Promotion Campaign Workflow (OUTCOME_APP_PROMOTION)

## When to use

Use for campaigns that drive mobile app installs, in-app events, or app re-engagement for a mobile application registered in Meta's App Dashboard.

## Before starting

Re-read [../constraints.md](../constraints.md). Most relevant:
- Budget in cents (×100)
- `promoted_object` required for OUTCOME_APP_PROMOTION — missing it causes a cryptic API error
- `targeting_automation` inside `targeting`
- Budget at campaign level for Advantage+
- `meta_ads_adset_create` takes `ad_account_id` (numeric, no `act_` prefix) + a `body` dict — all ad set fields inside `body`
- `meta_ads_ad_create` takes `ad_account_id` + a `body` dict — no separate top-level args
- Use `meta_ads_campaigns_activate()`, not `update_campaign(status="ACTIVE")`

---

## Required inputs

| Input | How to get it |
|---|---|
| Ad account ID | Discovery step 1 |
| Facebook Page ID | Discovery step 2 (`meta_ads_owned_pages_list`) |
| Mobile App ID | Ask the user — from Meta App Dashboard (not the app store ID) |
| App store URL | Ask the user — full Apple App Store or Google Play URL with https:// |
| Optimization goal | App installs (default) or specific in-app events |
| Budget amount + currency | Ask the user |
| Daily or lifetime | Ask; lifetime needs start + end dates |
| Ad creative (image_hash) | Upload via `meta_ads_ad_images_upload` |

`promoted_object` with both `application_id` **and** `object_store_url` is required. Missing either will fail at the API.

---

## Decision point: installs vs re-engagement

```
User wants app promotion
  ├── New installs (most common)
  │     optimization_goal: APP_INSTALLS
  │     call_to_action: DOWNLOAD
  │
  └── Re-engagement (existing users)
        optimization_goal: APP_EVENT (confirm specific event with user)
```

Default to APP_INSTALLS unless re-engagement is specified.

---

## Step-by-step creation (default)

### Pre-build checklist

- [ ] App ID confirmed (from Meta App Dashboard — NOT the app store numeric ID)
- [ ] App store URL confirmed (full URL with https://) — this exact URL becomes both the ad set's `object_store_url` AND the creative's CTA `link`
- [ ] Budget confirmed and converted to cents
- [ ] Page ID captured explicitly from discovery
- [ ] Creative assets ready or will use app store screenshots
- [ ] Adding to an **existing** ad set? Call `meta_ads_adset_get` first and copy `promoted_object.object_store_url` into the creative link verbatim

### 1. Create campaign

```python
meta_ads_campaign_create(
    ad_account_id="123456789",
    body={
        "name": "App Installs - [App Name] - [Date]",
        "objective": "OUTCOME_APP_PROMOTION",
        "status": "PAUSED",
        "daily_budget": 2000,              # $20/day in cents — Advantage+ only; omit for manual
        "is_skadnetwork_attribution": True # REQUIRED if the ad set targets iOS 14+ (see note in step 2);
                                        # campaign-level and immutable — can't be added later
    }
)
```

→ Capture `campaign_id`.

### 2. Create ad set

> `meta_ads_adset_create` takes `ad_account_id` (numeric, no `act_` prefix) plus a `body` dict. Every ad set field goes inside `body`.

**Advantage+ (default):**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "US Broad - App Installs",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "APP_INSTALLS",
    "billing_event": "IMPRESSIONS",
    "targeting": {
      "geo_locations": {
        "countries": [
          "US"
        ]
      },
      "targeting_automation": {
        "advantage_audience": 1
      }
    },
    "promoted_object": {
      "application_id": "<app_id>",
      "object_store_url": "https://apps.apple.com/app/example/id123456789"
    }
  }
}
```

> **CRITICAL**: `promoted_object` with both `application_id` AND `object_store_url` is required. Omitting either causes a cryptic API error.

> **CRITICAL**: `application_id` is the Meta App Dashboard ID, not the numeric App Store ID.

**Manual (only when user explicitly requests):**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "US 18-35 - App Installs",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "APP_INSTALLS",
    "billing_event": "IMPRESSIONS",
    "daily_budget": 2000,
    "targeting": {
      "geo_locations": {
        "countries": [
          "US"
        ]
      },
      "age_min": 18,
      "age_max": 35
    },
    "promoted_object": {
      "application_id": "<app_id>",
      "object_store_url": "https://apps.apple.com/app/example/id123456789"
    }
  }
}
```

→ Capture `adset_id`.

> **iOS 14+ targeting (SKAdNetwork).** To target "iOS 14 and above" set
> `targeting.user_os: ["iOS_ver_14.0_and_above"]` on the ad set **and** create the parent
> campaign with `is_skadnetwork_attribution: true` (a **campaign-level** flag on
> `meta_ads_campaign_create`, not an ad-set field). Without it Meta silently clamps the
> target to `iOS_ver_14.0_to_14.4` and the ad set shows as **"Apple App Store (iOS 13.7 or
> earlier)"** in Ads Manager. The flag is **immutable after the campaign is created** — if
> you forgot it, delete the campaign and recreate it. Creating an open-ended-iOS app ad set
> under a non-SKAdNetwork campaign is now rejected with this guidance rather than shipping
> the broken target. **Android is unaffected** — this is iOS-only (SKAdNetwork is Apple's
> framework).
>
> **user_os value format.** The ONLY valid values are `iOS_ver_<v>_and_above` /
> `Android_ver_<v>_and_above` (open-ended), `iOS_ver_<min>_to_<max>` (range), or bare
> `iOS` / `Android` (all versions). Do **not** use `iOS_14`, `iOS 14+`, or a
> `user_os_version` field — Meta rejects them with *"Invalid User_os Value"* / *"not a
> valid target spec field"*. (Shorthand is auto-normalized as a safety net, but emit the
> canonical value.)

### 3. Upload image

```python
meta_ads_ad_images_upload(account_id="act_123456789", image_url="<url>")
```

→ Capture `image_hash`.

### 4. Create ad

> **CRITICAL**: `meta_ads_ad_create` takes `ad_account_id` plus a single `body` dict. No separate top-level args.

> **CRITICAL — the creative link MUST match the ad set's `object_store_url` exactly.** Meta rejects the ad with *"Object store URL does not match promoted object"* if the creative's CTA destination differs from the store URL on the ad set's `promoted_object`. **Never guess or hand-type the store URL.** If you did not just create the ad set yourself (e.g. you are adding creatives to an existing ad set), call `meta_ads_adset_get(<adset_id>)` **first**, read `promoted_object.object_store_url`, and copy that exact value into:
> - `link_data.link`, and
> - `link_data.call_to_action.value.link` (if you set a CTA value)
>
> They must be character-for-character identical to the ad set's `object_store_url`.

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "App Install Ad - [Creative]",
    "adset_id": "<adset_id>",
    "creative": {
      "object_story_spec": {
        "page_id": "<page_id>",
        "link_data": {
          "link": "<EXACT object_store_url from the ad set's promoted_object>",
          "image_hash": "<image_hash>",
          "call_to_action": {
            "type": "DOWNLOAD"
          },
          "message": "Download [App Name] and [key benefit].",
          "name": "Get the App"
        }
      }
    }
  }
}
```

> Omit `status` — ads default to PAUSED.

→ Capture `ad_id`.

### 5. Preview and activate

```python
# creative_id is in the ad creation response: response.creative.id
meta_ads_ad_previews_get(creative_ids=["<creative_id>"])
meta_ads_campaigns_activate(campaign_id="<campaign_id>")  # when user approves
```

---

## Common failure points

| Symptom | Cause | Fix |
|---|---|---|
| `Object store URL does not match promoted object` (code 100) | Creative CTA link ≠ ad set's `promoted_object.object_store_url` | Read `promoted_object.object_store_url` via `meta_ads_adset_get` and copy it exactly into the creative's `link` (don't guess the URL) |
| Cryptic API error on ad set | Missing `promoted_object` | Add `application_id` + `object_store_url` |
| "App not found" error | Wrong `application_id` | Verify in Meta App Dashboard, not app store |
| `object_store_url` invalid | URL format wrong or missing https:// | Use full URL with https:// |
| Budget rejected | Passed dollars not cents | Multiply by 100 |
| Ad set error: unexpected argument | Fields outside `body` | All fields must be inside the `body` dict |
| Campaign ACTIVE but no installs | Used `update_campaign(status="ACTIVE")` | Use `meta_ads_campaigns_activate()` |
| Ad set shows "iOS 13.7 or earlier" / `user_os` reads `iOS_ver_14.0_to_14.4` | Parent **campaign** not created as iOS-14 SKAdNetwork, so Meta clamped the open-ended target | Recreate the campaign with `meta_ads_campaign_create(..., is_skadnetwork_attribution=true)` — it's a campaign-level flag, immutable after creation |

# Awareness & Engagement Campaign Workflow

## When to use

**OUTCOME_AWARENESS**: Maximize brand reach and impressions. No user action required.

**OUTCOME_ENGAGEMENT**: Drive interactions — post likes, shares, comments, Page follows, or video views.

These are the simplest campaign types. No pixel required. No complex `promoted_object` setup.

## Before starting

Re-read [../constraints.md](../constraints.md). Most relevant:
- Budget in cents (×100)
- `targeting_automation` inside `targeting`
- Budget at campaign level for Advantage+
- `meta_ads_adset_create` takes `ad_account_id` (numeric, no `act_` prefix) + a `body` dict — all ad set fields inside `body`
- `meta_ads_ad_create` takes `ad_account_id` + a `body` dict — no separate top-level args
- Use `meta_ads_campaigns_activate()`, not `update_campaign(status="ACTIVE")`

---

## Required inputs

| Input | How to get it |
|---|---|
| Ad account ID | Discovery step 1 |
| Facebook Page ID | Discovery step 2 (`meta_ads_owned_pages_list`) |
| Goal: awareness or engagement? | Ask the user if not stated |
| Budget amount + currency | Ask the user |
| Daily or lifetime | Ask; lifetime needs start + end dates |
| Ad creative (image_hash) | Upload via `meta_ads_ad_images_upload` |

No pixel needed. `promoted_object` is optional for engagement.

---

## Optimization goals

| Objective | optimization_goal |
|---|---|
| OUTCOME_AWARENESS | `REACH` |
| OUTCOME_ENGAGEMENT | `POST_ENGAGEMENT` |

---

## Step-by-step creation (default)

### 1. Create campaign

**Awareness:**
```python
meta_ads_campaign_create(
    ad_account_id="123456789",
    body={
        "name": "Awareness - [Brand] - [Date]",
        "objective": "OUTCOME_AWARENESS",
        "status": "PAUSED",
        "daily_budget": 2000
    }
)
```

**Engagement:**
```python
meta_ads_campaign_create(
    ad_account_id="123456789",
    body={
        "name": "Engagement - [Brand] - [Date]",
        "objective": "OUTCOME_ENGAGEMENT",
        "status": "PAUSED",
        "daily_budget": 2000
    }
)
```

→ Capture `campaign_id`.

### 2. Create ad set

> `meta_ads_adset_create` takes `ad_account_id` (numeric, no `act_` prefix) plus a `body` dict. Every ad set field goes inside `body`.

**Advantage+ awareness:**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "US Broad - Brand Awareness",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "REACH",
    "billing_event": "IMPRESSIONS",
    "targeting": {
      "geo_locations": {
        "countries": [
          "US"
        ]
      },
      "targeting_automation": {
        "advantage_audience": 1
      }
    }
  }
}
```

**Advantage+ engagement:**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "US Broad - Page Engagement",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "POST_ENGAGEMENT",
    "billing_event": "IMPRESSIONS",
    "targeting": {
      "geo_locations": {
        "countries": [
          "US"
        ]
      },
      "targeting_automation": {
        "advantage_audience": 1
      }
    }
  }
}
```

→ Capture `adset_id`.

### 3. Upload image

```python
meta_ads_ad_images_upload(account_id="act_123456789", image_url="<url>")
```

→ Capture `image_hash`.

### 4. Create ad

> **CRITICAL**: `meta_ads_ad_create` takes `ad_account_id` plus a single `body` dict. No separate top-level args.

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "Awareness Ad - [Creative]",
    "adset_id": "<adset_id>",
    "creative": {
      "object_story_spec": {
        "page_id": "<page_id>",
        "link_data": {
          "link": "https://example.com",
          "image_hash": "<image_hash>",
          "call_to_action": {
            "type": "LEARN_MORE"
          },
          "message": "<primary_text>",
          "name": "<headline>"
        }
      }
    }
  }
}
```

> Omit `status` — ads default to PAUSED.

→ Capture `ad_id`.

### 5. Preview and activate

```python
# creative_id is in the ad creation response: response.creative.id
meta_ads_ad_previews_get(creative_ids=["<creative_id>"])
meta_ads_campaigns_activate(campaign_id="<campaign_id>")  # when user approves
```

---

## Manual path (only when user explicitly requests)

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "AU 18-35 Awareness",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "REACH",
    "billing_event": "IMPRESSIONS",
    "daily_budget": 2000,
    "targeting": {
      "geo_locations": {
        "countries": [
          "AU"
        ]
      },
      "age_min": 18,
      "age_max": 35
    }
  }
}
```

Budget at **ad set level** for manual. No `targeting_automation`.

# Leads Campaign Workflow (OUTCOME_LEADS)

## When to use

Use for campaigns optimized for lead generation: native Meta lead forms, website form submissions, or any event where a user provides contact information.

## Before starting

Re-read [../constraints.md](../constraints.md). Every rule there applies here. Most relevant:
- Budget in cents (×100)
- `promoted_object` required for OUTCOME_LEADS — missing it, or missing any required field within it, causes a validation error
- `targeting_automation` inside `targeting`
- Budget at campaign level for Advantage+
- `meta_ads_adset_create` takes `ad_account_id` (numeric, no `act_` prefix) + a `body` dict — all ad set fields inside `body`
- `meta_ads_ad_create` takes `ad_account_id` + a `body` dict — no separate top-level args
- Use `meta_ads_campaigns_activate()`, not `update_campaign(status="ACTIVE")`
- **"Bid amount required" errors MUST be surfaced to the user — do NOT change optimization_goal as a workaround**

---

## Required inputs

| Input | How to get it |
|---|---|
| Ad account ID | Discovery step 1 |
| Facebook Page ID | Discovery step 2 — see fallback note below |
| Lead capture method | Ask: native lead form OR website pixel? |
| Pixel ID (if website leads) | `meta_ads_ad_pixels_list` |
| Landing page URL (if website leads) | Ask the user |
| Budget amount + currency | Ask the user |
| Daily or lifetime | Ask; lifetime needs start + end dates |
| Ad creative (image_hash or creative_id) | Upload via `meta_ads_ad_images_upload`, or list existing via `meta_ads_creative_list` |

**Never proceed to campaign creation without all required inputs confirmed.**

---

## Decision point: lead form vs website pixel

```
User wants leads
  ├── Native Meta Lead Form
  │     Users fill form directly on Facebook/Instagram
  │     promoted_object: {"page_id": "<page_id>"}
  │
  └── Website pixel (landing page)
        Users click through to your website and submit a form
        promoted_object: {
          "pixel_id": "<pixel_id>",
          "custom_event_type": "LEAD",
          "page_id": "<page_id>"       ← required on BOTH paths
        }
```

If the user hasn't specified, ask:
> "Do you want users to fill out a form directly within Facebook/Instagram, or drive them to a landing page on your website?"

---

## Step-by-step creation (default)

### Pre-build checklist

- [ ] Lead capture method confirmed (form or website)
- [ ] Budget confirmed and converted to cents
- [ ] Page ID captured — see note below if `meta_ads_owned_pages_list` fails
- [ ] Pixel ID captured (if website leads)
- [ ] Destination URL confirmed (if website leads)
- [ ] Creative ready: image_hash from upload, or existing creative_id confirmed with correct destination URL
- [ ] Health check run: `meta_ads_health_check` — **required before first campaign on any account**

### 1. Run health check

```python
meta_ads_health_check(account_id="act_123456789")
```

Surface any non-PASS items before continuing. A failing pixel health check means `LEAD_GENERATION` optimization may not be available for this account.

### 2. Create campaign

```python
meta_ads_campaign_create(
    ad_account_id="123456789",
    body={
        "name": "Leads - [Business] - [Date]",
        "objective": "OUTCOME_LEADS",
        "status": "PAUSED",
        "daily_budget": 2000    # $20/day in cents — Advantage+ only; omit for manual
    }
)
```

→ Capture `campaign_id` from the response.

### 3. Look up pixel ID (website leads only)

```python
meta_ads_ad_pixels_list(account_id="act_123456789")
```

→ Capture `pixel_id`. Required for `promoted_object`.

Skip if using the native lead form path — `promoted_object` uses only `page_id` there.

### 4. Create ad set

> `meta_ads_adset_create` takes `ad_account_id` (numeric, no `act_` prefix) plus a `body` dict. Every ad set field goes inside `body`.

> **Bid strategy warning**: If the account has a non-default bid strategy (e.g. LOWEST_COST_WITH_BID_CAP), ad set creation will fail with "Bid Amount Required." If you see this error, **stop immediately and surface it to the user** — do NOT add `bid_amount` or change `optimization_goal` as workarounds. See constraints.md section 14.

**Advantage+ — website pixel path:**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "US Broad - Demo Requests",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "LEAD_GENERATION",
    "billing_event": "IMPRESSIONS",
    "targeting": {
      "geo_locations": {
        "countries": [
          "US"
        ]
      },
      "targeting_automation": {
        "advantage_audience": 1
      }
    },
    "promoted_object": {
      "pixel_id": "<pixel_id>",
      "custom_event_type": "LEAD",
      "page_id": "<page_id>"
    }
  }
}
```

> **CRITICAL**: `promoted_object` requires `pixel_id`, `custom_event_type`, **and** `page_id` for the website pixel path. The local validator will reject the call if any of these three fields is missing.

**Advantage+ — native lead form path:**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "US Broad - Lead Form",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "LEAD_GENERATION",
    "billing_event": "IMPRESSIONS",
    "targeting": {
      "geo_locations": {
        "countries": [
          "US"
        ]
      },
      "targeting_automation": {
        "advantage_audience": 1
      }
    },
    "promoted_object": {
      "page_id": "<page_id>"
    }
  }
}
```

> **CRITICAL**: `targeting_automation` is inside `targeting`, not at the ad set top level.

> **CRITICAL**: No `daily_budget` on the ad set for Advantage+ — campaign controls budget.

**Manual (only when user explicitly requests):**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "UK Decision Makers 30-55",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "LEAD_GENERATION",
    "billing_event": "IMPRESSIONS",
    "daily_budget": 3000,
    "targeting": {
      "geo_locations": {
        "countries": [
          "GB"
        ]
      },
      "age_min": 30,
      "age_max": 55
    },
    "promoted_object": {
      "pixel_id": "<pixel_id>",
      "custom_event_type": "LEAD",
      "page_id": "<page_id>"
    }
  }
}
```

→ Capture `adset_id` from the response.

#### If LEAD_GENERATION optimization goal is rejected (error 2490408)

This error means the account's bid strategy (`LOWEST_COST_WITH_BID_CAP`) is incompatible with `LEAD_GENERATION`. **Adding `bid_amount` will not fix it** — the optimization goal is simply unavailable under this bid strategy, regardless of what values you pass.

1. **Stop. Do not substitute `LINK_CLICKS` or change the objective to `OUTCOME_TRAFFIC`.** That silently creates a traffic campaign, not a leads campaign.
2. Surface the constraint to the user with the available resolution paths:

   > "Meta's `LEAD_GENERATION` optimization goal isn't available on this account due to its current bid strategy (`LOWEST_COST_WITH_BID_CAP`). Here are your options:
   > - **Recommended**: Change the account's bid strategy to 'Lowest Cost' (no cap) in Meta Business Manager, then I'll retry.
   > - **Workaround**: Run as a traffic campaign with link click optimization — this will drive clicks to your landing page but won't optimize for lead events.
   > - **Alternative**: Use a native Meta Lead Form instead of the website landing page, which may work under this bid strategy.
   > Which would you like to do?"

3. Do not proceed until the user has chosen a path.

### 5. (Native lead form path only) List lead forms

If using a native lead form, you need a `lead_gen_form_id` from the page:

```python
meta_ads_lead_forms_list(page_id="<page_id>")
```

> **Warning**: This tool requires a **Page Access Token** and will fail with error 190 ("This method must be called with a Page Access Token") when using a User Access Token. If this happens:
> - Ask the user to supply the form ID manually from their Facebook Page → Publishing Tools → Forms Library
> - Or proceed without a form ID for testing purposes (the ad will link to the Page, not a form — it will not collect leads until a form is attached)
> - Do not proceed silently without informing the user of this limitation

### 5. Upload image or prepare creative

```python
meta_ads_ad_images_upload(
    account_id="act_123456789",
    image_url="<public_image_url>"    # or file_id if from Hyper file storage
)
```

→ Capture `image_hash`.

#### Creating a creative from scratch with `meta_ads_creative_create`

Use this when you need full control over the creative spec (e.g., native lead form ads). `name` is a **required** positional argument — it will fail silently if omitted.

```python
meta_ads_creative_create(
    ad_account_id="123456789",
    body={
        "name": "Creative Name",        # REQUIRED — not optional
        "object_story_spec": {
            "page_id": "<page_id>", # REQUIRED at top level — never inside link_data
            "link_data": {
                "message": "<primary ad copy>",
                "link": "<destination_url>",
                "description": "<secondary copy or headline>",
                "picture": "<image_url>",
                "call_to_action": {"type": "SIGN_UP"}
            }
        }
    }
)
```

**Valid `link_data` fields:**

| Field | Purpose | Notes |
|---|---|---|
| `message` | Primary ad copy | Required |
| `link` | Destination URL | Required |
| `description` | Secondary copy / headline text | Use this for headline-style text |
| `picture` | Image URL | Use image_hash instead if available |
| `call_to_action` | CTA button | `{"type": "SIGN_UP"}` or similar |
| `caption` | Display URL shown under ad | **Must be a URL** (e.g. `"hyperfx.ai"`), NOT copy text |

**Fields that do NOT work in `link_data`:**
- `headline` — not a valid field; causes "unsupported field" API error. Use `description` instead.
- `page_id` — must be at the **top level** of `object_story_spec`, not inside `link_data`.

→ Capture `creative_id` from the response.

If the user has provided or selected an **existing creative** (`creative_id`), skip the upload — but verify the destination URL first.

`meta_ads_creative_list` returns `link_url: null` in its list response, so you cannot verify the destination from the list alone. Call `meta_ads_creative_get(creative_id)` on the selected creative to retrieve the actual `link_url` before attaching it:

```python
meta_ads_creative_get(creative_id="33892633203717215")
# Check the returned link_url matches the user's intended landing page
```

If the destination doesn't match, tell the user and either select a different creative or create a new inline one.

**Selecting among multiple existing creatives:** When `meta_ads_creative_list` returns several options, choose based on:
1. Body copy alignment with campaign goal (lead-focused language > viral/social tone)
2. Headline relevance to the offer or CTA
3. Destination URL (verify via `meta_ads_creative_get` — the list shows `null`)

If you're unsure, show the user the top 2–3 options (name + body copy) and let them choose.

### 6. Create ad

> **CRITICAL**: `meta_ads_ad_create` takes `ad_account_id` plus a single `body` dict. No separate top-level args.

**With new inline creative (image_hash):**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "Lead Ad - [Creative Name]",
    "adset_id": "<adset_id>",
    "creative": {
      "object_story_spec": {
        "page_id": "<page_id>",
        "link_data": {
          "link": "https://example.com/contact",
          "image_hash": "<image_hash>",
          "call_to_action": {
            "type": "LEARN_MORE"
          },
          "message": "<primary_text>",
          "name": "<headline>",
          "description": "<description>"
        }
      }
    }
  }
}
```

**With existing creative (creative_id):**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "Lead Ad - [Creative Name]",
    "adset_id": "<adset_id>",
    "creative": {
      "creative_id": "<creative_id>"
    }
  }
}
```

> Omit `status` — ads default to PAUSED. Never pass `status="ACTIVE"` on creation.

→ Capture `ad_id` from the response.

### 7. Preview and activate

```python
# creative_id comes from the ad creation response (response.creative.id)
# or from the creative you created separately via create_ad_creative
# ad_id is NOT a valid parameter — creative_ids (list) is always required
meta_ads_ad_previews_get(creative_ids=["<creative_id>"])
```

Summarize preview formats to user — never render iframe inline.
Wait for explicit user approval before activating.

```python
meta_ads_campaigns_activate(campaign_id="<campaign_id>")
# Activates campaign + ad sets + ads together
# NOT: meta_ads_campaign_update(status="ACTIVE") — that leaves ad sets PAUSED
```

---

## Page ID fallback

`meta_ads_owned_pages_list` can fail with "No business ID found for this ad account" when the account is not connected to a Business Manager with a recognized business ID.

**If this happens**, call `meta_accounts_list` as a fallback:

```python
meta_accounts_list(account_id="act_123456789")
```

This returns connected pages and accounts through an alternate lookup path. Capture `page_id` from the response.

---

## Common failure points

| Symptom | Cause | Fix |
|---|---|---|
| Local validation error: "page_id required in promoted_object" | Missing page_id on website pixel path | Add `page_id` alongside `pixel_id` and `custom_event_type` |
| "No business ID found" from `list_owned_pages` | Account not linked to a Business Manager | Use `meta_accounts_list` as fallback |
| "Bid amount required" | Account-level bid strategy requires explicit bid | **Stop. Surface to user. Do NOT add bid_amount or change optimization_goal.** |
| "Performance goal isn't available" (subcode 2490408) | LEAD_GENERATION rejected by account | Run health check, stop, ask user. Do NOT substitute LINK_CLICKS. |
| Cryptic API error on ad set | Missing `promoted_object` entirely | Add promoted_object with all required fields |
| Budget at wrong level | Set budget on ad set for Advantage+ | Move to campaign level; remove from ad set |
| Nothing serves after activation | Used `update_campaign(status="ACTIVE")` | Use `meta_ads_campaigns_activate()` |
| Creative destination URL wrong | Existing creative linked to different URL | Verify creative destination before attaching |

---

## Full worked example

See [../examples/leads-form.md](../examples/leads-form.md).

# Sales Campaign Workflow (OUTCOME_SALES)

## When to use

Use for campaigns optimized for website purchases, checkout completions, or any offsite conversion event tracked via Meta Pixel.

## Before starting

Re-read [../constraints.md](../constraints.md). Every rule there applies here. Most relevant:
- Budget in cents (×100)
- `promoted_object` required for OUTCOME_SALES
- `targeting_automation` inside `targeting`
- Budget at campaign level for Advantage+
- `meta_ads_adset_create` takes `ad_account_id` (numeric, no `act_` prefix) + a `body` dict — all ad set fields inside `body`
- `meta_ads_ad_create` takes `ad_account_id` + a `body` dict — no separate top-level args
- Use `meta_ads_campaigns_activate()`, not `update_campaign(status="ACTIVE")`

---

## Required inputs

| Input | How to get it |
|---|---|
| Ad account ID | Discovery step 1 |
| Facebook Page ID | Discovery step 2 (`meta_ads_owned_pages_list`) |
| Meta Pixel ID | `meta_ads_ad_pixels_list` — step 2 of creation below |
| Conversion event type | Ask user — default is `PURCHASE` |
| Budget amount + currency | Ask the user |
| Daily or lifetime | Ask; lifetime needs start + end dates |
| Destination URL | Ask the user |
| Ad creative (image_hash) | Upload via `meta_ads_ad_images_upload` |

---

## Decision point: conversion type

```
User wants sales
  ├── Website purchases (most common)
  │     optimization_goal: OFFSITE_CONVERSIONS
  │     promoted_object: {pixel_id, custom_event_type: "PURCHASE"}
  ├── Custom conversion event (add to cart, checkout, etc.)
  │     optimization_goal: OFFSITE_CONVERSIONS
  │     promoted_object: {pixel_id, custom_event_type: "<EVENT>"}
  └── Catalog / dynamic product ads
        promoted_object: {pixel_id, product_catalog_id}  ← confirm with user first
```

Default to PURCHASE unless the user specifies otherwise.

---

## Step-by-step creation (default)

Use this for most campaigns. Each step is visible, failures are easy to diagnose and retry.

### Pre-build checklist

- [ ] Budget confirmed and converted to cents
- [ ] Page ID captured explicitly from discovery
- [ ] Destination URL confirmed
- [ ] Creative assets ready or will generate from site

### 1. Create campaign

```python
meta_ads_campaign_create(
    ad_account_id="123456789",
    body={
        "name": "Sales - [Business] - [Date]",
        "objective": "OUTCOME_SALES",
        "status": "PAUSED",
        "daily_budget": 2000    # $20/day in cents — Advantage+ only; omit for manual
    }
)
```

→ Capture `campaign_id` from the response.

### 2. Look up pixel ID

```python
meta_ads_ad_pixels_list(account_id="act_123456789")
```

→ Capture `pixel_id`. Required for `promoted_object`.

### 3. Create ad set

> `meta_ads_adset_create` takes `ad_account_id` (numeric, no `act_` prefix) plus a `body` dict. Every ad set field goes inside `body`.

**Advantage+ (default):**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "US Broad - Purchases",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "OFFSITE_CONVERSIONS",
    "billing_event": "IMPRESSIONS",
    "targeting": {
      "geo_locations": {
        "countries": [
          "US"
        ]
      },
      "targeting_automation": {
        "advantage_audience": 1
      }
    },
    "promoted_object": {
      "pixel_id": "<pixel_id>",
      "custom_event_type": "PURCHASE"
    }
  }
}
```

> **CRITICAL**: `promoted_object` is required for OUTCOME_SALES. Missing it causes a cryptic API error.

> **CRITICAL**: `targeting_automation` is inside `targeting`, not at the ad set top level.

> **CRITICAL**: No `daily_budget` on the ad set for Advantage+ — campaign controls budget.

**Manual (only when user explicitly requests):**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "US Women 25-44",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "OFFSITE_CONVERSIONS",
    "billing_event": "IMPRESSIONS",
    "daily_budget": 2000,
    "targeting": {
      "geo_locations": {
        "countries": [
          "US"
        ]
      },
      "age_min": 25,
      "age_max": 44,
      "genders": [
        2
      ]
    },
    "promoted_object": {
      "pixel_id": "<pixel_id>",
      "custom_event_type": "PURCHASE"
    }
  }
}
```

→ Capture `adset_id` from the response.

### 4. Upload image

```python
meta_ads_ad_images_upload(
    account_id="act_123456789",
    image_url="<public_image_url>"    # or file_id if from Hyper file storage
)
```

→ Capture `image_hash` from the response.

### 5. Create ad

> **CRITICAL**: `meta_ads_ad_create` takes `ad_account_id` plus a single `body` dict containing all ad fields. Do not pass `name` or `adset_id` as separate top-level arguments and do not pass `body` as a JSON string.

```
❌ WRONG: meta_ads_ad_create(account_id="act_...", adset_id="123", name="My Ad")
❌ WRONG: meta_ads_ad_create(ad_account_id="...", body='{"adset_id": "123"}')  # string not dict
✅ RIGHT:  meta_ads_ad_create(ad_account_id="111222333", body={"adset_id": "123", ...})
```

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "Sales Ad - [Creative Name]",
    "adset_id": "<adset_id>",
    "creative": {
      "object_story_spec": {
        "page_id": "<page_id>",
        "link_data": {
          "link": "https://example.com/shop",
          "image_hash": "<image_hash>",
          "call_to_action": {
            "type": "SHOP_NOW"
          },
          "message": "<primary_text>",
          "name": "<headline>",
          "description": "<description>"
        }
      }
    }
  }
}
```

> Omit `status` — ads default to PAUSED. Never pass `status="ACTIVE"` on creation.

→ Capture `ad_id` from the response.

### 6. Preview and activate

```python
# creative_id is in the ad creation response: response.creative.id
meta_ads_ad_previews_get(creative_ids=["<creative_id>"])
# Summarize formats to user — never render iframe inline
# Wait for explicit user approval

meta_ads_campaigns_activate(campaign_id="<campaign_id>")
# Activates campaign + ad sets + ads together
# NOT: meta_ads_campaign_update(status="ACTIVE") — that leaves ad sets PAUSED
```

---

## Other creative formats (step 5 variations)

The single-image `object_story_spec` above is the most common. `meta_ads_ad_create` also supports carousel and dynamic creative natively — just change the `creative` block.

**Carousel** (2–10 cards) — use `child_attachments` inside `link_data`:

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "Sales Carousel Ad",
    "adset_id": "<adset_id>",
    "creative": {
      "object_story_spec": {
        "page_id": "<page_id>",
        "link_data": {
          "link": "https://example.com/shop",
          "message": "Browse our collection",
          "child_attachments": [
            {
              "link": "https://example.com/p1",
              "name": "Product 1",
              "description": "Desc 1",
              "image_hash": "<hash1>"
            },
            {
              "link": "https://example.com/p2",
              "name": "Product 2",
              "description": "Desc 2",
              "image_hash": "<hash2>"
            }
          ],
          "multi_share_optimized": true
        }
      }
    }
  }
}
```

**Dynamic creative** (Meta auto-optimizes combinations) — pair `asset_feed_spec` with a minimal `object_story_spec` that carries the `page_id`:

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "Sales Dynamic Ad",
    "adset_id": "<adset_id>",
    "creative": {
      "object_story_spec": {
        "page_id": "<page_id>"
      },
      "asset_feed_spec": {
        "images": [
          {
            "hash": "<hash1>"
          },
          {
            "hash": "<hash2>"
          }
        ],
        "titles": [
          {
            "text": "Headline A"
          },
          {
            "text": "Headline B"
          }
        ],
        "bodies": [
          {
            "text": "Copy option 1"
          },
          {
            "text": "Copy option 2"
          }
        ],
        "descriptions": [
          {
            "text": "Free shipping over $40"
          }
        ],
        "link_urls": [
          {
            "website_url": "https://example.com/shop"
          }
        ],
        "call_to_action_types": [
          "SHOP_NOW"
        ],
        "ad_formats": [
          "SINGLE_IMAGE"
        ]
      }
    }
  }
}
```

> Dynamic creative requirements:
> - `ad_formats` is **required** — use `["SINGLE_IMAGE"]` (or `["SINGLE_VIDEO"]` for video). Omitting it makes Meta default to SINGLE_IMAGE and reject a feed that carries video.
> - Keep a minimal `object_story_spec` with just `page_id` alongside `asset_feed_spec` (the page_id comes from there).
> - The ad set must be created with `is_dynamic_creative: true` — pass it to `meta_ads_adset_create`.
>
> For non-dynamic ads, `creative` uses a single `object_story_spec` (or `creative_id` to reuse an existing creative).

---

## Common failure points

| Symptom | Cause | Fix |
|---|---|---|
| Cryptic API error on ad set creation | Missing `promoted_object` | Add `pixel_id` + `custom_event_type` to ad set |
| Budget rejected | Passed dollars not cents | Multiply by 100 |
| Ad set error: unexpected argument | Fields passed outside `body` | All fields must be inside the `body` dict |
| Ad creation error | Separate top-level args used | Use `ad_account_id` + `body` |
| Campaign ACTIVE but nothing serves | Used `update_campaign(status="ACTIVE")` | Use `meta_ads_campaigns_activate()` |
| "Bid amount required" | Optimization goal requires explicit bid | Do NOT change goal — ask user |
| `targeting_automation` error | Placed at ad set top level | Move inside `targeting` object |

---

## Full worked example

See [../examples/sales-ecommerce.md](../examples/sales-ecommerce.md).

# Traffic Campaign Workflow (OUTCOME_TRAFFIC)

## When to use

Use for campaigns that send users to a website, landing page, or specific content destination. No conversion tracking required. Good for top-of-funnel content promotion, event pages, or when a pixel is not yet installed.

## Before starting

Re-read [../constraints.md](../constraints.md). Most relevant:
- Budget in cents (×100)
- `targeting_automation` inside `targeting`
- Budget at campaign level for Advantage+
- `meta_ads_adset_create` takes `ad_account_id` (numeric, no `act_` prefix) + a `body` dict — all ad set fields inside `body`
- `meta_ads_ad_create` takes `ad_account_id` + a `body` dict — no separate top-level args
- Use `meta_ads_campaigns_activate()`, not `update_campaign(status="ACTIVE")`

`promoted_object` is **not required** for OUTCOME_TRAFFIC. No pixel needed.

---

## Required inputs

| Input | How to get it |
|---|---|
| Ad account ID | Discovery step 1 |
| Facebook Page ID | Discovery step 2 (`meta_ads_owned_pages_list`) |
| Destination URL | Ask the user |
| Budget amount + currency | Ask the user |
| Daily or lifetime | Ask; lifetime needs start + end dates |
| CTA type | Choose from table below |
| Ad creative (image_hash) | Upload via `meta_ads_ad_images_upload` |

---

## CTA selection

| Destination | Recommended CTA |
|---|---|
| Blog post / article | `LEARN_MORE` |
| Product or collection page | `SHOP_NOW` |
| Event or sign-up page | `SIGN_UP` |
| Resource / download | `DOWNLOAD` |
| Booking / appointment page | `BOOK_NOW` |
| Promotional offer | `GET_OFFER` |
| Contact page | `CONTACT_US` |

---

## Step-by-step creation (default)

### Pre-build checklist

- [ ] Budget confirmed and converted to cents
- [ ] Page ID captured explicitly from discovery
- [ ] Destination URL confirmed
- [ ] CTA selected
- [ ] Creative assets ready or will generate from site

### 1. Create campaign

```python
meta_ads_campaign_create(
    ad_account_id="123456789",
    body={
        "name": "Traffic - [Business] - [Date]",
        "objective": "OUTCOME_TRAFFIC",
        "status": "PAUSED",
        "daily_budget": 2000    # $20/day in cents — Advantage+ only; omit for manual
    }
)
```

→ Capture `campaign_id` from the response.

### 2. Create ad set

> `meta_ads_adset_create` takes `ad_account_id` (numeric, no `act_` prefix) plus a `body` dict. Every ad set field goes inside `body`.

**Advantage+ (default):**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "US Broad - Website Traffic",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "LINK_CLICKS",
    "billing_event": "IMPRESSIONS",
    "targeting": {
      "geo_locations": {
        "countries": [
          "US"
        ]
      },
      "targeting_automation": {
        "advantage_audience": 1
      }
    }
  }
}
```

> No `promoted_object` needed for OUTCOME_TRAFFIC.

**Manual (only when user explicitly requests):**

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "US Adults 25-44",
    "campaign_id": "<campaign_id>",
    "optimization_goal": "LINK_CLICKS",
    "billing_event": "IMPRESSIONS",
    "daily_budget": 2000,
    "targeting": {
      "geo_locations": {
        "countries": [
          "US"
        ]
      },
      "age_min": 25,
      "age_max": 44
    }
  }
}
```

> **Bid cap requested?** Pass `bid_strategy` and `bid_amount` (cents) inside `body` — the toolkit validates the pairing up front. See [../constraints.md](../constraints.md) section 16.

> **Targeting regions / cities / DMAs (not whole countries)?** Resolve the numeric geo keys with `meta_ads_targeting_search` first — never hand-write them. See [../constraints.md](../constraints.md) section 17.

→ Capture `adset_id` from the response.

### 3. Upload image

```python
meta_ads_ad_images_upload(
    account_id="act_123456789",
    image_url="<public_image_url>"
)
```

→ Capture `image_hash` from the response.

### 4. Create ad

> **CRITICAL**: `meta_ads_ad_create` takes `ad_account_id` plus a single `body` dict. No separate top-level args.

```json
{
  "ad_account_id": "123456789",
  "body": {
    "name": "Traffic Ad - [Page Name]",
    "adset_id": "<adset_id>",
    "creative": {
      "object_story_spec": {
        "page_id": "<page_id>",
        "link_data": {
          "link": "https://example.com/page",
          "image_hash": "<image_hash>",
          "call_to_action": {
            "type": "LEARN_MORE"
          },
          "message": "<primary_text>",
          "name": "<headline>",
          "description": "<description>"
        }
      }
    }
  }
}
```

> Omit `status` — ads default to PAUSED.

→ Capture `ad_id` from the response.

### 5. Preview and activate

```python
# creative_id is in the ad creation response: response.creative.id
meta_ads_ad_previews_get(creative_ids=["<creative_id>"])
# Summarize formats to user — never render iframe inline

meta_ads_campaigns_activate(campaign_id="<campaign_id>")
# Only when user explicitly approves
```

---

## Common failure points

| Symptom | Cause | Fix |
|---|---|---|
| Budget rejected | Passed dollars not cents | Multiply by 100 |
| Ad set error: unexpected argument | Fields outside `body` | All fields must be inside the `body` dict |
| Campaign ACTIVE but no traffic | Used `update_campaign(status="ACTIVE")` | Use `meta_ads_campaigns_activate()` |
| `targeting_automation` error | Placed at top level of ad set | Move inside `targeting` object |

# Example: Leads Campaign — Website Landing Page (B2B SaaS, Step-by-Step)

This example shows the full sequence: user request → clarification → written plan → step-by-step execution.

---

## User request

> "I want to run a Facebook lead gen campaign for my B2B SaaS. Budget is $50/day."

---

## Step 1: Clarification questions

Before touching any tools, ask:

```
Before I build this, a few questions:

1. Do you want users to fill out a form directly within Facebook/Instagram (native lead form),
   or drive them to a landing page on your website?
2. What's your website URL / landing page?
3. Do you have a Meta Pixel installed that's firing Lead events?
4. What geography should I target? (Default: United States)
5. How long should this run — ongoing daily budget, or a fixed period?
```

---

## Step 2: User answers

> "Landing page. URL is example.com/demo. Yes, pixel is installed tracking lead events. US only. Ongoing."

---

## Step 3: Written plan (shown before any tool calls)

State the plan explicitly before acting.

```
Here's my plan:

OBJECTIVE: OUTCOME_LEADS (website pixel path)
CAMPAIGN TYPE: Advantage+ (default)
BUDGET: $50/day = 5000 cents at campaign level
OPTIMIZATION GOAL: LEAD_GENERATION
PROMOTED OBJECT: pixel_id + custom_event_type: LEAD + page_id (all three required on website pixel path)
TARGETING: Broad US, Advantage+ audience automation
STATUS: PAUSED until you approve

Steps:
1. Select ad account (meta_ads_adaccount_list)
2. Get Page ID (meta_ads_owned_pages_list)
3. Run health check (meta_ads_health_check)
4. Screenshot example.com/demo for creative reference (firecrawl_screenshots_create)
5. Extract branding (firecrawl_branding_extract)
6. Generate ad creative from screenshot
7. Upload image → get image_hash (meta_ads_ad_images_upload)
8. Create campaign → campaign_id (meta_ads_campaign_create)
9. Get Pixel ID → pixel_id (meta_ads_ad_pixels_list)
10. Create ad set → adset_id (meta_ads_adset_create)
11. Create ad → ad_id (meta_ads_ad_create)
12. Show ad previews — wait for your review
13. Activate only when you say to

Key constraints:
- $50/day = 5000 cents (not 50)
- promoted_object REQUIRED: pixel_id + LEAD event + page_id (all three required on website pixel path)
- targeting_automation inside targeting object
- Budget at campaign level (ad set has no budget)
- create_ad_set takes ad_account_id + body
- create_ad takes ad_account_id + body
- Will use meta_ads_campaigns_activate(), not update(status="ACTIVE")
```

---

## Step 4: Execution

### Discovery

```python
meta_ads_adaccount_list({"detail": "id_only"})
# → account: act_111222333

meta_ads_owned_pages_list({"account_id": "act_111222333", "detail": "id_only"})
# → page_id: 632278516639981  ← captured explicitly

meta_ads_health_check({"account_id": "act_111222333"})
# → All checks PASS
```

### Research

```python
firecrawl_screenshots_create({"url": "https://example.com/demo"})
# → Screenshot: dark navy, "Book a Demo" hero CTA, B2B product screenshots

firecrawl_branding_extract({"url": "https://example.com"})
# → Colors: #0D1B2A (navy), #00C2FF (electric blue)
# → Font: Inter | Tone: professional, direct, B2B
```

### Creative

```python
meta_ads_ad_images_upload({"account_id": "act_111222333", "image_url": "<generated_image_url>"})
# → image_hash: xyz789abc012
```

### Campaign creation (step-by-step)

```python
# Step 1: Campaign
meta_ads_campaign_create(
    ad_account_id="111222333",
    body={
        "name": "Leads - ExampleSaaS - TEST - 2026-06",
        "objective": "OUTCOME_LEADS",
        "status": "PAUSED",
        "daily_budget": 5000    # $50/day in cents
    }
)
# → campaign_id: 987654321

# Step 2: Pixel
meta_ads_ad_pixels_list(account_id="act_111222333")
# → pixel_id: 9876543210

# Step 3: Ad set
meta_ads_adset_create(
    ad_account_id="111222333",
    body={
        "name": "US Broad - Demo Requests - TEST",
        "campaign_id": "987654321",
        "optimization_goal": "LEAD_GENERATION",
        "billing_event": "IMPRESSIONS",
        "targeting": {
            "geo_locations": {"countries": ["US"]},
            "targeting_automation": {"advantage_audience": 1}
        },
        "promoted_object": {
            "pixel_id": "9876543210",
            "custom_event_type": "LEAD",
            "page_id": "632278516639981"
        }
        # No daily_budget — campaign controls budget for Advantage+
    }
)
# → adset_id: 334455667

# Step 4: Ad
meta_ads_ad_create(
    ad_account_id="111222333",
    body={
        "name": "Demo Request - Image Ad - TEST",
        "adset_id": "334455667",
        "creative": {
            "object_story_spec": {
                "page_id": "632278516639981",
                "link_data": {
                    "link": "https://example.com/demo",
                    "image_hash": "xyz789abc012",
                    "call_to_action": {"type": "LEARN_MORE"},
                    "message": "See how ExampleSaaS helps B2B teams close deals faster.",
                    "name": "Book a Free Demo",
                    "description": "No commitment. 30-minute walkthrough."
                }
            }
        }
        # No status field — ads default to PAUSED
    }
)
# → ad_id: 556677889
```

### Preview and summary

```python
# creative_id from ad creation response: response.creative.id
meta_ads_ad_previews_get(creative_ids=["<creative_id>"])
# Summarize preview formats to user — never render iframe inline
```

```
Campaign created and paused. Here's what was built:

Campaign: "Leads - ExampleSaaS - TEST - 2026-06"
Status: PAUSED
Budget: $50/day
Objective: Leads (LEAD pixel event from example.com/demo)
Optimization: LEAD_GENERATION
Targeting: United States, Advantage+ broad audience
Ad previews: [available in the dashboard]

When you're ready to go live, reply "activate".
```

### Activation (when user approves)

```python
# RIGHT
meta_ads_campaigns_activate(campaign_id="987654321")

# WRONG — do not use
# meta_ads_campaign_update(campaign_id="987654321", status="ACTIVE")
```

---

## What if no pixel is installed?

If `meta_ads_ad_pixels_list` returns nothing:

```
I couldn't find a Meta Pixel on your account. To track leads from your website,
you'll need a pixel installed and firing Lead events on the form confirmation.

Would you like to:
a) Set up a pixel first (I can walk you through it), or
b) Use a native Meta Lead Form instead (users fill the form within Facebook/Instagram)?
```

Do not proceed with a website-pixel OUTCOME_LEADS campaign if no pixel exists.

# Example: Sales Campaign — Ecommerce (Advantage+, Step-by-Step)

This example shows the full sequence: user request → clarification → written plan → step-by-step execution.

---

## User request

> "I want to run Facebook ads for my online skincare store. I have a $30/day budget and want to drive purchases."

---

## Step 1: Clarification questions

Before touching any tools, ask:

```
Before I build this, a few quick details:

1. What's your website URL and main landing page for the ads?
2. Do you have a Meta Pixel installed and is it firing Purchase events?
3. What geography should I target? (Default: United States)
4. How long should this run — ongoing daily budget, or a fixed period?
5. Do you have existing product images or should I generate creatives from your website?
```

---

## Step 2: User answers

> "URL is skinfirst.com. Yes, pixel is installed and tracking purchases. US only. Ongoing. Generate from site."

---

## Step 3: Written plan (shown before any tool calls)

State the plan explicitly before acting. Do not start calling tools until this is visible.

```
Here's my plan:

OBJECTIVE: OUTCOME_SALES (website purchases via pixel)
CAMPAIGN TYPE: Advantage+ (default)
BUDGET: $30/day = 3000 cents at campaign level
OPTIMIZATION GOAL: OFFSITE_CONVERSIONS
PROMOTED OBJECT: pixel_id + custom_event_type: PURCHASE
TARGETING: Broad US, Advantage+ audience automation
STATUS: PAUSED until you approve

Steps:
1. Select ad account (meta_ads_adaccount_list)
2. Get Page ID (meta_ads_owned_pages_list)
3. Run health check (meta_ads_health_check)
4. Screenshot skinfirst.com for creative reference (firecrawl_screenshots_create)
5. Extract branding (firecrawl_branding_extract)
6. Generate ad creative from screenshot
7. Upload image → get image_hash (meta_ads_ad_images_upload)
8. Create campaign → campaign_id (meta_ads_campaign_create)
9. Get Pixel ID → pixel_id (meta_ads_ad_pixels_list)
10. Create ad set → adset_id (meta_ads_adset_create)
11. Create ad → ad_id (meta_ads_ad_create)
12. Show ad previews — wait for your review
13. Activate only when you say to

Key constraints:
- $30/day = 3000 cents (not 30)
- promoted_object required: pixel_id + PURCHASE
- targeting_automation inside targeting object
- Budget at campaign level (ad set has no budget)
- create_ad_set takes ad_account_id + body
- create_ad takes ad_account_id + body
- Will use meta_ads_campaigns_activate(), not update(status="ACTIVE")
```

---

## Step 4: Execution

### Discovery

```python
meta_ads_adaccount_list({"detail": "id_only"})
# → account: act_111222333

meta_ads_owned_pages_list({"account_id": "act_111222333", "detail": "id_only"})
# → page_id: 632278516639981  ← captured explicitly

meta_ads_health_check({"account_id": "act_111222333"})
# → All checks PASS
```

### Research

```python
firecrawl_screenshots_create({"url": "https://skinfirst.com"})
# → Screenshot: clean minimal layout, soft pastel palette, hero product shot

firecrawl_branding_extract({"url": "https://skinfirst.com"})
# → Colors: #F5EDE4 (cream), #9B7D6E (warm brown)
# → Font: Playfair Display | Tone: elegant, natural
```

### Creative

```python
# Generate ad image using screenshot as visual reference
meta_ads_ad_images_upload({"account_id": "act_111222333", "image_url": "<generated_image_url>"})
# → image_hash: abc123def456
```

### Campaign creation (step-by-step)

```python
# Step 1: Campaign
meta_ads_campaign_create(
    ad_account_id="111222333",
    body={
        "name": "Sales - SkinFirst - TEST - 2026-06",
        "objective": "OUTCOME_SALES",
        "status": "PAUSED",
        "daily_budget": 3000    # $30/day in cents
    }
)
# → campaign_id: 987654321

# Step 2: Pixel
meta_ads_ad_pixels_list(account_id="act_111222333")
# → pixel_id: 9876543210

# Step 3: Ad set
meta_ads_adset_create(
    ad_account_id="111222333",
    body={
        "name": "US Broad - Purchases - TEST",
        "campaign_id": "987654321",
        "optimization_goal": "OFFSITE_CONVERSIONS",
        "billing_event": "IMPRESSIONS",
        "targeting": {
            "geo_locations": {"countries": ["US"]},
            "targeting_automation": {"advantage_audience": 1}
        },
        "promoted_object": {
            "pixel_id": "9876543210",
            "custom_event_type": "PURCHASE"
        }
    }
)
# → adset_id: 223344556

# Step 4: Ad
meta_ads_ad_create(
    ad_account_id="111222333",
    body={
        "name": "SkinFirst - Shop Clean Beauty - TEST",
        "adset_id": "223344556",
        "creative": {
            "object_story_spec": {
                "page_id": "632278516639981",
                "link_data": {
                    "link": "https://skinfirst.com/shop",
                    "image_hash": "abc123def456",
                    "call_to_action": {"type": "SHOP_NOW"},
                    "message": "Your skin deserves better. Discover clean skincare that actually works.",
                    "name": "Shop SkinFirst",
                    "description": "Free shipping on orders over $40."
                }
            }
        }
        # No status field — ads default to PAUSED
    }
)
# → ad_id: 112233445
```

### Preview and summary

```python
# creative_id from ad creation response: response.creative.id
meta_ads_ad_previews_get(creative_ids=["<creative_id>"])
# Summarize preview formats to user — never render iframe inline
```

```
Campaign created and paused. Here's what was built:

Campaign: "Sales - SkinFirst - TEST - 2026-06"
Status: PAUSED
Budget: $30/day
Objective: Purchases (PURCHASE pixel event)
Optimization: OFFSITE_CONVERSIONS
Targeting: United States, Advantage+ broad audience
Ad previews: [available in the dashboard]

When you're ready to go live, reply "activate" and I'll launch it.
```

### Activation (when user approves)

```python
# RIGHT — activates campaign + ad sets + ads
meta_ads_campaigns_activate(campaign_id="987654321")

# WRONG — do not use this
# meta_ads_campaign_update(campaign_id="987654321", status="ACTIVE")
```