openai-ads

OpenAI Ads Campaigns

Strategic guide for managing the OpenAI Advertiser API. All operations go through https://api.ads.openai.com/v1.

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• OpenAI Ads integration connected (an OpenAI Ads API key, scoped to one ad account) at https://app.hyperfx.ai/apps.

If openai_ads_ad_accounts_get is not in the tool list, stop and tell the user to enable Hyper MCP and connect OpenAI Ads. After connecting, openai_ads_health_check() verifies the key — if connected=false, the API key is missing, invalid, or expired.

Out of scope — defer to other skills

• Creative generation (ad imagery, copy) → `ad-creative-generation` / `image-generation`.
• Cross-platform campaign launches → use this skill for OpenAI Ads, then invoke meta-ads / google-ads separately.

Critical Rules

CRITICAL: Auth is bearer API-key auth, not OAuth. One Ads API key is scoped to exactly one ad account. There is no list ad accounts endpoint; openai_ads_ad_accounts_get returns the connected account for that key.

CRITICAL: All money values on inputs are integer micros. $1.00 = 1_000_000 micros. $50/day = 50_000_000. The daily_spend_limit_micros minimum is 1_000_000 ($1). The ad group max_bid_micros is capped at 100_000_000 ($100). Insights responses use plain floats in account currency, not micros.

CRITICAL: Always create campaigns, ad groups, and ads with status="paused". Surface what was created to the user, then activate using the dedicated activate endpoint after approval.

CRITICAL: Ads have review_status. New ads enter in_review and will not serve until review_status="approved", even if status="active".

CRITICAL: chat_card creatives require target_url and file_id. Upload the image first via openai_ads_images_upload, then pass the returned file_id to openai_ads_create. PNG, 1024x1024, <= 1 MB.

IMPORTANT: Creative types are chat_card and product_ad_template. Product-ad templates get image and destination URL from the selected product feed item, so they do not require file_id or target_url.

IMPORTANT: Campaign bidding_type can be impressions or clicks. Ad group billing_event_type can be impression or click.

Tool surface

Phase 1: Account Discovery

Run these after connect:

openai_ads_ad_accounts_get()
openai_ads_campaigns_list(limit=100)
openai_ads_list_custom_audiences(limit=100)
openai_ads_list_conversion_event_settings(limit=100)

The connect-time context builder may have already populated a cached snapshot. Prefer:

openai_ads_caches_get()

If success=False because the cache is empty, refresh once:

openai_ads_caches_refresh()

Phase 2: Plan and Confirm

Before creating anything, confirm with the user:

• Objective in plain language.
• Daily and/or lifetime budget in account currency.
• Target geos: simple country codes like ["US", "GB"], or location IDs from openai_ads_search_geo_locations.
• Any custom audiences to include or exclude.
• Whether this is a normal chat_card campaign or a product-feed campaign.
• Headline (title, <= 50 chars), body (<= 100 chars), and click-through URL for chat_card.
• One image asset for chat_card, either a public URL or a base64 blob.
• Max bid in micros (max_bid_micros; for example 2_000_000).
• Optional context_hints, short natural-language phrases that describe when the ad should show.
• Optional conversion event setting IDs to attach to the campaign.

If anything is missing, ask. Do not invent budgets, geos, or copy.

All reference files live in `references/`. Read them at references/<file> (e.g. references/campaign-creation.md).

Routing table

Safety Rules

Never:

• Pass dollar amounts directly. All money inputs are micros.
• Activate a campaign, ad group, ad, or account without explicit user approval.
• Skip image upload for a chat_card; it needs a real file_id.
• Use geo exclusions; use included geos and audience exclusions instead.
• Assume an ad is delivering just because status="active". Always check review_status.
• Treat archive as reversible.
• Promise paid traffic on a new ad. New ads sit in review_status="in_review" until OpenAI approves them.