TikTok

TikTok business accounts through your TikTok API for Business app ("TikTok Accounts").

The permissions each capability needs are in App Review: TikTok.

video and photo are publish variants of tiktok.posts.items.
There is no live surface: TikTok publishes no LIVE API.
Koil registers your app's webhook callbacks with TikTok itself, per event family and only while an Event Destination is subscribed to a topic that family feeds, so there is no developer-console step.

Publishing is not yet usable

TikTok pulls post media only from a URL whose domain or prefix your app has verified as a URL property, and Koil currently serves staged media from an origin no customer can verify. A publish is rejected up front with that reason rather than failing minutes later. Reading, replying, moderating, and messaging are unaffected.

Content type	Operations	Events	Backfill
`tiktok.posts.items`	`list`, `get`, `publish`	`created`, `deleted`	no
`tiktok.posts.comments`	`list`, `get`, `publish`, `moderate`, `delete`	`created`, `updated`, `deleted`, `moderated`	no
`tiktok.posts.mentions`	`list`, `get`	`created`, `updated`	no
`tiktok.dm.threads`	`list`	`updated`	no
`tiktok.dm.messages`	`list`, `publish`	`created`	no

`tiktok.posts.items`

The account's public video and photo posts.

`list`

List the TikTok account's public posts, newest first.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId"
  ]
}

`get`

Get one TikTok post by provider id.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId"
  ]
}

`publish`

Publish a TikTok video or photo post.

Submit through POST /v1/publish-requests with contentType: "tiktok.posts.items". These fields go in the item's args; connectedProfileId and variant are item fields.

variant: "video"

Field	Type	Required	Description
`text`	`string`	no	Caption; hashtags and @mentions render as plain text. Up to 2,200 UTF-16 code units and 30 mentions.
`media`	`object \| object[]`	yes
`brandOrganic`	`boolean`	yes	Label the post as promotional content for the account's own business.
`brandedContent`	`boolean`	yes	Label the post as a paid partnership with a brand.
`disableComment`	`boolean`	no
`disableDuet`	`boolean`	no
`disableStitch`	`boolean`	no
`thumbnailOffsetMs`	`integer`	no
`customThumbnailUrl`	`string`	no	Cover image for the video, as a URL on a URL property the app has verified — the same rule the staged video URL follows. JPG, JPEG, WebP or PNG, 360×360 to 1080×1920 (or 1920×1080), within 20 MB. Cannot be combined with thumbnailOffsetMs, which TikTok ignores when a cover URL is set.
`aiGenerated`	`boolean`	no	Label the post as AI-generated; cannot be changed once posted.
`draft`	`boolean`	no	Deliver to the creator's TikTok inbox as a draft instead of publishing; needs the video.upload scope and ignores every other post setting.
`scheduling`	`object`	no	Future operation time and optional wall-clock timezone.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "text": {
      "description": "Caption; hashtags and @mentions render as plain text. Up to 2,200 UTF-16 code units and 30 mentions.",
      "maxLength": 2200,
      "type": "string"
    },
    "media": {
      "minItems": 1,
      "maxItems": 1,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "pattern": "^video/",
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "pattern": "^video/",
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    },
    "brandOrganic": {
      "description": "Label the post as promotional content for the account's own business.",
      "type": "boolean"
    },
    "brandedContent": {
      "description": "Label the post as a paid partnership with a brand.",
      "type": "boolean"
    },
    "disableComment": {
      "type": "boolean"
    },
    "disableDuet": {
      "type": "boolean"
    },
    "disableStitch": {
      "type": "boolean"
    },
    "thumbnailOffsetMs": {
      "minimum": 0,
      "type": "integer"
    },
    "customThumbnailUrl": {
      "description": "Cover image for the video, as a URL on a URL property the app has verified — the same rule the staged video URL follows. JPG, JPEG, WebP or PNG, 360×360 to 1080×1920 (or 1920×1080), within 20 MB. Cannot be combined with thumbnailOffsetMs, which TikTok ignores when a cover URL is set.",
      "minLength": 1,
      "type": "string"
    },
    "aiGenerated": {
      "description": "Label the post as AI-generated; cannot be changed once posted.",
      "type": "boolean"
    },
    "draft": {
      "description": "Deliver to the creator's TikTok inbox as a draft instead of publishing; needs the video.upload scope and ignores every other post setting.",
      "type": "boolean"
    },
    "scheduling": {
      "additionalProperties": false,
      "description": "Future operation time and optional wall-clock timezone.",
      "type": "object",
      "properties": {
        "at": {
          "format": "date-time",
          "description": "Future execution time as an ISO-8601 string.",
          "type": "string"
        },
        "timezone": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "at"
      ]
    }
  },
  "required": [
    "media",
    "brandOrganic",
    "brandedContent"
  ]
}

variant: "photo"

Field	Type	Required	Description
`title`	`string`	no
`text`	`string`	no	Caption; hashtags and @mentions render as plain text. Up to 4,000 UTF-16 code units and 30 mentions.
`media`	`object \| object[]`	yes
`privacyLevel`	`"PUBLIC_TO_EVERYONE" \| "MUTUAL_FOLLOW_FRIENDS" \| "FOLLOWER_OF_CREATOR" \| "SELF_ONLY"`	yes
`coverIndex`	`integer`	no	Which image is the cover; defaults to the first.
`autoAddMusic`	`boolean`	no
`brandOrganic`	`boolean`	yes	Label the post as promotional content for the account's own business.
`brandedContent`	`boolean`	yes	Label the post as a paid partnership with a brand.
`disableComment`	`boolean`	no
`draft`	`boolean`	no	Deliver to the creator's TikTok inbox as a draft instead of publishing; needs the video.upload scope and keeps only the title and caption.
`scheduling`	`object`	no	Future operation time and optional wall-clock timezone.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "title": {
      "maxLength": 90,
      "type": "string"
    },
    "text": {
      "description": "Caption; hashtags and @mentions render as plain text. Up to 4,000 UTF-16 code units and 30 mentions.",
      "maxLength": 4000,
      "type": "string"
    },
    "media": {
      "minItems": 1,
      "maxItems": 35,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    },
    "privacyLevel": {
      "anyOf": [
        {
          "const": "PUBLIC_TO_EVERYONE",
          "type": "string"
        },
        {
          "const": "MUTUAL_FOLLOW_FRIENDS",
          "type": "string"
        },
        {
          "const": "FOLLOWER_OF_CREATOR",
          "type": "string"
        },
        {
          "const": "SELF_ONLY",
          "type": "string"
        }
      ]
    },
    "coverIndex": {
      "minimum": 0,
      "description": "Which image is the cover; defaults to the first.",
      "type": "integer"
    },
    "autoAddMusic": {
      "type": "boolean"
    },
    "brandOrganic": {
      "description": "Label the post as promotional content for the account's own business.",
      "type": "boolean"
    },
    "brandedContent": {
      "description": "Label the post as a paid partnership with a brand.",
      "type": "boolean"
    },
    "disableComment": {
      "type": "boolean"
    },
    "draft": {
      "description": "Deliver to the creator's TikTok inbox as a draft instead of publishing; needs the video.upload scope and keeps only the title and caption.",
      "type": "boolean"
    },
    "scheduling": {
      "additionalProperties": false,
      "description": "Future operation time and optional wall-clock timezone.",
      "type": "object",
      "properties": {
        "at": {
          "format": "date-time",
          "description": "Future execution time as an ISO-8601 string.",
          "type": "string"
        },
        "timezone": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "at"
      ]
    }
  },
  "required": [
    "media",
    "privacyLevel",
    "brandOrganic",
    "brandedContent"
  ]
}

Not offered

update: provider no endpoint
moderate: provider not supported
delete: provider no endpoint

Events

Backfill: not offered — not implemented.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`variant`	`"video" \| "photo"`	yes
`text`	`string`	no	Caption/body text for content.
`media`	`object[]`	no
`providerPermalink`	`string (uri)`	no	Canonical provider URL for content.
`embedUrl`	`string`	no
`engagement`	`object`	no	Provider-reported engagement counts.
`durationSeconds`	`number`	no
`isAd`	`boolean`	no
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"tiktok.posts.items"`	yes

`tiktok.posts.comments`

Comments on the account's posts, and replies to them.

`list`

List comments on one TikTok post, or the replies to one of its comments.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`mediaExternalId`	`string`	yes
`parentExternalId`	`string`	no
`includeReplies`	`boolean`	no	Include up to three replies inline under each top-level comment.
`status`	`"PUBLIC" \| "ALL"`	no	Visibility filter; defaults to ALL (hidden included).
`sort`	`"likes" \| "replies" \| "create_time"`	no
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "mediaExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "parentExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "includeReplies": {
      "description": "Include up to three replies inline under each top-level comment.",
      "type": "boolean"
    },
    "status": {
      "description": "Visibility filter; defaults to ALL (hidden included).",
      "anyOf": [
        {
          "const": "PUBLIC",
          "type": "string"
        },
        {
          "const": "ALL",
          "type": "string"
        }
      ]
    },
    "sort": {
      "anyOf": [
        {
          "const": "likes",
          "type": "string"
        },
        {
          "const": "replies",
          "type": "string"
        },
        {
          "const": "create_time",
          "type": "string"
        }
      ]
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "mediaExternalId"
  ]
}

`get`

Get one TikTok comment by provider id.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`mediaExternalId`	`string`	yes
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "mediaExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId",
    "mediaExternalId"
  ]
}

`publish`

Publish a TikTok comment: a top-level comment on a post, or a reply to a comment or a comment mention. The body is text, one image, or both.

Submit through POST /v1/publish-requests with contentType: "tiktok.posts.comments". These fields go in the item's args; connectedProfileId and variant are item fields.

Field	Type	Required	Description
`target`	`object`	yes	The provider content this publish targets, identified as events identify it.
`mediaExternalId`	`string`	no
`text`	`string`	yes	Comment text, up to 1,200 UTF-8 characters.
`media`	`object \| object[]`	no	At most one image; a TikTok comment carries a single picture.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "target": {
      "additionalProperties": false,
      "description": "The provider content this publish targets, identified as events identify it.",
      "type": "object",
      "properties": {
        "contentType": {
          "anyOf": [
            {
              "const": "tiktok.posts.comments",
              "type": "string"
            },
            {
              "const": "tiktok.posts.items",
              "type": "string"
            },
            {
              "const": "tiktok.posts.mentions",
              "type": "string"
            }
          ]
        },
        "externalId": {
          "description": "Provider-owned content identifier.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "contentType",
        "externalId"
      ]
    },
    "mediaExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "text": {
      "description": "Comment text, up to 1,200 UTF-8 characters.",
      "minLength": 1,
      "maxLength": 1200,
      "type": "string"
    },
    "media": {
      "minItems": 1,
      "maxItems": 1,
      "description": "At most one image; a TikTok comment carries a single picture.",
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    }
  },
  "required": [
    "target",
    "text"
  ]
}

Field	Type	Required	Description
`target`	`object`	yes	The provider content this publish targets, identified as events identify it.
`mediaExternalId`	`string`	no
`text`	`string`	no	Comment text, up to 1,200 UTF-8 characters.
`media`	`object \| object[]`	yes	At most one image; a TikTok comment carries a single picture.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "target": {
      "additionalProperties": false,
      "description": "The provider content this publish targets, identified as events identify it.",
      "type": "object",
      "properties": {
        "contentType": {
          "anyOf": [
            {
              "const": "tiktok.posts.comments",
              "type": "string"
            },
            {
              "const": "tiktok.posts.items",
              "type": "string"
            },
            {
              "const": "tiktok.posts.mentions",
              "type": "string"
            }
          ]
        },
        "externalId": {
          "description": "Provider-owned content identifier.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "contentType",
        "externalId"
      ]
    },
    "mediaExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "text": {
      "description": "Comment text, up to 1,200 UTF-8 characters.",
      "minLength": 1,
      "maxLength": 1200,
      "type": "string"
    },
    "media": {
      "minItems": 1,
      "maxItems": 1,
      "description": "At most one image; a TikTok comment carries a single picture.",
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    }
  },
  "required": [
    "target",
    "media"
  ]
}

`moderate`

Hide, unhide, like, or unlike a TikTok comment.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`mediaExternalId`	`string`	no	The post the comment is on. Required for hide and unhide; ignored by like and unlike, which TikTok addresses by comment id alone.
`action`	`"hide" \| "unhide" \| "like" \| "unlike"`	yes

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "mediaExternalId": {
      "minLength": 1,
      "description": "The post the comment is on. Required for hide and unhide; ignored by like and unlike, which TikTok addresses by comment id alone.",
      "type": "string"
    },
    "action": {
      "anyOf": [
        {
          "const": "hide",
          "type": "string"
        },
        {
          "const": "unhide",
          "type": "string"
        },
        {
          "const": "like",
          "type": "string"
        },
        {
          "const": "unlike",
          "type": "string"
        }
      ]
    }
  },
  "required": [
    "connectedProfileId",
    "externalId",
    "action"
  ]
}

`delete`

Delete a TikTok comment the account made.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId"
  ]
}

Not offered

update: provider not supported

Events

Backfill: not offered — not implemented.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`mediaExternalId`	`string`	yes
`text`	`string`	no	Caption/body text for content.
`media`	`object[]`	no
`author`	`object`	no	Provider actor reference for observed content.
`thread`	`object`	no	Parent/root identifiers for threaded contexts.
`hidden`	`boolean`	no
`pinned`	`boolean`	no
`liked`	`boolean`	no
`ownerAuthored`	`boolean`	no
`engagement`	`object`	no	Provider-reported engagement counts.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"tiktok.posts.comments"`	yes

`tiktok.posts.mentions`

@-mentions of the account in other users' captions and comments.

`list`

List the top mentions of the TikTok account in other users' captions or comments.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`variant`	`"caption" \| "comment"`	yes
`days`	`integer`	no	Look-back window in days; defaults to 90.
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "variant": {
      "anyOf": [
        {
          "const": "caption",
          "type": "string"
        },
        {
          "const": "comment",
          "type": "string"
        }
      ]
    },
    "days": {
      "minimum": 1,
      "maximum": 90,
      "description": "Look-back window in days; defaults to 90.",
      "type": "integer"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "variant"
  ]
}

`get`

Get one mention in full, hydrating a mention event: TikTok's webhook payload carries no engagement counts or thumbnail, and no comment text or author handle for a comment mention. Details stay readable for 48 hours after the webhook.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes	The mention's id: the comment id for a comment mention, the post id for a caption mention.
`mediaExternalId`	`string`	yes
`variant`	`"caption" \| "comment"`	yes
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "description": "The mention's id: the comment id for a comment mention, the post id for a caption mention.",
      "type": "string"
    },
    "mediaExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "variant": {
      "anyOf": [
        {
          "const": "caption",
          "type": "string"
        },
        {
          "const": "comment",
          "type": "string"
        }
      ]
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId",
    "mediaExternalId",
    "variant"
  ]
}

Not offered

publish: not applicable
update: not applicable
moderate: provider not supported
delete: not applicable

Events

Backfill: not offered — not implemented.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`variant`	`"caption" \| "comment"`	yes
`mediaExternalId`	`string`	yes
`commentExternalId`	`string`	no
`text`	`string`	no	Caption/body text for content.
`author`	`object`	no	Provider actor reference for observed content.
`media`	`object[]`	no
`providerPermalink`	`string (uri)`	no	Canonical provider URL for content.
`engagement`	`object`	no	Provider-reported engagement counts.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"tiktok.posts.mentions"`	yes

`tiktok.dm.threads`

The account's Business Messaging conversations.

`list`

List the TikTok Business Account's direct-message conversations from the last 90 days.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`variant`	`"stranger" \| "single"`	yes	stranger: message requests the account has not replied to; single: conversations it has replied in.
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "variant": {
      "description": "stranger: message requests the account has not replied to; single: conversations it has replied in.",
      "anyOf": [
        {
          "const": "stranger",
          "type": "string"
        },
        {
          "const": "single",
          "type": "string"
        }
      ]
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "variant"
  ]
}

Not offered

get: provider no endpoint
publish: not applicable
update: not applicable
moderate: provider not supported
delete: provider no endpoint

Events

content.tiktok.dm.threads.updated

Backfill: not offered — not implemented.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`variant`	`"stranger" \| "single"`	no
`updatedAt`	`string (date-time)`	no	Provider update timestamp as an ISO-8601 string.
`referral`	`object`	no
`lastReadAt`	`string (date-time)`	no	Provider update timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"tiktok.dm.threads"`	yes

`tiktok.dm.messages`

Messages in one Business Messaging conversation.

`list`

List the 20 most recent messages of one TikTok direct-message conversation.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`threadExternalId`	`string`	yes
`resolveMedia`	`boolean`	no	Resolve inbound images and videos to a fetchable URL, one extra call per attachment. The URL TikTok mints lasts 24 hours, so ask for it when the media is about to be shown.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "threadExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "resolveMedia": {
      "description": "Resolve inbound images and videos to a fetchable URL, one extra call per attachment. The URL TikTok mints lasts 24 hours, so ask for it when the media is about to be shown.",
      "type": "boolean"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "threadExternalId"
  ]
}

`publish`

Send a message into a TikTok conversation the user opened: text, optionally quoting one of its messages, or one image.

Submit through POST /v1/publish-requests with contentType: "tiktok.dm.messages". These fields go in the item's args; connectedProfileId and variant are item fields.

Field	Type	Required	Description
`threadExternalId`	`string`	yes
`text`	`string`	yes	Message text, up to 6,000 characters.
`target`	`object`	no	The provider content this publish targets, identified as events identify it.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "threadExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "text": {
      "description": "Message text, up to 6,000 characters.",
      "minLength": 1,
      "maxLength": 6000,
      "type": "string"
    },
    "target": {
      "additionalProperties": false,
      "description": "The provider content this publish targets, identified as events identify it.",
      "type": "object",
      "properties": {
        "contentType": {
          "const": "tiktok.dm.messages",
          "type": "string"
        },
        "externalId": {
          "description": "Provider-owned content identifier.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "contentType",
        "externalId"
      ]
    }
  },
  "required": [
    "threadExternalId",
    "text"
  ]
}

Field	Type	Required	Description
`threadExternalId`	`string`	yes
`media`	`object \| object[]`	yes	One image; TikTok sends a single picture per message. Staged, then uploaded to TikTok for a media_id.
`threadVariant`	`"stranger" \| "single"`	no

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "threadExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "media": {
      "minItems": 1,
      "maxItems": 1,
      "description": "One image; TikTok sends a single picture per message. Staged, then uploaded to TikTok for a media_id.",
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    },
    "threadVariant": {
      "anyOf": [
        {
          "const": "stranger",
          "type": "string"
        },
        {
          "const": "single",
          "type": "string"
        }
      ]
    }
  },
  "required": [
    "threadExternalId",
    "media"
  ]
}

Not offered

get: provider no endpoint
update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

content.tiktok.dm.messages.created

Backfill: not offered — not implemented.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`threadExternalId`	`string`	yes
`kind`	`"text" \| "image" \| "video" \| "sharePost" \| "emoji" \| "sticker" \| "template" \| "other"`	yes
`text`	`string`	no	Caption/body text for content.
`author`	`object`	no	Provider actor reference for observed content.
`recipient`	`object`	no	Provider actor reference for observed content.
`thread`	`object`	no	Parent/root identifiers for threaded contexts.
`attachments`	`object[]`	no
`source`	`string`	no
`autoMessageType`	`"welcomeMessage" \| "suggestedQuestion" \| "autoReply"`	no
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"tiktok.dm.messages"`	yes

TikTok

tiktok.posts.items

list

get

publish

Not offered

Events

tiktok.posts.comments

list

get

publish

moderate

delete

Not offered

Events

tiktok.posts.mentions

list

get

Not offered

Events

tiktok.dm.threads

list

Not offered

Events

tiktok.dm.messages

list

publish

Not offered

Events

On this page

`tiktok.posts.items`

`list`

`get`

`publish`

`tiktok.posts.comments`

`list`

`get`

`publish`

`moderate`

`delete`

`tiktok.posts.mentions`

`list`

`get`

`tiktok.dm.threads`

`list`

`tiktok.dm.messages`

`list`

`publish`