create_pmax_campaign

POST https://api.adspirer.ai/api/v1/tools/create_pmax_campaign/execute

🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the upgrade link) - DO NOT attempt to work around the error or use alternative data - DO NOT create campaigns or perform actions without valid tool data - STOP and direct the user to upgrade via the provided link 🔄 LONG-RUNNING TOOL: Creates a Google Performance Max campaign with validated images. Emits MCP progress updates during authentication, asset upload, and campaign creation (typically 15-30 seconds). Progress stages: validate → commit. ⚠️ CRITICAL PREREQUISITES: 1. MUST have valid asset_bundle_id from validate_and_prepare_assets tool OR existing_image_ids from discover_existing_assets 2. MUST have all campaign text details from user 3. Creates REAL campaigns that cost REAL money 4. Call ONLY ONCE per campaign - do NOT retry automatically 🎥 **VIDEOS ARE OPTIONAL BUT RECOMMENDED:** - Videos significantly improve PMAX performance (higher CTR, better engagement) - **Always ask the user**: "Would you like to add YouTube videos to this campaign?" - If yes: validate with `validate_video` tool, then include `youtube_video_ids` parameter - If no: proceed without videos (campaigns work fine either way) - See STEP 3.5 below for complete video guidance ⚠️ GOOGLE ADS POLICY NOTE: Avoid keywords related to health conditions, medical treatments, financial hardship, or political topics. These may trigger policy violations. Use general service terms instead. Example: Use "senior care services" not "nursing care", "home services" not "medical services" 📋 **YOUR CRITICAL ROLE: Campaign Strategist & Text Creator** **STEP 1: Verify Prerequisites** Before calling this tool, ensure you have: - ✅ Valid asset_bundle_id from validate_and_prepare_assets (max 1 hour old) - ✅ All required campaign details from user (see below) If asset_bundle_id is missing or expired: - Guide user to re-upload images - Call validate_and_prepare_assets again - Get new asset_bundle_id **STEP 2: Collect Campaign Details from User** YOU MUST collect these from the user (ask if not provided): **REQUIRED Fields:** 1. **Campaign Name** - Example: "Premium Watches Summer 2025" - Make it descriptive and unique 2. **Daily Budget** - Google recommends ~$50/day USD equivalent for Performance Max - IMPORTANT: Accept the user's budget in their stated currency — do NOT convert to USD - Ask: "What's your daily advertising budget?" 3. **Final URL** (Landing Page) - Must match verified domain in Google Ads - Example: "https://example.com/watches" - Ask: "What's the landing page URL for this campaign?" 4. **Business Name** - Maximum 25 characters - Example: "Luxury Watch Co" - Will appear in ads **STEP 3: Generate High-Quality Ad Copy** As an expert copywriter, you MUST create compelling ad text: **🚨 BEFORE GENERATING TEXT - READ CHARACTER LIMITS 🚨** **Headlines (3-15 required):** - **STRICT LIMIT: 30 characters maximum per headline** - Count characters BEFORE calling this tool! - Examples: - "Premium Luxury Watches" (22 chars) ✅ - "Free Shipping" (13 chars) ✅ - "Certified Authentic" (19 chars) ✅ **Descriptions (2-4 required):** - **STRICT LIMIT: 80 characters maximum per description** - Count characters BEFORE calling this tool! - Examples: - "Shop authentic luxury timepieces with free worldwide shipping." (63 chars) ✅ - "Expert-curated Swiss watches. Certified authentic. Shop now." (61 chars) ✅ **Long Headlines (1-5 REQUIRED):** - **STRICT LIMIT: 90 characters maximum per long headline** - At least 1 is REQUIRED for Performance Max - Count characters BEFORE calling this tool! - Example: "Premium Swiss Watches - Certified Authentic, Free Worldwide Shipping" (70 chars) ✅ **⚠️ WILL BE REJECTED IF YOU EXCEED LIMITS - NO RETRIES!** **⚠️ COUNT CHARACTERS CAREFULLY - VALIDATION IS STRICT!** **How to Count Characters:** - Use extended thinking to count each text element - Double-check your character counts before calling - If close to limit, shorten it to be safe - Do NOT assume backend will fix it - it won't! - Use clear, concise language - Focus on user benefits **OPTIONAL Fields (use defaults if not provided):** - target_locations: Defaults to ["United States"] - target_languages: Defaults to ["English"] **🎥 STEP 3.5: YouTube Videos (OPTIONAL but Highly Recommended)** **⚠️ IMPORTANT: Always ask the user about videos!** Videos significantly improve Performance Max campaign performance: - **Higher CTR**: Video ads stand out more than static images - **Better engagement**: Users watch videos longer - **Wider reach**: Serves on YouTube, Display, Discover, Gmail, Search - **Lower CPA**: Video ads often convert better **When to Ask:** - AFTER discovering existing assets - AFTER user uploads images - BEFORE calling create_pmax_campaign **What to Say:** "I've prepared your images. Would you like to add YouTube videos to this campaign? Videos can significantly improve performance (higher CTR and engagement). They're optional but recommended. If yes: - You'll need videos uploaded to YouTube (public or unlisted) - Minimum 10 seconds duration - I can validate them for you If no: - We can proceed with images only - You can add videos later if needed" **How to Include Videos:** 1. **User provides YouTube video URL or ID** - Example: "https://youtu.be/eIZtladpm6c" - Example: "eIZtladpm6c" 2. **You validate it** ``` Call: validate_video Arguments: { "video_url_or_id": "eIZtladpm6c", "platform": "pmax" } ``` 3. **Include in campaign** - Add `youtube_video_ids` parameter: `["eIZtladpm6c"]` - Can include up to 5 videos **Video Specifications:** - **Aspect Ratios**: Landscape (16:9), Square (1:1), Vertical (9:16) - **Duration**: Minimum 10 seconds (no maximum) - **Maximum**: 5 videos per campaign - **Source**: Must be on YouTube (public or unlisted, NOT private) - **Validation**: Happens via Google Ads API during campaign creation **If user doesn't have videos:** - Proceed without them (campaigns work fine without videos) - Mention they can add videos later - Note: Google may auto-generate videos from images if none provided **STEP 4: Call create_pmax_campaign** After you have ALL details: - Validate character counts yourself BEFORE calling - Call create_pmax_campaign with complete payload - Wait for response (may take 15-30 seconds) **STEP 5: Handle Response** **If SUCCESS:** - Celebrate with user! 🎉 - Show campaign ID, name, budget, status - Explain campaign starts PAUSED for safety - 🔴 **IMMEDIATELY proceed to STEP 6 (Extensions)** — do NOT stop here! **If FAILURE:** 1. **Asset Bundle Expired:** - Error: "Asset bundle not found or expired" - Action: Guide user to re-upload images - Call validate_and_prepare_assets again 2. **Character Limit Errors:** - Error: "Headline exceeds 30 characters" - Action: Shorten the text and try again - Show user which field caused the error 3. **Google Ads API Errors:** - Domain not verified - Budget too low - Account suspended - Action: Explain error clearly, provide troubleshooting steps 4. **Authentication Errors:** - Error: "No Google Ads account connected" - Action: Guide user to connect their Google Ads account 🔴 **STEP 6: MANDATORY — Add Extensions After Creation** After the campaign is successfully created, you MUST: 1. Crawl the user's website to gather relevant page links, features, and service categories 2. Add sitelinks: at least 4 links to key pages (add_sitelinks tool) 3. Add callout extensions: 4-6 business highlights (add_callout_extensions tool) 4. Add structured snippets: categorized features (add_structured_snippets tool) 5. Verify with list_campaign_extensions to confirm all extensions are attached Extensions are FREE and increase ad visibility by 15-25%. NEVER skip this step. **DO NOT:** - Retry automatically on failure - Call multiple times for same campaign - Skip collecting user's campaign details - Proceed without valid asset_bundle_id - Skip adding extensions after campaign creation **Campaign Creation Best Practices:** 🔴 **PRE-STEP: ALWAYS Discover Assets First** - Before ANY PMAX campaign, call discover_existing_assets - Show user what assets were found (images, logos with dimensions) - Ask: "Would you like to reuse these existing assets, upload new ones, or mix both?" - Based on answer: - Reuse → Use existing_image_ids in create_pmax_campaign - Upload new → Use validate_and_prepare_assets → asset_bundle_id - Mix both → Use both parameters (hybrid mode) - 🚫 NEVER skip this step 1. **Research First:** - Understand the business, products, audience - Review website messaging - Identify key selling points 2. **Strategic Ad Copy:** - Use action verbs - Include numbers/stats if available - Highlight benefits over features - Create urgency when appropriate - Match brand voice 3. **Quality Over Quantity:** - Better to have 5 great headlines than 15 mediocre ones - Each headline should be unique and valuable - Avoid repetition 4. **User Safety:** - Confirm budget with user before creating - Explain campaigns start PAUSED - Remind them this costs real money **Example Complete Flow:** User: "Create a PMax campaign for my luxury watch store" You: "I'll help you create a PMax campaign! First, let me check if you have any existing assets we can reuse." [Call discover_existing_assets(target_domain="luxurywatches.com")] [Returns: 8 images found] You: "Great news! I found 8 validated images from your previous campaigns: - 4 landscape images (1200x628) - 2 square images (1200x1200) - 2 logo images (1200x1200) Would you like to: A) Reuse these existing images (saves time, consistent branding) B) Upload new images C) Mix both (reuse some + add new ones)" [User chooses A - Reuse] You: "Perfect! Now I need a few details: 1. What daily budget would you like? (minimum $10, recommended $50+) 2. What's your landing page URL? 3. What locations should we target? (e.g., 'Bay Area', 'San Francisco', 'United States') I'll create compelling headlines and descriptions based on your luxury watch business." [User provides budget: $75, URL: https://luxurywatches.com, Location: Bay Area] You: "Great! Here's what I'll create: **Campaign Name:** Premium Watches Campaign 2025 **Budget:** $75/day **Landing Page:** https://luxurywatches.com **Locations:** Bay Area (targeted precisely) **Headlines I've generated:** - Premium Luxury Watches - Certified Authentic - Free Worldwide Shipping [...12 more] **Descriptions:** - Shop authentic Swiss timepieces with lifetime warranty and expert curation. - Discover premium watches from top brands. Free shipping. 30-day returns. [...2 more] **Using existing images:** 8 validated images (reuse mode) Ready to create this campaign? (It will start PAUSED so you can review first)" [User confirms] [Call create_pmax_campaign with existing_image_ids from discovery] **Returns:** - Campaign ID, name, status - Asset group summary - Next steps for activation **Execution Time:** 15-30 seconds (direct backend API call) **Authentication:** Required (MCP OAuth 2.1) **CRITICAL REMINDERS:** - Asset bundle expires after 1 hour - Campaign starts PAUSED for user safety - This costs real money - be transparent - Never retry on failure - report error to user - Provide excellent user experience throughout

{
  "arguments": {
    "campaign_name": "string",
    "budget_daily": 1.0,
    "asset_bundle_id": "string",
    "existing_image_ids": [
      "customers/1234567890/assets/12345678901",
      "customers/1234567890/assets/12345678902"
    ],
    "headlines": [
      "string"
    ],
    "descriptions": [
      "string"
    ],
    "business_name": "string",
    "final_url": "string"
  }
}

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for create_pmax_campaign)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "create_pmax_campaign"
}

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "create_pmax_campaign"
}

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "create_pmax_campaign",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}