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](https://app.hyperfx.ai/mcp) - **TikTok Marketing integration connected** (TikTok Ads Manager / Business Center) at [https://app.hyperfx.ai/apps](https://app.hyperfx.ai/apps). If `search("tiktok_ads_advertiser_accounts_list")` does not find `tiktok_ads_advertiser_accounts_list`, stop and tell the user to enable Hyper MCP and connect 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: | Surface | Find a tool | Run it | | --- | --- | --- | | MCP client (Claude, Cursor, Codex, ChatGPT) | `search("<what you want to do>")`, then `describe("<name>")` | `call("<name>", {...})` | | Hyper CLI | `hyperai search "<what you want to do>"`, then `hyperai describe <name>` | `hyperai call <name> --json '{...}'` | If a tool is not found, its integration is not connected or not enabled for the workspace: stop and tell the user which integration to connect. ## Out of scope — defer to other skills - **Organic TikTok posting** (videos, photos, carousels — no ad spend) → [`tiktok`](../tiktok). - **Creative generation** (ad copy, images) → [`ad-creative-generation`](../ad-creative-generation); video creatives → [`video-generation`](../video-generation). - **Cross-platform campaign launches** → use this skill for TikTok, then invoke `meta-ads` / `google-ads` separately. ## Tool surface | Tool | Purpose | | --- | --- | | `tiktok_ads_advertiser_accounts_list` | Discovery: list advertiser IDs available to the connected user. | | `tiktok_ads_campaigns_get`, `tiktok_ads_campaigns_create`, `tiktok_ads_campaigns_update`, `tiktok_ads_campaigns_status_update` | Campaign lifecycle. | | `tiktok_ads_ad_groups_list`, `tiktok_ads_ad_groups_create`, `tiktok_ads_ad_groups_update`, `tiktok_ads_ad_groups_status_update` | Ad group lifecycle. | | `tiktok_ads_list`, `tiktok_ads_create`, `tiktok_ads_ad_status_update`, `tiktok_ads_update` | Ad lifecycle and supported incremental content changes. Describe the selected tool before editing; Smart+ ads use their dedicated tools. | | `tiktok_ads_videos_upload`, `tiktok_ads_videos_get`, `tiktok_ads_videos_search` | Video creative upload + lookup. | | `tiktok_ads_integrated_reports_get` | Performance reporting. | | `tiktok_ads_custom_audiences_create`, `tiktok_ads_custom_audiences_list`, `tiktok_ads_lookalike_audiences_create` | Audience management (optional). | ## 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. ```python tiktok_ads_benchmarks_get( advertiser_id="123456789", dimensions=["industry"], filtering={"industry": "292801"} # industry code from tiktok_ads_advertiser_accounts_list ) ``` ### Available Campaign Objectives | Objective | Best For | Key Requirements | | --- | --- | --- | | `TRAFFIC` | Drive website visits | `promotion_type="WEBSITE"`, CPC billing | | `CONVERSIONS` | Drive purchases / leads | Pixel ID, conversion event tracking | | `REACH` | Brand awareness | Manual placement only, CPM billing, frequency cap | | `APP_PROMOTION` | App installs | App ID, app store URL | | `VIDEO_VIEW` | Video engagement | Video creative assets | ## 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`. ```python 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:** ```python 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:** ```python 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. ```python 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 ```python 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 | Error | Solution | | --- | --- | | Budget must be at least $50 | TikTok enforces a MINIMUM $50 for campaign budgets. | | Start time in past | Use a future date in `schedule_start_time` and the **current** year. | | TikTok API rejects `optimize_goal` in some contexts | Both `optimize_goal` and `optimization_goal` exist in the schema, but prefer `optimization_goal` — it is the field TikTok validates in most objective types. | | Only supports manual placement | REACH requires `placement_type="PLACEMENT_TYPE_NORMAL"`. | | Bid needs to be greater than $0 | Set `bid_price` > 0. | | Please set frequency cap | REACH requires both `frequency` and `frequency_schedule`. | ### 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 ```python 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.