TikTok Ads Integration

Connect your agent to TikTok's advertising platform to report on and manage campaigns, ad groups, ads, audiences, and creatives through TikTok's official TikTok for Business MCP server.

Overview

The TikTok Ads integration powers the int-tiktok-ads skill (TikTok Ads Manager). The agent works through TikTok's official TikTok for Business MCP server (Model Context Protocol), which exposes TikTok API for Business v1.3 capabilities as tools: reporting, campaign / ad group / ad management, Upgraded Smart+, audiences, creatives, Spark Ads, and TikTok's own diagnosis tools.

This integration covers advertising only. It does not post organic videos to a TikTok profile — that is the separate TikTok integration, which uses its own tiktok credential.

Skills that use this integration:

• int-tiktok-ads — Reporting, campaign / ad group / ad management, Upgraded Smart+ and GMV Max, audiences, creatives, Spark Ads, and diagnosis
• util-ads-manager-common and util-ads-playbook — Shared ads helpers (approval flow, recommendations queue, daily report template, kill / scale / test playbook), also used by the Meta Ads and Google Ads skills

Agents that typically enable this integration:

• TikTok Ads Manager (prebuilt; int-tiktok-ads is on by default)
• Any Custom Build agent that needs paid-media capabilities on TikTok

Availability

Authorization lasts 30 days. TikTok ends every TikTok for Business authorization 30 days after it is granted, and refreshing the access token does not extend it. Reconnect with the same TikTok for Business account to renew it — see "The 30-day authorization" below.

Prerequisites

• A TikTok for Business account with access to at least one advertiser (ad account) — for example through TikTok Ads Manager or membership in a Business Center. For the agent to make changes, not just report, that account needs a role on the advertiser that allows campaign management.
• An agent with int-tiktok-ads enabled — TikTok Ads Manager has it on by default. On a Custom Build agent, enable it with POST /UserAgent/SkillsApply (see "Using the Skill" below). Skill changes are only available on Custom Build agents.
• For API integrations only: a Wiro API key (Authentication), a deployed agent (Agent Overview) and its useragentguid, and an HTTPS return URL that your backend controls. http://localhost and http://127.0.0.1 are accepted for local development only.

Connect in the Wiro dashboard

1. Open your agent, go to Credentials, and find the TikTok Ads card.
2. Click Connect TikTok for Business.
3. Sign in to TikTok for Business and approve the consent screen. It names the app Wiro AI and asks for the mcp:tt4b permission scope.
4. Back in Wiro, pick the advertisers the agent may manage. You can select several; when your account has exactly one advertiser, it is selected for you.
5. Wiro saves the selection and restarts the agent if it was running, so the agent picks up the new connection.

The 30-day authorization

• TikTok ends every TikTok for Business authorization 30 days after it is granted. Refreshing the access token does not extend it; this is TikTok's rule, not a Wiro setting.
• To renew, reconnect with the same TikTok for Business account: click Disconnect on the TikTok Ads card, then Connect TikTok for Business again and confirm the advertisers. A different TikTok for Business account may see different advertisers.
• From 7 days before the end, the daily performance report opens its Risk Flags & Account Health section with the end date and a reconnect reminder. When you chat with the agent in that window, it mentions the end date once at the top of its reply.
• After the authorization ends, the daily performance report sends a one-line notice that TikTok Ads reporting stopped and asks you to reconnect. The other TikTok Ads scheduled tasks stay quiet until you reconnect.
• Expiry does not pause your ads. Campaigns keep delivering in TikTok; only the agent loses access.
• The short-lived access tokens (about 24 hours) are renewed by Wiro automatically. You never see or handle a TikTok token.

Advertiser selection

• The agent works only on the advertisers you selected when you connected. Any request for another advertiser is refused.
• To change the selection, click Disconnect on the TikTok Ads card, then connect again and pick the advertisers you want.
• Until at least one advertiser is selected, an agent that requires TikTok Ads (such as TikTok Ads Manager) stays in Setup Required and cannot start.

What the agent can do

What the agent cannot do

These operations are not available through this integration, by design. When you ask for one, the agent tells you it is not available instead of trying another way.

• Business Center administration.
• Billing, payments, balances, invoices, or fund transfers. TikTok charges ad spend to the advertiser's own payment method; handle billing in TikTok Ads Manager.
• Downloading lead data. Lead generation campaigns can be reported on (cost per lead) and paused.
• TikTok One (Creator Marketplace).
• Catalogs.
• Pixel and event configuration.
• Reach & Frequency purchases.
• Creating GMV Max campaigns. TikTok starts them delivering as soon as they are created, so create them in TikTok Ads Manager; the agent can then report on them and apply approved updates.
• Customer-file audiences. They need an audience file upload; create them in TikTok Ads Manager.
• Organic posting to a TikTok profile. Use the TikTok integration.

Safety and approvals

• Every change goes through the agent's approval policy (the approval-policy custom skill). By default the agent describes the change (object, IDs, old and new value, reason) and waits for your approval. Reads — reports, lookups, previews — never need approval.
• New objects start paused. Campaigns, ad groups, ads, Upgraded Smart+ campaigns, and campaign copies are always created paused. Turning one on is a separate change that needs its own approval.
• Deletes happen only when you ask. Campaigns, ad groups, ads, audiences, creative assets, blocked words, ad comments, and search negative keywords can be deleted on request, after approval. Deleting cannot be undone. The agent never deletes on its own; when it recommends stopping something, it pauses it.
• Rejected changes are not retried. If TikTok rejects a change, the agent reports TikTok's message and request ID and stops.
• Scheduled tasks only read from TikTok. They put proposed changes into the recommendations queue; a change runs only after you approve it in chat (for example apply 1).
• Budgets are in the advertiser's currency, not cents. The agent confirms the currency before changing a budget and states it in the approval request. TikTok requires a new budget to be at least 105% of what has already been spent and does not accept budget changes between 23:55 and 00:00 advertiser time.
• Rate limits. TikTok allows most tools 3 requests per second per tool for each TikTok for Business user; a few, such as asynchronous report creation and campaign copies, have lower limits per app. When TikTok rate-limits a report or lookup, the agent backs off and retries; a rate-limited change is reported and not retried.
• No secrets in chat. The agent never asks for a TikTok password or token. The only code you paste is a Spark Ads authorization code.

Scheduled tasks

TikTok Ads Manager ships with these scheduled tasks. Times use the agent's time zone.

Shared ads tasks also cover TikTok Ads: the nightly cron-ads-recommendation-cleanup expires stale recommendations, and the optional Adjust creative ROAS report (cron-adjust-creative-roas-reporter) cross-checks TikTok spend when Adjust is connected.

To change what the tasks look for, edit these custom skills (stored as cs-<key>) rather than the tasks:

• tiktok-ads-strategy — TikTok-specific knobs: tracking quality gates, kill thresholds, placement strategy, Spark Ads and Smart+ rules.
• ad-strategy — cross-platform KPI thresholds, shared with Meta Ads and Google Ads.
• approval-policy — which changes wait for approval.

Multiple advertisers

• Scheduled tasks run once per selected advertiser. Each report is headed with the advertiser's name and ID and uses that advertiser's currency and time zone.
• In chat, name the advertiser when more than one is selected; otherwise the agent asks which one to use. A single request or change never mixes advertisers.
• The 30-day reminder appears in each advertiser's daily report; the expiry notice is sent once for the whole connection.

Connect through the API

Use this flow when you build your own settings screen on top of Wiro agents. Every request is authenticated as described in Authentication.

Step 1: Start the connection

curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "credentialkey": "tiktok-ads",
    "redirecturl": "https://your-app.com/settings/integrations"
  }'

Response:

{
  "result": true,
  "errors": [],
  "authorizeUrl": "https://business-api.tiktok.com/portal/mcp-tt4b-authorize?client_id=...&redirect_uri=https%3A%2F%2Fapi.wiro.ai%2Fv1%2FUserAgentOAuth%2FTikTokAdsCallback&scope=mcp%3Att4b&response_type=code&state=...&code_challenge=...&code_challenge_method=S256&resource=..."
}

Redirect the user's browser to authorizeUrl with a full-page redirect rather than a popup. Wiro adds the PKCE challenge itself, so you never handle a code verifier or client secret. authmethod can be omitted: "wiro" is the default and the only accepted value.

State TTL: Wiro keeps the OAuth state for 15 minutes. If the user takes longer on TikTok's consent screen, the connection fails with tiktokads_error=session_expired and you must call OAuthConnect again.

Step 2: Handle the return

After the user approves, TikTok sends them to Wiro's callback (https://api.wiro.ai/v1/UserAgentOAuth/TikTokAdsCallback). Wiro exchanges the code, lists the advertisers the TikTok for Business user can access, stores the tokens server-side, and redirects the browser to your redirecturl.

Success URL looks like:

https://your-app.com/settings/integrations?tiktokads_connected=true&tiktokads_advertisers=%5B%7B%22id%22%3A%227012345678901234567%22%2C%22name%22%3A%22Brand%20X%22%7D%5D

• tiktokads_advertisers is encodeURIComponent(JSON.stringify([...])).
• Each element is { id, name }: id is the numeric advertiser ID as a string, name is the advertiser name.
• The list is never empty on success. When no advertiser can be listed, the callback returns tiktokads_error=no_accounts instead.
• On a first connection (or after OAuthDisconnect), nothing is selected yet: the connection becomes active only after Step 3, even when a single advertiser is returned. Reconnecting without OAuthDisconnect keeps the previous selection.

Parse in the browser:

const params = new URLSearchParams(window.location.search);

if (params.get("tiktokads_connected") === "true") {
  const advertisers = JSON.parse(params.get("tiktokads_advertisers") || "[]");
  if (advertisers.length === 1) {
    await saveAdvertisers(advertisers);
  } else {
    presentAdvertiserPicker(advertisers);
  }
} else if (params.get("tiktokads_error")) {
  handleError(params.get("tiktokads_error"));
}

Step 3: Save the advertiser selection

This call is required. The Wiro dashboard selects a sole advertiser automatically, but API clients must always send the selection themselves.

curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "credentialkey": "tiktok-ads",
    "accounts": [
      { "advertiserid": "7012345678901234567", "advertisername": "Brand X" }
    ]
  }'

Response:

{
  "result": true,
  "errors": [],
  "accounts": [
    { "id": "7012345678901234567", "name": "Brand X" }
  ]
}

Behavior:

• Send one or more { advertiserid, advertisername } entries picked from tiktokads_advertisers (id becomes advertiserid, name becomes advertisername). Non-digits in advertiserid are stripped server-side.
• Each call replaces the previous selection.
• If the agent was running, Wiro restarts it so it picks up the selection. No manual Start needed.

Step 4: Verify the connection

curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "credentialkey": "tiktok-ads"
  }'

Response:

{
  "result": true,
  "errors": [],
  "connected": true,
  "accounts": [
    { "id": "7012345678901234567", "name": "Brand X" }
  ],
  "connectedat": "2026-09-26T08:14:00.000Z",
  "tokenexpiresat": "2026-09-27T08:14:00.000Z"
}

Field notes:

• connected is true when the connection has a current access token and at least one advertiser is selected.
• connectedat is when the user authorized. The authorization ends 30 days after this time.
• tokenexpiresat is the expiry of the current access token (about 24 hours), not the end of the 30-day authorization. Wiro renews the access token while the agent is running, so this value moves forward about once a day.
• If the agent has been stopped for more than a day, connected can read false until the agent runs again. Starting the agent renews the access token as long as the 30-day authorization has not ended.

Step 5: Start the agent if it's not running

curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "guid": "your-useragent-guid" }'

Check POST /UserAgent/Detail first: if setuprequired is still true, TikTok Ads or some other credential the agent requires is incomplete, and Start will refuse. See Agent Credentials — Setup Required.

Agents already running when you connected TikTok Ads restart automatically.

Credential fields

Both fields are returned by POST /UserAgent/Detail and are managed by the connection flow: POST /UserAgent/CredentialUpsert rejects writes to them (for example Advertiser ID is managed by the connection flow). Access and refresh tokens are stored server-side and are never returned by any endpoint.

API Reference

All endpoints require Wiro authentication — see Authentication for x-api-key + optional signature headers.

POST /UserAgentOAuth/OAuthConnect

Response: { result, errors, authorizeUrl }. If result: false, inspect errors[0].message — common messages: Request parameter [useragentguid] required, Request parameter [credentialkey] required, Request parameter [redirecturl] required, Invalid redirect URL, User agent not found or unauthorized, Unsupported connection mode for TikTok Ads, and TikTok Ads credentials not configured.

GET /UserAgentOAuth/TikTokAdsCallback

Server-side endpoint invoked by TikTok. You don't call it — you only handle the final redirect back to your redirecturl. The callback path is per-provider — TikTok Ads's is TikTokAdsCallback, separate from the organic TikTok integration's TikTokCallback.

POST /UserAgentOAuth/SetPickerAccounts

Response: { result, errors, accounts: [{id, name}, ...] }. Replaces the previous selection and triggers an automatic agent restart if the agent was running. Returns TikTok Ads account not connected when no completed connection exists yet.

POST /UserAgentOAuth/OAuthStatus

Response fields:

POST /UserAgentOAuth/OAuthDisconnect

Body: { useragentguid, credentialkey: "tiktok-ads" }. Asks TikTok to revoke the authorization and clears the connection in Wiro: tokens, connection time, and the advertiser selection. The Wiro side is cleared even if TikTok's revoke request fails. An access token TikTok issued earlier may stay valid at TikTok for up to 24 hours, but the agent no longer has it.

curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "credentialkey": "tiktok-ads"
  }'

Response: { "result": true, "errors": [] }. Running agents restart automatically.

Token lifecycle

Wiro renews the 24-hour access token automatically while the agent is running. The authorization behind it lasts 30 days from connectedat and cannot be extended by refreshing. To renew it, run the flow again: OAuthDisconnect, then OAuthConnect, the callback, and SetPickerAccounts. There is no customer-facing token-refresh endpoint, and raw tokens are never exposed to the agent model or to API callers.

Using the Skill

TikTok Ads Manager has int-tiktok-ads on by default. On a Custom Build agent, enable it via POST /UserAgent/SkillsApply (see Agent Skills → Toggling Integration Skills); skill changes are only available on Custom Build agents. Adjust the cron of a bundled task such as the daily performance report with enabled and interval only — the task body (value) is owned by the bundled integration skill and silently dropped on writes:

curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "skillkey": "cron-tiktokads-performance-reporter",
    "enabled": true,
    "interval": "0 9 * * *"
  }'

To change what the reports include (tracking quality gates, kill thresholds, placement strategy, Spark Ads and Smart+ rules), edit the preference skill tiktok-ads-strategy (stored as cs-tiktok-ads-strategy), or ad-strategy for cross-platform thresholds — see Agent Skills → Updating Preferences.

Troubleshooting

Because no valid state is left to read your redirecturl from, missing_params and session_expired send the browser to https://wiro.ai with the error parameter instead of to your app.

"No accounts available" after signing in

Either the TikTok for Business user you signed in with has no advertiser access, or TikTok's advertiser lookup failed. Get access to an advertiser in TikTok Ads Manager or through Business Center membership, then connect again. If this user already has advertiser access, try connecting again.

The agent says the TikTok Ads connection expired

The 30-day authorization ended. Click Disconnect on the TikTok Ads card, then connect again with the same TikTok for Business account and confirm the advertisers. Your campaigns kept running in TikTok in the meantime.

A change was refused

The action is outside what this integration allows (see "What the agent cannot do"), it targets an advertiser that was not selected, or the TikTok for Business user's role on the advertiser does not allow campaign management. Change roles in TikTok's business settings; change the advertiser selection by disconnecting and connecting again.

A report metric is rejected by TikTok

Nothing to do. The agent drops the metric TikTok rejected and runs the report again without it.

connected: false after completing the flow

OAuthStatus returns connected: true only when there is a current access token and at least one advertiser is saved. If you skipped Step 3 (SetPickerAccounts), connected stays false. If the selection is saved, check whether the 30-day authorization has ended (reconnect) or the agent has been stopped for more than a day (start it).

Multi-Tenant Architecture

For SaaS products connecting many customers' TikTok Ads accounts through a single Wiro-powered backend:

1. One Wiro agent instance per customer. Call POST /UserAgent/Deploy during onboarding, then run the connection flow for that customer's useragentguid. Each customer signs in with their own TikTok for Business account.
2. Tokens are isolated per agent instance. Customer A's TikTok authorization is never visible to Customer B — they live under different useragentguid values.
3. The consent screen shows Wiro AI. There is no customer-owned app mode, so the consent screen cannot be white-labeled.
4. Plan for the 30-day renewal. Every customer has to reconnect every 30 days. Track connectedat from OAuthStatus and prompt the customer before the 30 days are up.
5. Rate limits are mostly per TikTok for Business user. TikTok allows most tools 3 requests per second per tool for each user; asynchronous report creation and campaign copies have lower per-app limits that all connections share.

Related

• Agent Credentials & OAuth — integration catalog hub and generic OAuth reference.
• Agent Overview — deploying, starting, and lifecycle.
• Agent Skills — configuring int-tiktok-ads and scheduled runs.
• TikTok integration — organic video posting to a TikTok profile (separate tiktok credential).
• Meta Ads integration — for cross-platform paid campaigns.
• Google Ads integration — for cross-platform paid campaigns.