create_display_campaign

POST https://api.adspirer.ai/api/v1/tools/create_display_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 Create a Google **Display** campaign with a Responsive Display Ad on the Google Display Network (GDN). 🛑 **STOP — IMAGES ARE MANDATORY. ASK THE USER FIRST.** 🛑 A Display campaign cannot be created without images. Before calling this tool you MUST have: - At least 1 landscape image URL (1.91:1 aspect ratio, min 600×314, max 5 MB) - At least 1 square image URL (1:1 aspect ratio, min 300×300, max 5 MB) If the user has not provided image URLs, **ASK THEM** — do not invent URLs, do not guess Wikipedia/stock-photo URLs (they 403 to server fetches), do not pass `marketing_images: null`. Suggest the user upload to a host like postimages.org and paste the direct .jpg/.png URLs. ✅ **STRONGLY RECOMMENDED — pre-validate first**: call `validate_and_prepare_assets` with the user's image URLs BEFORE calling this tool. It checks aspect ratio, dimensions, file size, and content-type, then returns an `asset_bundle_id` you can pass here. This avoids a Google Ads API rejection mid-create (e.g., "aspect ratio doesn't match expected"). **When to use this tool:** - User explicitly asks for "Display campaign", "Google Display Network", "GDN", "banner ads", or "display ads" - User wants visual/banner placements across millions of websites, mobile apps, YouTube, and Gmail (display slots only) - User wants Smart Display (Google-managed automation): pass smart_display=true and bidding_strategy='TARGET_CPA' **When NOT to use:** - User wants text ads in Google Search → use create_search_campaign - User wants cross-channel (YouTube + Discover + Gmail + Display together) → use create_demandgen_campaign - User wants a PMax-like multi-channel approach → use create_pmax_campaign **Step-by-step workflow:** 1. Ask user for: budget, landing URL, business name, **AT LEAST 1 LANDSCAPE + 1 SQUARE IMAGE URL**, headlines (1-5 @ 30 chars), long headline (1 @ 90 chars), descriptions (1-5 @ 90 chars) 2. Resolve any free-text locations via `resolve_google_locations` first (returns exact `geoTargetConstants/<id>` to avoid ambiguity) 3. Pre-validate the image URLs with `validate_and_prepare_assets` → use the returned `asset_bundle_id` (recommended) OR pass the URLs directly as `marketing_images` / `square_marketing_images` (we'll validate before upload, but the API may still reject for subtle aspect-ratio mismatches) 4. Optional: logos, YouTube videos, audience/topic/placement targeting 5. Call `create_display_campaign` with the full payload (must include images one way or another) 6. After success, add extensions: `add_sitelinks`, `add_callout_extensions`, `add_structured_snippets` **Targeting surfaces supported (ad-group level, ignored for Smart Display):** - audience_segments: user_interests (affinity/in-market via search_audiences), custom_audiences, user_lists, combined_audiences - topics: topic constants - managed_placements: specific websites/apps/YouTube channels/videos - display_keywords: contextual keywords (always BROAD match on Display) - demographics: age/gender/parental/income (exclude-the-inverse pattern) **Bidding strategies:** - MAXIMIZE_CLICKS (default, works without conversion tracking) - MAXIMIZE_CONVERSIONS (needs conversion tracking) - TARGET_CPA (needs target_cpa + conversion tracking) - TARGET_ROAS (needs target_roas + conversion tracking) - MANUAL_CPC (enhanced CPC, needs cpc_bid in account currency) - MANUAL_CPM (viewable CPM, needs cpm_bid in account currency) **Smart Display (smart_display=true):** - sub_type=DISPLAY_SMART_CAMPAIGN (Google-managed) - Bidding MUST be TARGET_CPA - Manual audience/topic/placement/keyword/demographic inputs are REJECTED - Account needs conversion tracking with enough history (≥50 Display conversions or ≥100 Search conversions in last 30 days) **Character limits (strictly enforced — validation will reject before hitting the API):** - Headlines: MAX 30 chars each (1-5) - Long headline: MAX 90 chars (exactly 1) - Descriptions: MAX 90 chars each (1-5) - Business name: MAX 25 chars - Price prefix: MAX 10 chars - Promo text: MAX 20 chars **Image requirements:** - Landscape (1.91:1): min 600x314, max 5MB, 1-15 images - Square (1:1): min 300x300, max 5MB, 1-15 images - Landscape logo (4:1): min 512x128, up to 5 (optional) - Square logo (1:1): min 128x128, up to 5 (optional) **Safety:** - Campaigns always start PAUSED (user must review + enable manually in Google Ads UI) - Never retry on failure — surface the error to the user **Execution time:** 10-20 seconds (atomic mutate: budget + campaign + ad group + all criteria + assets + ad)

{
  "arguments": {
    "campaign_name": "string",
    "budget_daily": 1.0,
    "final_url": "https://example.com",
    "business_name": "string",
    "headlines": [
      "string"
    ],
    "long_headline": "string",
    "descriptions": [
      "string"
    ],
    "marketing_images": [
      {}
    ],
    "square_marketing_images": [
      {}
    ],
    "logo_images": [
      {}
    ],
    "square_logo_images": [
      {}
    ],
    "existing_images": {},
    "asset_bundle_id": "string"
  }
}

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for create_display_campaign)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "create_display_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_display_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_display_campaign",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}