TikTok Ads

Strategic guide for managing TikTok advertising campaigns. Research deeply, validate parameters carefully, and guide users through the platform's strict objective-specific requirements.

This skill is for paid TikTok ads (the TikTok Marketing API surface).

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• TikTok Marketing integration connected (TikTok Ads Manager / Business Center) at https://app.hyperfx.ai/apps.

If tiktok_ads_advertiser_accounts_list is not found, the integration to connect is TikTok Marketing.

How to run the tools in this skill

Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:

If a tool is not found: in Hyper chat, find its toolkit id with discover_toolkits and pass it to enable_toolkit. On an MCP client or the CLI, tell the user which integration to connect in Hyper.

Out of scope — defer to other skills

• Organic TikTok posting (videos, photos, carousels — no ad spend) → tiktok.
• Creative generation (ad copy, images) → ad-creative-generation; video creatives → video-generation.
• Cross-platform campaign launches → use this skill for TikTok, then invoke meta-ads / google-ads separately.

Tool surface

Phase 1: Account Discovery

Initial Setup

• Use tiktok_ads_advertiser_accounts_list() to get advertiser IDs.
• If multiple accounts: ask the user to select one.
• If single account: inform the user and proceed.

Bid Benchmarks (optional but recommended)

Before setting bid prices, call tiktok_ads_benchmarks_get to retrieve industry-specific CPM/CPC benchmarks. This prevents using placeholder values that may be too low to win auctions or too high for the user's budget.

tiktok_ads_benchmarks_get(
    advertiser_id="123456789",
    dimensions=["industry"],
    filtering={"industry": "292801"}  # industry code from tiktok_ads_advertiser_accounts_list
)

Available Campaign Objectives

Phase 2: Campaign Creation

Step 1: Create Campaign

Budget Requirements:

• MINIMUM $50 for campaign-level budgets (TikTok requirement).
• budget_mode: BUDGET_MODE_INFINITE (CBO), BUDGET_MODE_DAY, or BUDGET_MODE_TOTAL.

tiktok_ads_campaigns_create(
    advertiser_id="123456789",
    campaign_name="Summer Sale 2026",
    objective_type="TRAFFIC",
    budget_mode="BUDGET_MODE_DAY",
    budget=50.0,  # MINIMUM $50/day
    operation_status="ENABLE"
)

Step 2: Create Ad Group

ALWAYS REQUIRED Parameters:

• advertiser_id, campaign_id, adgroup_name.
• location_ids (e.g., ["6252001"] for US).
• schedule_type and schedule_start_time (MUST be a future date).
• billing_event (CPC, CPM, OCPM).
• budget_mode (REQUIRED for ad groups).

For TRAFFIC Campaigns:

tiktok_ads_ad_groups_create(
    advertiser_id="123456789",
    campaign_id="1234567890123456",
    adgroup_name="Website Traffic - Summer Sale",
    location_ids=["6252001"],  # US
    schedule_type="SCHEDULE_FROM_NOW",
    schedule_start_time="2026-06-01 00:00:00",  # FUTURE DATE
    billing_event="CPC",
    budget_mode="BUDGET_MODE_DAY",
    budget=30.0,
    promotion_type="WEBSITE",        # REQUIRED for TRAFFIC
    optimization_goal="CLICK",       # REQUIRED (correct spelling)
    bid_price=0.50,
    placement_type="PLACEMENT_TYPE_AUTOMATIC",
    operation_status="ENABLE"
)

For REACH Campaigns:

tiktok_ads_ad_groups_create(
    advertiser_id="123456789",
    campaign_id="1234567890123456",
    adgroup_name="Brand Awareness US",
    location_ids=["6252001"],
    schedule_type="SCHEDULE_FROM_NOW",
    schedule_start_time="2026-06-01 00:00:00",
    billing_event="CPM",                       # REQUIRED for REACH
    budget_mode="BUDGET_MODE_DAY",
    budget=30.0,
    optimization_goal="REACH",
    placement_type="PLACEMENT_TYPE_NORMAL",    # REQUIRED — automatic NOT supported
    placements=["PLACEMENT_TIKTOK"],           # REQUIRED
    bid_price=2.0,                             # REQUIRED
    frequency=3,                               # REQUIRED
    frequency_schedule=7,                      # REQUIRED
    operation_status="ENABLE"
)

Step 3: Upload Creative Assets

Upload one video per creative variant. Capture the returned video_id — you'll need it in Step 4.

video_response = tiktok_ads_videos_upload(
    advertiser_id="123456789",
    video_file=video_data,
    upload_type="UPLOAD_BY_FILE"
)
video_id = video_response["data"]["video_id"]

Already-uploaded videos can be reused. Use tiktok_ads_videos_search to find existing videos by name or tiktok_ads_videos_get to fetch metadata for a known video ID.

Step 4: Create the Ad

tiktok_ads_create(
    advertiser_id="123456789",
    adgroup_id="1234567890123456",
    ad_name="Summer Sale - Hero Video",
    identity_type="CUSTOMIZED_USER",   # or "AUTH_CODE" for TikTok Account spark ads
    identity_id="<advertiser_identity_id>",
    ad_format="SINGLE_VIDEO",
    video_id=video_id,
    ad_text="Limited-time summer drop. Shop now.",
    landing_page_url="https://example.com/summer",
    call_to_action="SHOP_NOW",
    operation_status="DISABLE"        # create paused, enable after review
)

Always create ads paused (operation_status="DISABLE") and only flip them to ENABLE once the user has reviewed.

Critical Parameter Rules

Common Errors & Solutions

Parameter Dependencies

TRAFFIC objective requires:

• promotion_type="WEBSITE".
• optimization_goal="CLICK".
• billing_event="CPC".
• bid_price > 0.

REACH objective requires:

• optimization_goal="REACH".
• billing_event="CPM".
• placement_type="PLACEMENT_TYPE_NORMAL".
• placements array (e.g., ["PLACEMENT_TIKTOK"]).
• bid_price > 0.
• frequency and frequency_schedule.

CONVERSIONS objective requires:

• A connected TikTok Pixel and a configured conversion event.
• optimization_goal="CONVERT" (or VALUE for value-based).
• billing_event="OCPM".
• pixel_id and external_action set on the ad group.

Reporting

tiktok_ads_integrated_reports_get(
    advertiser_id="123456789",
    report_type="BASIC",
    data_level="AUCTION_AD",
    dimensions=["ad_id"],   # ID-based only — NOT names
    start_date="2026-04-01",
    end_date="2026-04-30",
    metrics=["impressions", "clicks", "ctr", "spend", "cpc", "cpm"],
    page_size=20
)

Reporting Rules:

• With the stat_time_day dimension: maximum 30-day range per call.
• Use ID-based dimensions only (ad_id, campaign_id, adgroup_id — not names).
• Conversion metrics (conversion, cost_per_conversion, conversion_rate, etc.) require a connected pixel and a configured conversion event.
• data_level must match the dimension granularity: AUCTION_AD with ad_id, AUCTION_ADGROUP with adgroup_id, AUCTION_CAMPAIGN with campaign_id.

Safety Rules

Never:

• Set ad group budgets below $20/day without warning the user.
• Schedule a campaign with a past schedule_start_time (TikTok rejects this with a confusing error).
• Mix REACH ad groups with PLACEMENT_TYPE_AUTOMATIC — it will silently fail validation.
• Create ads with operation_status="ENABLE" before the user has reviewed creative + targeting.
• Run reports with name-based dimensions — TikTok only accepts ID dimensions.