tiktok-ads

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_get_advertiser_accounts is not in the tool list, stop and tell the user to enable Hyper MCP and connect TikTok Marketing.

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_get_advertiser_accounts() 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_ad_benchmarks 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_ad_benchmarks(
    advertiser_id="123456789",
    dimensions=["industry"],
    filtering={"industry": "292801"}  # industry code from tiktok_get_advertiser_accounts
)

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_create_campaign(
    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_create_adgroup(
    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_create_adgroup(
    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_ad_video_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_ad_video_search to find existing videos by name or tiktok_ad_video_info to fetch metadata for a known video ID.

Step 4: Create the Ad

tiktok_create_ad(
    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_report_integrated_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.