TikTok

The TikTok integration covers organic content publishing, ad campaign management through TikTok Ads Manager, and engagement sync. The connector uses TikTok for Business OAuth, which grants access to creator accounts, business accounts, and ad accounts.

Connect TikTok

TikTok uses OAuth 2.0. Vendor segment in the universal flow is tiktok.

const { authUrl } = await fetch('/api/upstream/call/tiktok-provider/get-auth-url', {
  method: 'POST',
  headers: { orgid: ORG_ID, Authorization: `Bearer ${jwt}` },
  body: JSON.stringify({
    scopes: [
      'user.info.basic',
      'user.info.profile',
      'user.info.stats',
      'video.list',
      'video.upload',
      'video.publish',
      'business.creator.insights',
    ],
    returnUrl: 'https://admin.example/integrations',
  }),
}).then(r => r.json());

Ad-platform scopes are separate — request them through TikTok Ads Manager API rather than the same OAuth flow. The integration record stores both sets of credentials.

Content publishing

// Initialise an upload (returns upload URL)
const { uploadUrl, publishId } = await fetch(
  '/api/upstream/call/tiktok-provider/init-video-upload',
  {
    method: 'POST',
    headers: { orgid: ORG_ID, Authorization: `Bearer ${jwt}` },
    body: JSON.stringify({
      title: 'New product drop',
      caption: 'Check out our spring collection #springfashion',
      privacyLevel: 'PUBLIC_TO_EVERYONE',
    }),
  },
).then(r => r.json());

// Upload bytes to uploadUrl (multipart)
// Then publish
await fetch('/api/upstream/call/tiktok-provider/publish-video', {
  method: 'POST',
  headers: { orgid: ORG_ID, Authorization: `Bearer ${jwt}` },
  body: JSON.stringify({ publishId }),
});

The two-step (init upload, then publish) is how TikTok's Content Posting API works — upload is asynchronous and the platform polls for completion before publishing.

Ads

TikTok Ads campaigns route through the Ads module. The connector wraps TikTok Ads Manager API operations: campaign create, ad group create, creative upload, launch, pause, metrics fetch.

Ad account selection: a single TikTok user can manage multiple ad accounts. The integration record stores all accessible accounts; the Ads module's campaign body specifies which accountId to use.

Engagement sync

The Sync module's TikTok job pulls recent video performance metrics (views, likes, comments, shares) and writes them to the social activity store. Comments on the org's videos can be ingested as CRM inbox conversations if business.creator.insights scope is granted.

await fetch('/api/sync/trigger', {
  method: 'POST',
  headers: { orgid: ORG_ID, Authorization: `Bearer ${jwt}` },
  body: JSON.stringify({ platform: 'tiktok', syncType: 'all' }),
});

Webhooks

TikTok sends webhooks for ad-account-level events (campaign approved, rejected, paused) and creator-level events (video published, removed). The connector dispatches based on event type — most flow into the social activity sync.

Token expiry

TikTok access tokens last 24 hours; refresh tokens last 365 days. The connector refreshes the access token transparently before each call. On refresh failure (revoked, expired), the integration moves to status: "expired" and the admin is notified.

Common quirks

• Content moderation — TikTok reviews uploaded videos before they go live. The platform reports the publish state but can't accelerate review.
• Music licensing — videos uploaded via the API can't include arbitrary music tracks; TikTok strips unlicensed audio. Use TikTok's commercial music library or upload audio you own.
• Audience segmentation — TikTok's custom audience uploads require hashed identifiers. The connector hashes locally before upload; never send raw email addresses.