> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.shipcontent.com/llms.txt
> Use this file to discover all available pages before exploring further.

---
title: TikTok
description: Prepare one saved video for a TikTok Personal or Business account.
section: channels
order: 26
status: implemented
mode: both
reviewed: 2026-11-19
sources: [src/lib/server/marketing/post-metrics-agent-tools.ts, src/lib/mcp/agent-post-metrics-tools.ts, src/lib/server/marketing/post-metric-mapping.ts, db/accounts.sql, db/tiktok.sql, src/lib/server/tiktok/TikTokCommentsPagination.ts, src/lib/server/owner/owner-handler-tiktok-routes.ts, db/publishing.sql, src/components/owner/tiktok-account.tsx, src/app/[workspace]/(app)/tiktok/page.tsx, src/app/tiktok/page.tsx, src/lib/server/tiktok/TikTokInsights.ts, src/lib/server/tiktok/TikTokComments.ts, src/worker/TikTokReplyWorker.ts, src/lib/server/owner/OwnerHandler.ts, src/components/owner/post-video-upload.tsx, src/components/owner/tiktok-controls.tsx, src/components/owner/post-review.tsx, src/components/studio.tsx, src/components/marketing/marketing-workspace.tsx, src/lib/media/post-video-upload.ts, src/lib/tiktok/tiktok-tools.ts, src/lib/server/tiktok/tiktok-agent-tools.ts, src/worker/TikTokPublicationWorker.ts, src/lib/server/tiktok/TikTokPublication.ts, src/lib/server/tiktok/TikTokMedia.ts, src/app/integrations/tiktok/media/[leaseToken]/route.ts, src/lib/tiktok/tiktok.ts, src/lib/server/tiktok/TikTokAccountsProvider.ts, src/lib/server/tiktok/TikTokAccounts.ts, src/lib/server/tiktok/TikTokAccountsVault.ts, src/app/integrations/tiktok/callback/route.ts, src/lib/server/tiktok/tiktok-callback.ts, src/components/owner/channel-actions.ts, src/lib/marketing/marketing-drafts.ts, src/lib/mcp/agent-tools.ts, src/lib/server/owner/connections-overview.ts, db/migrations/20261119T0420_agent_delete_cancel_post.sql, src/lib/mcp/agent-post-lifecycle-tools.ts, src/lib/server/marketing/post-lifecycle-agent-tools.ts, src/lib/server/marketing/PostScheduleStore.ts, src/lib/marketing/post-lifecycle.ts]
tools: [list_tiktok_posts, list_tiktok_comments, list_tiktok_replies, prepare_tiktok_reply, get_tiktok_insights, refresh_tiktok_insights, start_tiktok_connection, get_tiktok_status, prepare_tiktok_publication, get_tiktok_operation, create_post, edit_post, duplicate_post, get_post, list_assets, get_post_metrics, refresh_post_metrics, delete_post, cancel_post_schedule]
next: [/docs/workflows/post-draft, /docs/workflows/media, /docs/contracts/approval-model]
---

Publishing uses no credits. With plan enforcement on, new owner and automatic-agent publication approvals and unsent publication starts require publishing access. An explicit future schedule also requires scheduling access and available scheduled-post capacity across all owner workspaces. Immediate publication does not use that capacity. A lower schedule cap keeps accepted schedules; publishing access is checked again before execution. If it ends, unsent publication work is cancelled. Replies and polling for an initiated send continue under their existing authority rules. Exact saved approval replays remain available. Updated October 16, 2026.

Prepare a TikTok video draft with the shared post tools. Select an uploaded or generated video from `list_assets`, then attach its saved ID with `create_post` or `edit_post`. A generated video needs no download or new upload.

## Draft settings

Set `channel: "tiktok"` and `format: "video"`. Supply the caption, one saved video ID and `tiktok` in the same request. The six booleans in `tiktok.settings` are `isBrandOrganic`, `isBrandedContent`, `isAiGenerated`, `disableComment`, `disableDuet` and `disableStitch`. Keep the AI disclosure true for AI-generated content.

Set `tiktok.schedule` to `null` for no proposed schedule. To propose timing, supply an explicit UTC `dueAt` and an IANA `timeZone`, for example `America/Mexico_City`. These fields save preparation; they do not queue a send. Read the same post with `get_post` after an edit. A duplicate copies settings and clears proposed timing.

## Upload and publish

In Media, select **Upload video**, then **Create TikTok post** on the saved video. In Posts, select TikTok and **Upload video** in Create post, or open a draft and select **Upload video**. A completed upload saves the private asset. It does not approve or publish. Upload and draft work also function before TikTok is connected.

The draft accepts one video. **Upload replacement video** replaces its attachment. If storage succeeds but attachment fails, the video stays in Media; **Retry attachment** uses the saved asset without another upload. Text edits are kept. Save the caption, settings and optional UTC time, then select **Review saved video**. Check the video preview, account, caption, disclosures and time. Select **Approve and publish** or **Approve schedule** once. Approval locks the draft. Duplicate it to make another publication.

For agents, select the saved video with `list_assets` or the completed `get_media_job` result. Save all draft fields with `create_post` or `edit_post`, then call `prepare_tiktok_publication`. With Publish (`list_workspaces.access.canPublish`) and an `automatic` post, a ready result has `mode: "queued"`, `operation` and `review: null`. Otherwise give `review.url` to the owner when `mode: "owner_review"`; resolve blockers first. After approval or queuing, read `get_tiktok_status` with `postId`; its `operation.id` resumes `get_tiktok_operation`. No video download, re-upload or extra agent setup is needed.

## Availability

Draft storage, the Accounts API adapter and owner account connection are implemented locally. In Connections, select **Connect** to authorize a Personal/creator or Business account. The server inspects the returned app, account and scopes. A different reconnect destination waits for owner confirmation. Disconnect removes local credentials; published TikTok videos stay on TikTok.

The tile shows **Not configured** until the operator supplies the Accounts settings below. Provider access is subject to TikTok approval and the permissions the account grants. Exact review preparation and owner approval are implemented on the server. The worker publishes and schedules approved videos locally. Owner publication controls and agent publishing handoffs are implemented locally. Owned post/comment reads and reviewed reply delivery are implemented on the server; their owner view and agent tools are implemented locally. On-demand account and post performance reads are implemented on the server. An approved developer app or advertiser connection does not prove Accounts API access.

Comment reads use one page per request, with distinct IDs and full reply pagination. Successful empty comment reads are supported, including a terminal response with no comments array. Nonempty pagination and reply reads have not yet been verified in production. A short page can still have more data. A repeated cursor stops that scan with an incomplete-list message. The server saves owned videos and verifies an exact public parent comment before reply review, owner approval and send. Replies allow 1,200 Unicode characters. Hidden, missing or changed parents require a new review.

Owner reads use `GET /owner/tiktok-comments`; supply `videoId` for comments and add `commentId` for replies. `GET /owner/tiktok-reply` reads a saved review and operation. `POST /owner/tiktok-reply` prepares a reply or approves its exact hash with the normal owner session and CSRF token. Agents cannot approve. A returned reply ID is saved separately from public, hidden or unavailable readback. An uncertain send stays unconfirmed and is not repeated automatically.

## Operator setup

Reuse the app's server-only `TIKTOK_BUSINESS_APP_ID` and `TIKTOK_BUSINESS_APP_SECRET`. Set `TIKTOK_ACCOUNTS_AUTHORIZATION_URL` to the portal's TikTok account holder authorization URL. Set `TIKTOK_ACCOUNTS_REDIRECT_URI` and register exactly `https://app.shipcontent.com/integrations/tiktok/callback/`, including the final slash.

Set `SHIPCONTENT_TIKTOK_ACCOUNTS_CONNECTION_DATABASE_URL` to a separate login with only the restricted Accounts connection role. Configure `SHIPCONTENT_TIKTOK_ACCOUNTS_VAULT_ACTIVE_KEY_ID` and `SHIPCONTENT_TIKTOK_ACCOUNTS_VAULT_KEYS` with the key ID and a JSON map of base64 32-byte AES keys. Keep old keys while saved credentials use them. The schema bootstrap also needs `SHIPCONTENT_BOOTSTRAP_TIKTOK_ACCOUNTS_CONNECTION_PASSWORD`. These credentials are separate from advertiser tokens.

The callback accepts one authorization code in `code` (the v2 web authorization return) or `auth_code` (the Accounts authorization guide), with one-use state and the current owner's session. Duplicate or mixed code fields are rejected before token exchange. The Accounts token request uses `auth_code`. See [web authorization](https://developers.tiktok.com/docs/en/login-kit-web) and [Accounts authorization](https://business-api.tiktok.com/portal/docs/accounts-api-authorization/v1.3). Account reads expose identity, scopes, permission availability and check time; they exclude credentials. A normal token refresh preserves the connection. Changed scopes or disconnect invalidate its authority. A provider rejection requires reconnect.

Publication needs `video.publish` and `video.list`, so ShipContent can read the saved provider result after sending. Basic post performance needs `video.list`. The optional `video.insights` scope enables additional provider fields; its absence does not block the basic counts. Performance is shown only for the selected workspace and post.

## Limits

A draft accepts zero or one saved video and follows `publishMode` like other channels. Use `review` unless the user requested automatic publishing. A post the owner set to review cannot be changed by the agent (`PUBLISH_MODE_LOCKED`). An automatic video can be queued by an agent with Publish. TikTok comment replies still need the owner. Captions allow at most 2,200 UTF-16 units and 30 mentions. Two UTF-16 units are used for most emoji. The existing source-specific media limits still apply; this change does not increase upload limits.

A post, comment or reply list `cursor` has 1 to 20 digits. Leading zeros do not change the page: `007` reads the same page as `7`. The server keeps at most 100 pages of one list. It reads a later page from TikTok but does not keep it. After a scope change or a reconnect, the server does not use the pages it kept and reads each page from TikTok again. A kept page also needs the list permission (`TIKTOK_PERMISSION_REQUIRED`). Read the first page without `cursor` to start the list again. Updated October 29, 2026.

A ready review expires after 30 minutes. It binds the video checksum, account, permission version, caption, six settings and UTC schedule. Approval by the owner or an agent with Publish saves one operation. `tiktok.schedule` keeps its proposed time; `prepare_post_schedule` does not schedule TikTok. Turning off Publish keeps this queued work; disconnecting the agent cancels unsent work. A schedule more than 15 minutes late needs a new draft and review; exactly 15 minutes is allowed. Uploaded MP4s keep the 50 MiB limit. Generated MP4s keep the 250 MiB limit. This public-video path requires account privacy to allow public posts, at least 360px in both dimensions, 23–60 fps and a duration from 3 seconds to the lesser of 600 seconds or the account limit.

The operator must set `TIKTOK_ACCOUNTS_MEDIA_ORIGIN` to an owned HTTPS origin and verify URL ownership with TikTok before publishing. Each server-only media URL serves one approved saved video for 45 minutes. The private bucket stays private. The worker checks the exact URL against this app's verified properties with TikTok before sending. It checks the saved six-per-minute and 15-per-24-hour send allowance for the account; other TikTok activity can also use the provider allowance.

An unsent scheduled operation can be cancelled. After send, cancellation returns its current status. Updated 2026-11-19: an agent cancels an unsent operation that an agent made with `cancel_post_schedule`. It needs the Publish permission. The result has `schedule: null`. The operation moves to `cancelled`, and the post keeps its lock. `delete_post` also cancels such an operation and then hides the post. An operation that the owner approved returns `SCHEDULE_OWNER_LOCKED`, and an operation that was sent returns `SCHEDULE_DISPATCH_STARTED`. Both leave the operation as it is. A cancelled, late or stopped publication keeps the post locked: duplicate the post to schedule it again. A saved publishing task ID resumes status checks. After send, an account, permission or access change does not stop these checks, and a failure becomes `unknown`, not failed. A lost send response without a task ID stays unknown and is not submitted again. Completion without a final post ID stays processing for up to 24 hours, then becomes `unknown`. A final ID needs exact owned-post readback before the worker marks it published. Provider acknowledgement is separate from independent public visibility evidence.

The Accounts API uses separate customer authorization. See [TikTok's Accounts API overview](https://business-api.tiktok.com/portal/docs/accounts-api-overview/v1.3).


In Connections, select **Posts and comments** to open the protected TikTok workspace page. Refresh owned posts, select one, then open a comment thread. Write a reply, select **Review reply**, check the exact parent and text, then **Approve and send reply**. Agents use `prepare_tiktok_reply` and give its protected `review.url` to the owner. Read `get_tiktok_status` with `reviewId` to recover the operation. Sent receipts and public, hidden or unavailable visibility remain separate.

## Performance

Use **Refresh performance** on the TikTok workspace page. Agents use `get_tiktok_insights` or `refresh_tiktok_insights`. Read saved performance with `GET /owner/tiktok-insights`. Refresh with `POST /owner/tiktok-insights` and the normal owner session and CSRF token. Account reports default to the previous seven complete UTC days. Select both inclusive dates within the last 60 days. A `videoId` selects lifetime post totals and cannot use a date range.

Updated 2026-11-19: `get_post_metrics` also returns the lifetime views, likes, comments and shares of each published TikTok video, with the posts of the other channels, and `refresh_post_metrics` reads them. `refresh_post_metrics` needs the `video.list` permission to read the numbers; `get_post_metrics` reads saved numbers only. Without the permission, the row has a `failure`. Account reports and date ranges stay in `get_tiktok_insights`. See [Read post performance](/docs/workflows/metrics).

Views, likes, comments and shares retain the source, account, reporting basis and last refresh time. Missing data stays unavailable; an explicit zero stays zero. A failed refresh keeps the last successful snapshot and marks it stale. Snapshots older than 24 hours are stale. Disconnect prevents provider reads. Comparisons require the same account, connection, post, period, basis and UTC timezone.

Engagement rate is derived as `(likes + comments + shares) / video_views × 100`. It is unavailable if an input is missing or video views are zero. Some metrics can lag 24–48 hours. Video views include paid and organic views. Post data can stop updating after 365 days. Refresh on demand; no analytics scheduler runs.
