跳到主要内容
Tecrübetecrube.com
Assistant tools · Setup and campaigns

TikTok Ads tools

Campaign, ad group and ad management, video/image upload, audiences and performance reports.

Tool names and descriptions are generated straight from the server code; the descriptions are the original English text the assistant sees.

Read tools27 tools

list_tiktok_advertisers

读取1 credits

TikTok ad accounts (advertisers) reachable with the connected TikTok Ads token: id, name, currency, timezone, status, and which one is selected for the current project. Read only; returns connected=false when no account is linked.

This tool takes no parameters.

list_tiktok_campaigns

读取1 credits

TikTok campaigns of the connected ad account: campaign_id, name, objective_type, budget, budget_mode, operation_status (on/off switch) and secondary_status (TikTok's delivery status). Use campaign_id values for the other tiktok tools.

ParameterTypeDescription
campaign_idsOptionalarray<string>—
statusOptionalSTATUS_DELIVERY_OK | STATUS_NOT_DELIVERY | STATUS_DISABLE | STATUS_DELETE | STATUS_NOT_DELETE | STATUS_ALLprimary status filter: STATUS_DELIVERY_OK (delivering), STATUS_NOT_DELIVERY, STATUS_DISABLE (paused), STATUS_DELETE, STATUS_NOT_DELETE (default: all but deleted), STATUS_ALL. Omit to list all.
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_ad_groups

读取1 credits

TikTok ad groups with budget, bid, optimisation goal, targeting (locations, ages, gender, languages, interests, audiences), placements, schedule and dayparting.

ParameterTypeDescription
campaign_idsOptionalarray<string>—
adgroup_idsOptionalarray<string>—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_ads

读取1 credits

TikTok ads: ad_id, name, ad group, status (operation_status, secondary_status), format, text, video_id, landing page, call to action. Ads that failed or only partly passed review also carry review: TikTok's review status, rejection reasons and suggestion, and the placements, locations and ages they are barred from.

ParameterTypeDescription
campaign_idsOptionalarray<string>—
adgroup_idsOptionalarray<string>—
ad_idsOptionalarray<string>—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

tiktok_performance_report

读取2 credits

TikTok performance by campaign, ad group or ad for a date range: spend, impressions, clicks, CTR, CPM, CPC, conversions, cost per conversion, conversion rate, ROAS where available; optional daily breakdown and totals. Real data only; connected=false when no account.

ParameterTypeDescription
levelOptionalcampaign | ad_group | ad—
daysOptionalinteger (1–365)—
start_dateOptionalstring—
end_dateOptionalstring—
dailyOptionalbooleanone row per day (stat_time_day)
campaign_idsOptionalarray<string>—
adgroup_idsOptionalarray<string>—
ad_idsOptionalarray<string>—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_audiences

读取1 credits

Custom and lookalike audiences of the TikTok ad account: audience_id, name, type, size (cover_num), validity. Use audience_ids in update_tiktok_ad_group to assign them.

ParameterTypeDescription
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_videos

读取1 credits

Videos in the TikTok ad account's asset library: video_id, file name, duration, size, preview and cover URLs. Use video_id in create_tiktok_ad or create_tiktok_whatsapp_campaign; add new videos from a public URL with upload_tiktok_video.

ParameterTypeDescription
video_idsOptionalarray<string>—
limitOptionalinteger (1–500)newest first (default 500)
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

get_tiktok_video_cover

读取1 credits

Suggested cover frames for a TikTok library video (file/video/suggestcover): id, preview url (valid one hour), size. Upload the chosen url with upload_tiktok_image to use it as the ad cover (image_ids). Read only.

ParameterTypeDescription
video_idRequiredstring—
countOptionalinteger (1–10)—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

search_tiktok_targeting

读取1 credits

Turn targeting names into TikTok ids: interest (tool/interest_category → interest_category_ids), behavior (tool/action_category → actions[].action_category_ids), interest_keyword (tool/interest_keyword/recommend → interest_keyword_ids), location (tool/targeting/search → location_ids / zipcode_ids, cities and provinces), region (tool/region → targetable countries for the objective). Read only.

ParameterTypeDescription
typeRequiredinterest | behavior | interest_keyword | location | region—
queryRequiredstringname to look up, e.g. fashion, moda, Istanbul, Turkey
languageOptionalstringnames language for interest/behavior/interest_keyword, e.g. tr, en (default: conversation language)
objective_typeOptionalstringfor location/region: campaign objective, default TRAFFIC; LEAD_GENERATION for WhatsApp ads
promotion_typeOptionalstringfor location/region; default WEBSITE, or LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE with LEAD_GENERATION
placementsOptionalarray<string>default PLACEMENT_TIKTOK
region_codesOptionalarray<string>location: filter by country code, e.g. TR
geo_typesOptionalarray<string>location: COUNTRY | PROVINCE | CITY | DISTRICT | DMA | ZIP_CODE
limitOptionalinteger (1–100)—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_identities

读取1 credits

Ad identities of the TikTok ad account (identity/get): identity_id, identity_type, display name, username, whether posts can be pulled. Pass identity_id/identity_type to create_tiktok_ad or list_tiktok_posts. Read only.

ParameterTypeDescription
identity_typeOptionalCUSTOMIZED_USER | AUTH_CODE | TT_USER | BC_AUTH_TT—
identity_bc_idOptionalstringrequired with BC_AUTH_TT
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_pixels

读取1 credits

TikTok conversion pixels of the ad account (pixel/list): pixel_id, pixel_code, name, setup mode and tracked events. Use pixel_id for conversion ad groups and pixel_code for send_tiktok_conversion_event. Read only.

ParameterTypeDescription
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_auto_messages

读取1 credits

Welcome message templates for TikTok Direct Message ads (creative/auto_message/get): auto_message_id, title, greeting, suggested questions and review status. Pass auto_message_id to create_tiktok_ad. Read only.

ParameterTypeDescription
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_lead_forms

读取1 credits

TikTok instant lead forms of the ad account (page/get, LEAD_GEN): page_id, title, status, created/updated/published time and preview URL. Read only.

ParameterTypeDescription
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

get_tiktok_lead_form_fields

读取1 credits

Question fields of a TikTok instant lead form (page/field/get): field keys, labels and types plus form metadata, to read collected lead answers correctly. Read only.

ParameterTypeDescription
page_idRequiredstringinstant form id from list_tiktok_lead_forms
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

download_tiktok_leads

读取2 credits

Download the leads collected by a TikTok instant form or lead ad (a ZIP file is unpacked to its CSV). Opens the download task, polls it briefly and, once ready, returns a privacy-safe summary: total rows, question names, and the first rows (limit, default 20) with lead id, created time, ad, ad group, campaign and form ids plus MASKED answers (names cut to initials; e-mails, phone numbers and IBANs masked). The full unmasked CSV is stored in the account's private file area and returned only as download_url, a signed link valid for 15 minutes (the stored file is kept for 30 days, then deleted): give the link to the user, never paste the file content into the chat; if the file cannot be stored, only the masked summary is returned. If TikTok is still preparing the file it returns task_id: call again with the same page_id/ad_id and that task_id. region: where the ads ran (eu = EEA/Switzerland/UK, us, other). Ad account admins only. Use the data only under the consent given on the form. Read only.

ParameterTypeDescription
page_idOptionalstringinstant form id from list_tiktok_lead_forms (or give ad_id)
ad_idOptionalstringlead ad id; downloads the leads of that ad instead of a form
task_idOptionalstringtask id returned by an earlier call that was still RUNNING
regionOptionaleu | us | otherwhere the ads targeted: eu = EEA/Switzerland/UK, us = United States, other (default) = everywhere else
limitOptionalinteger (1–100)rows in the masked preview (default 20); the full list is only in the download file
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_creative_portfolios

读取1 credits

Creative portfolios of the TikTok ad account (creative/portfolio/list): portfolio id, type (display card, download card, gift code…), preview URL and main settings. Read only.

ParameterTypeDescription
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_gmv_max_stores

读取1 credits

TikTok Shop stores linked to the ad account (gmv_max/store/list) with GMV Max availability, status, role, authorising Business Center and targetable regions. Read only.

ParameterTypeDescription
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_smart_plus

读取1 credits

Smart+ (automated) campaigns, ad groups or ads of the TikTok ad account (smart_plus/*/get). These are not returned by list_tiktok_campaigns / _ad_groups / _ads. Read only.

ParameterTypeDescription
levelOptionalcampaign | adgroup | addefault campaign
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_posts

读取1 credits

Organic TikTok posts of a linked TikTok account identity (identity/video/get) that can run as Spark Ads: tiktok_item_id, text, status, duration, cover and ad authorisation status. Read only.

ParameterTypeDescription
identity_idRequiredstring—
identity_typeOptionalTT_USER | BC_AUTH_TT | AUTH_CODEdefault TT_USER
identity_bc_idOptionalstringrequired with BC_AUTH_TT
limitOptionalinteger (1–100)default 20
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

tiktok_recommendations

读取2 credits

TikTok's own ad group diagnoses and suggestions (tool/diagnosis/get): creative fatigue, bid and budget suggestions with estimated uplift, and event tracking problems. Read only; apply with the update tools.

ParameterTypeDescription
adgroup_idsOptionalarray<string>up to 20; default: TikTok picks the ad groups with diagnoses
issue_categoriesOptionalarray<string>CREATIVE | BID_AND_BUDGET | EVENT_TRACK
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

tiktok_report_query

读取2 credits

Free-form TikTok report (report/integrated/get): any supported metrics and dimensions, report type, data level, date range or lifetime and filters. Rows are returned exactly as TikTok computes them. Read only.

ParameterTypeDescription
metricsRequiredarray<string>TikTok metric names, e.g. spend, impressions, clicks, conversion, complete_payment_roas
dimensionsRequiredarray<string>e.g. campaign_id, adgroup_id, ad_id, stat_time_day, country_code, gender, age
report_typeOptionalBASIC | AUDIENCE | PLAYABLE_MATERIAL | CATALOG | BC | TT_SHOP—
data_levelOptionalstringe.g. AUCTION_CAMPAIGN, AUCTION_ADGROUP, AUCTION_AD, AUCTION_ADVERTISER
daysOptionalinteger (1–365)—
start_dateOptionalstring—
end_dateOptionalstring—
lifetimeOptionalbooleanlifetime totals instead of a date range
filteringOptionalarray<object>TikTok filters: [{field_name, filter_type, filter_value}]
limitOptionalinteger (1–5000)—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

list_tiktok_business_centers

读取1 credits

TikTok Business Centers reachable with the connected token (bc/get): bc_id, name, company, status, currency, timezone and your role. Read only.

This tool takes no parameters.

list_tiktok_bc_advertisers

读取1 credits

Ad accounts inside a TikTok Business Center (bc/asset/get, ADVERTISER): advertiser id, name, account type, your role and verification status. Read only.

ParameterTypeDescription
bc_idOptionalstringBusiness Center id (list_tiktok_business_centers); optional when the token reaches a single Business Center

list_tiktok_bc_pixels

读取1 credits

Pixels held in a TikTok Business Center (bc/asset/get, PIXEL), across its ad accounts. Read only.

ParameterTypeDescription
bc_idOptionalstringBusiness Center id (list_tiktok_business_centers); optional when the token reaches a single Business Center

list_tiktok_asset_groups

读取1 credits

Asset groups of a TikTok Business Center (bc/asset_group/list): asset_group_id and name. Read only.

ParameterTypeDescription
bc_idOptionalstringBusiness Center id (list_tiktok_business_centers); optional when the token reaches a single Business Center

tiktok_advertiser_qualification

读取1 credits

Business qualifications in a TikTok Business Center (bc/advertiser/qualification/get): company name, verification status, owning ad account, linked account count and region. Read only.

ParameterTypeDescription
bc_idOptionalstringBusiness Center id (list_tiktok_business_centers); optional when the token reaches a single Business Center
advertiser_idOptionalstringkeep only qualifications owned by this ad account
verifiedOptionalbooleanfilter verified / unverified

tiktok_change_history

读取2 credits

Activity log of a TikTok Business Center (changelog/get): when, which activity type, operator id and the change text, newest first. Read only.

ParameterTypeDescription
bc_idOptionalstringBusiness Center id (list_tiktok_business_centers); optional when the token reaches a single Business Center
start_dateOptionalstringYYYY-MM-DD (UTC); default: last 7 days
end_dateOptionalstring—
daysOptionalinteger (1–365)—
activity_typeOptionalstringALL (default) | USER | ASSET | … as TikTok defines
limitOptionalinteger (1–500)—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tools24 tools

select_tiktok_advertiser

写入1 credits

Choose which TikTok ad account (advertiser) all further TikTok reads and writes use. Per project: with a non-default project selected only that project's advertiser is saved; in the default project the connection's selection changes. Local setting; nothing is changed on TikTok. Switching is always allowed; adding another advertiser on the platform is subject to the plan's ads.accounts.max limit (error=entitlement body with next_plan and upgrade_url).

ParameterTypeDescription
advertiser_idRequiredstring—

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

upload_tiktok_video

写入2 credits

Upload a video to the TikTok ad account's asset library from a public URL (file/video/ad/upload, UPLOAD_BY_URL). Applied directly when the user asks; the new video_id is returned in the action result.

ParameterTypeDescription
video_urlRequiredstringpublic http(s) URL of an mp4/mov/mpeg/avi file (ideally under 10 MB for URL uploads)
file_nameOptionalstring1-100 chars, unique in the account; default: URL file name + timestamp
auto_fixOptionalbooleanlet TikTok detect and fix low resolution / wrong aspect ratio
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

upload_tiktok_image

写入2 credits

Upload an image (image ad or video cover) to the TikTok asset library from a public URL (file/image/ad/upload, UPLOAD_BY_URL). Applied directly when the user asks; the image_id is returned in the action result.

ParameterTypeDescription
image_urlRequiredstringpublic http(s) URL of a JPG/PNG (max 1440x2560 total pixels)
file_nameOptionalstring1-100 chars, unique in the account; default: URL file name + timestamp
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

create_tiktok_campaign

写入2 credits

Create a TikTok campaign end to end: this call ALSO creates its ad group (pass its settings in ad_group and audience, and pass daily_budget; do not call create_tiktok_ad_group afterwards unless the user wants a second group), optionally the ad, all as a paused draft. WEB_CONVERSIONS campaigns are built with TikTok Upgraded Smart+ endpoints (budget on the campaign as a dynamic daily budget; the ad needs a linked TikTok account identity on TikTok placement). Writes a ledger draft and sends it to TikTok directly when the user asks (the result shows the preview); only with a connected account.

ParameterTypeDescription
nameRequiredstring—
objective_typeRequiredTRAFFIC | WEB_CONVERSIONS | REACH | VIDEO_VIEWS | LEAD_GENERATION | APP_PROMOTION | PRODUCT_SALES—
daily_budgetOptionalnumberaccount currency
budget_modeOptionalBUDGET_MODE_DAY | BUDGET_MODE_TOTAL | BUDGET_MODE_INFINITE—
goalOptionalstring—
pixel_idOptionalstring—
sales_destinationOptionalWEBSITE | APP | WEB_AND_APP | TIKTOK_SHOPPRODUCT_SALES campaigns only
audienceOptionalobjectcountries (ISO list), age_min, age_max, genders ([1]=male, [2]=female), tiktok_location_ids, tiktok_interest_ids
ad_groupOptionalobjectoptional ad group overrides; defaults: automatic placement, from now, smooth pacing
adOptionalobjectoptional ad; needs a library video_id
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

create_tiktok_ad_group

写入2 credits

Create a TikTok ad group under a campaign with budget, bid, targeting, placements, schedule and dayparting. Applied directly when the user asks; created paused unless operation_status=ENABLE.

ParameterTypeDescription
campaign_idRequiredstringTikTok campaign_id
nameRequiredstring—
budgetRequirednumberdaily budget, account currency
budget_modeOptionalBUDGET_MODE_DAY | BUDGET_MODE_TOTAL—
placement_typeOptionalPLACEMENT_TYPE_AUTOMATIC | PLACEMENT_TYPE_NORMAL—
placementsOptionalarray<string>PLACEMENT_TIKTOK | PLACEMENT_PANGLE | PLACEMENT_GLOBAL_APP_BUNDLE
promotion_typeOptionalstringWEBSITE | APP_ANDROID | APP_IOS | LEAD_GENERATION
app_idOptionalstringapp promotion only
identity_idOptionalstring—
identity_typeOptionalstringCUSTOMIZED_USER | TT_USER | BC_AUTH_TT
secondary_optimization_eventOptionalstring—
operation_statusOptionalENABLE | DISABLE—
optimization_goalOptionalstringCLICK | CONVERT | REACH | VIDEO_VIEW | LEAD | ENGAGEMENT
billing_eventOptionalstringCPC | CPM | OCPM | CPV
bid_typeOptionalstringBID_TYPE_NO_BID | BID_TYPE_CUSTOM
bid_priceOptionalnumber—
conversion_bid_priceOptionalnumber—
pacingOptionalPACING_MODE_SMOOTH | PACING_MODE_FAST—
location_idsOptionalarray<string>TikTok location ids (Turkey 298795, US 6252001, UK 2635167, DE 2921044)
age_groupsOptionalarray<string>AGE_13_17 | AGE_18_24 | AGE_25_34 | AGE_35_44 | AGE_45_54 | AGE_55_100
genderOptionalGENDER_UNLIMITED | GENDER_MALE | GENDER_FEMALE—
languagesOptionalarray<string>language codes, e.g. tr, en
interest_category_idsOptionalarray<string>—
operating_systemsOptionalarray<string>ANDROID | IOS
audience_idsOptionalarray<string>—
excluded_audience_idsOptionalarray<string>—
schedule_start_timeOptionalstringYYYY-MM-DD HH:MM:SS (UTC)
schedule_end_timeOptionalstringYYYY-MM-DD HH:MM:SS (UTC); sets SCHEDULE_START_END
daypartingOptionalstring336 chars of 0/1: 7 days x 48 half-hours starting Monday 00:00
pixel_idOptionalstring—
optimization_eventOptionalstringe.g. COMPLETE_PAYMENT, ON_WEB_CART, FORM
comment_disabledOptionalboolean—
share_disabledOptionalboolean—
search_result_enabledOptionalboolean—
interest_keyword_idsOptionalarray<string>from search_tiktok_targeting(type=interest_keyword)
actionsOptionalarray<object>behaviour targeting: [{action_scene: VIDEO_RELATED|CREATOR_RELATED|HASHTAG_RELATED, action_period: 0|7|15, video_user_actions: [...], action_category_ids: [ids from search_tiktok_targeting(type=behavior)]}]
deep_bid_typeOptionalstringe.g. DEFAULT, MIN, PACING, VO_MIN_ROAS
roas_bidOptionalnumber—
zipcode_idsOptionalarray<string>from search_tiktok_targeting(type=location)
device_model_idsOptionalarray<string>—
device_price_rangesOptionalarray<number>price range bounds, e.g. [0, 250]
network_typesOptionalarray<string>WIFI | 2G | 3G | 4G | 5G
carrier_idsOptionalarray<string>—
schedule_typeOptionalSCHEDULE_FROM_NOW | SCHEDULE_START_END—
saved_audience_idOptionalstring—
frequencyOptionalintegermax impressions per user within frequency_schedule days
frequency_scheduleOptionalintegerfrequency cap window in days
brand_safety_typeOptionalstringNO_BRAND_SAFETY | STANDARD_INVENTORY | LIMITED_INVENTORY | EXPANDED_INVENTORY
blocked_pangle_app_idsOptionalarray<string>—
targeting_expansionOptionalobjecte.g. {expansion_enabled: true}
household_incomeOptionalarray<string>e.g. TOP5, TOP10, TOP10_25, TOP25_50
spending_powerOptionalALL | HIGH—
exclude_age_under_eighteenOptionalboolean—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

create_tiktok_ad

写入2 credits

Create a TikTok ad in an ad group from a library video (or Spark post). Applied directly when the user asks.

ParameterTypeDescription
adgroup_idRequiredstring—
ad_nameOptionalstring—
ad_textRequiredstring1-100 chars
video_idOptionalstringfrom list_tiktok_videos
image_idsOptionalarray<string>cover image ids / image ad
ad_formatOptionalSINGLE_VIDEO | SINGLE_IMAGE | CAROUSEL—
landing_page_urlOptionalstring—
call_to_actionOptionalstringLEARN_MORE | SHOP_NOW | SIGN_UP | CONTACT_US | DOWNLOAD …
identity_idOptionalstring—
identity_typeOptionalstringCUSTOMIZED_USER | TT_USER | BC_AUTH_TT
display_nameOptionalstring—
tiktok_item_idOptionalstringSpark Ads post id (list_tiktok_posts)
deeplinkOptionalstring—
auto_message_idOptionalstringwelcome message for Direct Message ads (list_tiktok_auto_messages / create_tiktok_auto_message)
identity_bc_idOptionalstringBusiness Center id when identity_type is BC_AUTH_TT
operation_statusOptionalENABLE | DISABLEDISABLE creates the ad paused; default ENABLE
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

update_tiktok_campaign_budget

写入2 credits

Change the budget of one or more TikTok campaigns (amount in the ad account currency). The preview reads the current budget from TikTok (from) so the +50% per change guardrail applies; applied directly when the user asks. The ledger is updated only when TikTok accepts.

ParameterTypeDescription
campaign_idsRequiredarray<string>TikTok campaign ids (or one Tecrube campaign id)
amountRequirednumberaccount currency
campaign_idOptionalstringAlias of campaign_ids (single id)
currencyOptionalstringoptional ISO check; must equal the ad account currency
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

update_tiktok_campaign_status

写入Irreversible2 credits

Pause (DISABLE), enable (ENABLE) or permanently delete (DELETE) TikTok campaigns. Applied directly when the user asks; DELETE is applied only when the user explicitly asked for it and marks the ledger campaign as ended.

ParameterTypeDescription
campaign_idsRequiredarray<string>—
operation_statusRequiredENABLE | DISABLE | DELETEDELETE is permanent; only when the user explicitly asked
campaign_idOptionalstringAlias of campaign_ids (single id)
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

update_tiktok_ad_group

写入2 credits

Update one or many TikTok ad groups at once: budget, bid (bid_type/bid_price), targeting (locations, ages, gender, languages, interests, audiences), schedule and dayparting, comment/share settings, frequency cap, brand safety and device/network targeting. Placements, budget mode and the optimisation setup (goal, billing event, optimisation event, pixel) are fixed at creation, so they are refused with the reason. Applied directly when the user asks.

ParameterTypeDescription
adgroup_idsRequiredarray<string>—
adgroup_nameOptionalstring—
budgetOptionalnumber—
optimization_goalOptionalstringFixed at creation (defines the ad group's optimisation); rejected with an explanation
billing_eventOptionalstringFixed at creation (defines the ad group's optimisation); rejected with an explanation
bid_typeOptionalstringBID_TYPE_NO_BID | BID_TYPE_CUSTOM
bid_priceOptionalnumber—
conversion_bid_priceOptionalnumber—
pacingOptionalPACING_MODE_SMOOTH | PACING_MODE_FAST—
location_idsOptionalarray<string>TikTok location ids (Turkey 298795, US 6252001, UK 2635167, DE 2921044)
age_groupsOptionalarray<string>AGE_13_17 | AGE_18_24 | AGE_25_34 | AGE_35_44 | AGE_45_54 | AGE_55_100
genderOptionalGENDER_UNLIMITED | GENDER_MALE | GENDER_FEMALE—
languagesOptionalarray<string>language codes, e.g. tr, en
interest_category_idsOptionalarray<string>—
operating_systemsOptionalarray<string>ANDROID | IOS
audience_idsOptionalarray<string>—
excluded_audience_idsOptionalarray<string>—
schedule_start_timeOptionalstringYYYY-MM-DD HH:MM:SS (UTC)
schedule_end_timeOptionalstringYYYY-MM-DD HH:MM:SS (UTC); sets SCHEDULE_START_END
daypartingOptionalstring336 chars of 0/1: 7 days x 48 half-hours starting Monday 00:00
pixel_idOptionalstringFixed at creation (defines the ad group's optimisation); rejected with an explanation
optimization_eventOptionalstringFixed at creation (defines the ad group's optimisation); rejected with an explanation
comment_disabledOptionalboolean—
share_disabledOptionalboolean—
search_result_enabledOptionalboolean—
interest_keyword_idsOptionalarray<string>from search_tiktok_targeting(type=interest_keyword)
actionsOptionalarray<object>behaviour targeting: [{action_scene: VIDEO_RELATED|CREATOR_RELATED|HASHTAG_RELATED, action_period: 0|7|15, video_user_actions: [...], action_category_ids: [ids from search_tiktok_targeting(type=behavior)]}]
deep_bid_typeOptionalstringe.g. DEFAULT, MIN, PACING, VO_MIN_ROAS
roas_bidOptionalnumber—
zipcode_idsOptionalarray<string>from search_tiktok_targeting(type=location)
device_model_idsOptionalarray<string>—
device_price_rangesOptionalarray<number>price range bounds, e.g. [0, 250]
network_typesOptionalarray<string>WIFI | 2G | 3G | 4G | 5G
carrier_idsOptionalarray<string>—
schedule_typeOptionalSCHEDULE_FROM_NOW | SCHEDULE_START_END—
saved_audience_idOptionalstring—
frequencyOptionalintegermax impressions per user within frequency_schedule days
frequency_scheduleOptionalintegerfrequency cap window in days
brand_safety_typeOptionalstringNO_BRAND_SAFETY | STANDARD_INVENTORY | LIMITED_INVENTORY | EXPANDED_INVENTORY
blocked_pangle_app_idsOptionalarray<string>—
targeting_expansionOptionalobjecte.g. {expansion_enabled: true}
household_incomeOptionalarray<string>e.g. TOP5, TOP10, TOP10_25, TOP25_50
spending_powerOptionalALL | HIGH—
exclude_age_under_eighteenOptionalboolean—
changesOptionalobjectany adgroup/update fields as a map
adgroup_idOptionalstringAlias of adgroup_ids (single id)
placementsOptionalarray<string>Not changeable after creation (TikTok rule); rejected with an explanation
placement_typeOptionalstringNot changeable after creation (TikTok rule); rejected with an explanation
budget_modeOptionalstringNot changeable after creation (TikTok rule); rejected with an explanation
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

update_tiktok_ad_group_status

写入Irreversible2 credits

Pause, enable or permanently delete (DELETE) TikTok ad groups (e.g. pause the ones whose CPA is above target). Applied directly; DELETE only when the user explicitly asked.

ParameterTypeDescription
adgroup_idsRequiredarray<string>—
operation_statusRequiredENABLE | DISABLE | DELETEDELETE is permanent; only when the user explicitly asked
reasonOptionalstring—
adgroup_idOptionalstringAlias of adgroup_ids (single id)
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

update_tiktok_ad_status

写入Irreversible2 credits

Pause, enable or permanently delete (DELETE) TikTok ads (e.g. pause a fatigued creative). Applied directly; DELETE only when the user explicitly asked.

ParameterTypeDescription
ad_idsRequiredarray<string>—
operation_statusRequiredENABLE | DISABLE | DELETEDELETE is permanent; only when the user explicitly asked
reasonOptionalstring—
ad_idOptionalstringAlias of ad_ids (single id)
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

create_tiktok_custom_audience

写入2 credits

Create a rule-based TikTok custom audience from pixel, app or engagement events (e.g. added to cart in the last 30 days but did not purchase). Applied directly when the user asks; the audience needs hours to populate.

ParameterTypeDescription
nameRequiredstring—
audience_typeOptionalPIXEL | APP | ENGAGEMENT | ENGAGEMENT_ORGANIC_VIDEO | BUSINESS_ACCOUNT | LEAD_GENERATION | TIKTOK_SHOP—
retention_daysOptionalinteger (1–365)—
eventOptionalstringevent to include: AddToCart, CompletePayment, ViewContent, PageView (default for pixel) or a TikTok filter value such as PIXEL SEARCH
exclude_eventOptionalstringevent to exclude, e.g. CompletePayment for cart abandoners
pixel_idOptionalstring—
event_source_idsOptionalarray<string>pixel ids / app ids / ad group ids depending on audience_type
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

delete_tiktok_audience

写入Irreversible2 credits

Permanently delete TikTok custom or lookalike audiences (dmp/custom_audience/delete). Applied when the user asks; cannot be undone.

ParameterTypeDescription
audience_idsRequiredarray<string>ids from list_tiktok_audiences
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

create_tiktok_lookalike_audience

写入2 credits

Create a TikTok lookalike audience from a custom audience (TikTok sizes: NARROW ≈ closest, BALANCED, BROAD). Applied directly when the user asks.

ParameterTypeDescription
nameRequiredstring—
source_audience_idRequiredstring—
audience_sizeOptionalNARROW | BALANCED | BROAD—
include_sourceOptionalboolean—
location_idsOptionalarray<string>—
placementsOptionalarray<string>—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

create_tiktok_whatsapp_campaign

写入2 credits

Create a TikTok ad that opens a WhatsApp chat (click-to-WhatsApp): LEAD_GENERATION campaign, ad group with optimisation location Instant Messaging App (WhatsApp) on TikTok placement, and a video ad whose cover is taken from the video automatically. Built with TikTok Upgraded Smart+ endpoints: the budget sits on the campaign as a dynamic daily budget and the ad needs a linked TikTok account identity (TT_USER, BC_AUTH_TT or AUTH_CODE). chat_link builds the wa.me link from the phone number; website URLs are refused. Everything is created paused; applied directly when the user asks.

ParameterTypeDescription
nameRequiredstring—
phone_numberRequiredstringWhatsApp business number with country code, e.g. +90 532 000 00 00 (national format starting with 0 is rejected)
daily_budgetRequirednumberad group daily budget, account currency (TikTok minimum ≈ USD 20 equivalent)
video_idRequiredstringlibrary video (list_tiktok_videos / upload_tiktok_video)
ad_textRequiredstring1-100 chars
connection_methodOptionalchat_link | nativechat_link: wa.me link built from the number (CLICK only, no extra setup); native: number connected to TikTok's message management tool (CLICK or allowlisted CONVERSATION)
prefilled_messageOptionalstringchat_link only: text pre-filled in WhatsApp; must name the offer or service in the ad, generic greetings are rejected
optimization_goalOptionalCLICK | CONVERSATION—
phone_region_codeOptionalstringnative only, when the calling code is shared (e.g. US for +1)
message_event_set_idOptionalstringnative + CONVERSATION only, when the number matches no event set
image_idsOptionalarray<string>cover image id; omitted = the video's own cover is fetched and uploaded automatically
call_to_actionOptionalstringnot sent to TikTok: messaging ads use a dynamic call to action chosen by TikTok (CALL_NOW not allowed)
ad_nameOptionalstring—
identity_idOptionalstring—
identity_typeOptionalstringTT_USER | BC_AUTH_TT | AUTH_CODE: a linked TikTok account is required, CUSTOMIZED_USER is refused
display_nameOptionalstring—
goalOptionalstring—
audienceOptionalobjectcountries (ISO list), age_min (18+), age_max, genders ([1]=male, [2]=female), tiktok_location_ids, tiktok_interest_ids
ad_groupOptionalobjectoptional ad group targeting/schedule overrides; placements, promotion type and search results are fixed for messaging ads
landing_page_urlOptionalstringNOT accepted: a messaging ad group has no website destination; give phone_number instead
website_urlOptionalstringNOT accepted (same rule as landing_page_url); rejected with an explanation
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

update_tiktok_campaign

写入5 credits

Rename a TikTok campaign (campaign/update); the ledger name follows. Applied directly when the user asks. Budget and status have their own tools.

ParameterTypeDescription
campaign_idRequiredstringTikTok campaign_id or Tecrube campaign id
nameRequiredstring—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

update_tiktok_ad

写入5 credits

Edit a TikTok ad's copy in place (ad/update): name, text, landing page, call to action or display name. The current ad is read first and every other field is kept. Applied directly when the user asks.

ParameterTypeDescription
ad_idRequiredstring—
adgroup_idOptionalstringoptional; read from the ad when omitted
ad_nameOptionalstring—
ad_textOptionalstring1-100 chars
landing_page_urlOptionalstring—
call_to_actionOptionalstring—
display_nameOptionalstring—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

create_tiktok_auto_message

写入2 credits

Create a welcome message for TikTok Direct Message ads (creative/auto_message/create): a greeting plus 1-3 tappable questions with automatic answers. Returns auto_message_id.

ParameterTypeDescription
titleRequiredstringtemplate name
contentRequiredstringgreeting
suggested_questionsRequiredarray<object>—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

create_tiktok_identity

写入2 credits

Create a custom TikTok ad identity (identity/create): the display name and avatar shown on non-Spark ads. Applied directly when the user asks; returns identity_id.

ParameterTypeDescription
display_nameRequiredstring—
image_uriOptionalstringimage_id of a square avatar from upload_tiktok_image
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

create_tiktok_pixel

写入2 credits

Create a TikTok conversion pixel (pixel/create). Applied directly when the user asks; returns pixel_id and pixel_code to install on the website.

ParameterTypeDescription
nameRequiredstring—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

create_tiktok_customer_file_audience

写入6 credits

Build a TikTok custom audience from a customer list (dmp/custom_audience/file/upload + create). Values are normalised and SHA-256 hashed inside Tecrube before anything is stored or sent; the preview shows counts only. Approval first.

ParameterTypeDescription
nameRequiredstring—
identifiersRequiredarray<string>emails, phones with +country code, or device ids; already SHA-256 hashed values are accepted too
id_typeOptionalEMAIL | PHONE | IDFA | AAIDdefault EMAIL
retention_daysOptionalinteger (1–365)—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

share_tiktok_audience

写入4 credits

Share TikTok custom audiences with other ad accounts in the same Business Center, or stop sharing (dmp/custom_audience/share, /share/cancel). Applied directly when the user asks.

ParameterTypeDescription
audience_idsRequiredarray<string>1-10 custom audience ids
shared_advertiser_idsOptionalarray<string>1-10 ad accounts in the same Business Center (optional for unshare: all)
actionOptionalshare | unshare—
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

manage_tiktok_search_negative_keywords

写入4 credits

Negative keywords of TikTok search ads for a campaign or ad group (search_ad/negative_keyword/*): list reads directly; add and delete are applied directly when the user asks.

ParameterTypeDescription
object_typeRequiredCAMPAIGN | ADGROUP—
object_idRequiredstring—
operationOptionallist | add | deletedefault list
keywordsOptionalarray<string>for add; max 80 chars each
keyword_idsOptionalarray<string>for delete (from operation=list)
match_typeOptionalPRECISE_WORD | PHRASE_WORD | BROAD_WORDfor add; default BROAD_WORD
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

send_tiktok_conversion_event

写入1 credits

Send one server-side web conversion event to TikTok (Events API 2.0, event/track). Email, phone and external id are SHA-256 hashed before storing or sending. Applied directly when the user asks.

ParameterTypeDescription
pixel_codeRequiredstringfrom list_tiktok_pixels
event_nameRequiredstringstandard event, e.g. CompletePayment, SubmitForm, Contact, AddToCart
emailOptionalstring—
phoneOptionalstring+country code
external_idOptionalstring—
ttclidOptionalstringTikTok click id from the landing URL
valueOptionalnumber—
currencyOptionalstringISO 4217, required with value
event_idOptionalstringdeduplication key shared with the browser pixel
test_event_codeOptionalstringfrom Events Manager › Test Events; the event is only shown there
urlOptionalstringpage where the event happened
advertiser_idOptionalstringoptional: run in this TikTok ad account (advertiser id from list_accounts) for this call only; the saved account selection does not change

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.