Skip to content

TikTok Messaging API

The TikTok Messaging API supports three jobs for a product inbox: List conversations for a linked account, page through message history inside a thread, and send direct messages as replies.

List TikTok conversations request
curl "{{API_BASE_URL}}/v1/messages?platform=tiktok&accountId=acc_tt_012&limit=20" \
  -H "x-access-key: your-api-key"
Illustrative request
Example line 1

curl "{{API_BASE_URL}}/v1/messages?platform=tiktok&accountId=acc_tt_012&limit=20" \

Illustrative request
Example line 2

-H "x-access-key: your-api-key"

The captured request and response shown in the List TikTok conversations request and List TikTok conversations response examples define the parity contract to implement against.

TikTok Messaging API: list conversations, read history, and reply

Start by enumerating threads for a linked TikTok account. Each thread entry should carry who is involved, how to display them, a preview of the newest item, and a sort key for recency. Next, open a single thread to walk backward through earlier items, where every item identifies its author and when it was created, letting your client reconstruct the exchange in order. Finally, post a reply in one operation; the acknowledgement includes an identifier for the item just created, which your inbox can store to confirm delivery and match the item to its thread. TikTok uses the shared /v1/messages shape, so the same client pattern can serve other messaging surfaces.

Exact contract sheet

For the captured list operation, the page-local contract is POST {{API_BASE_URL}}/v1/messages. Supply platform=tiktok, accountId=acc_tt_012, and limit=20 as query values, and authenticate with the x-access-key header. Here accountId selects the linked TikTok account to query. The precise request is shown in the List TikTok conversations request example, and the precise payload to parse is shown in the List TikTok conversations response example.

Field map for conversations, participants, and lastMessage

Before rendering an inbox, align your models to the returned structure. At the top level you receive success, selfId, and selfUsername; in the sample, selfUsername is yourbrand for the linked account. Inside conversations, each object provides id, participants, lastMessage, and updatedTime. A participant object provides id, name, username, and profilePictureUrl, which together cover identity and avatar display. The lastMessage object provides id, text, from, and timestamp, with from nested as id and name. Keep nextCursor for fetching a subsequent page, keep updatedTime for ordering threads, and keep lastMessage.id to deduplicate the preview you already rendered.

Worked parity example

Use the sample values to test your parser offline. Query with platform=tiktok, accountId=acc_tt_012, and limit=20. Expect selfId 6889904165124932609 and selfUsername yourbrand. The single sample thread is tt_conv_100000000000001, involving Jane Doe and Your Brand, with a preview asking where to buy the product from the video. Both updatedTime and the preview timestamp read 2026-08-05T16:40:00Z. When nextCursor is non-empty, request the following page with it instead of treating page one as exhaustive.

Failure matrix and checks

Plan for these checks during development. A reply can fail for one recipient because that person's TikTok settings do not permit inbound messages from the linked account; surface that outcome per recipient rather than marking the whole integration down. Confirm availability for the specific account before depending on TikTok messaging in production paths. Treat history and reply parameters as unconfirmed until their exact contracts are obtained, since the list sample does not define them. Finally, validate accountId against a linked account before interpreting an empty conversations array as a genuinely empty inbox.

Inbox-building decision criteria

An inbox built on this contract needs thread ordering, participant display data, and preview text. That means persisting updatedTime, username, profilePictureUrl, lastMessage text, and lastMessage timestamp from the list response, then using history calls to fill in the full exchange and reply calls to respond. Linking happens via OAuth, so end users connect TikTok without your team operating a separate developer application or storing platform tokens. Because the endpoint shape is shared, evaluate additional platforms by reusing the same request and response handling.

List conversations request contract
FieldType in samplePurpose
MethodPOSTPage-local contract label for the list request
Path/v1/messagesUnified messages endpoint
platform (query)string: tiktokSelects TikTok
accountId (query)string: acc_tt_012Connected TikTok account identifier
limit (query)number: 20Page size for the list request
x-access-key (header)string: your-api-keyAPI key authentication

Captured from the list-conversations sample; history and reply request fields are not captured and are held as gaps.

List conversations response field map
FieldType in samplePurpose
successboolean: trueWhether the request succeeded
selfIdstringConnected account ID
selfUsernamestring: yourbrandConnected account username
conversations[].idstringConversation identifier
conversations[].participants[].idstringParticipant ID
conversations[].participants[].namestringParticipant display name
conversations[].participants[].usernamestringParticipant username
conversations[].participants[].profilePictureUrlstringParticipant profile picture URL
conversations[].lastMessage.idstringMost recent message ID
conversations[].lastMessage.textstringMost recent message text
conversations[].lastMessage.from.idstringSender ID
conversations[].lastMessage.from.namestringSender display name
conversations[].lastMessage.timestampstring (ISO 8601)Most recent message timestamp
conversations[].updatedTimestring (ISO 8601)Conversation updated time for sorting
nextCursorstringPagination cursor for the next page

Captured from the list-conversations sample response.

Failure and decision matrix
CaseWhat to checkHandling
Recipient DM settings reject a sendWhether the recipient accepts messages from the connected accountTreat as a per-recipient rejection and surface the reason returned by the API
TikTok messaging availabilityCurrent platform availability for the connected accountCheck status or dashboard before building a hard dependency
Missing or invalid accountIdWhether accountId identifies a connected TikTok accountDo not treat an empty result as a confirmed empty inbox until accountId is verified
Message history requestExact history endpoint parameters are not capturedHold implementation until the history contract is confirmed
Send reply requestExact reply endpoint parameters are not captured beyond the sent message ID claimHold implementation until the reply contract is confirmed

No status codes are captured in the source; do not invent them.

Frequently asked questions

What can I do with TikTok messaging through this API?

You can enumerate DM threads, open a thread to page through earlier items, and post a reply, using the shared /v1/messages surface for TikTok.

Do I need to create a TikTok developer app?

No separate TikTok developer application is required for this flow. Account linking happens through OAuth, with credentials managed outside your codebase.

Can I message anyone at any time?

No. TikTok's own privacy controls decide whether a given person will accept inbound DMs. When those controls block delivery, the attempt fails for that person and an explanation is returned.

Is TikTok messaging available today?

Do not assume TikTok messaging is live for your account. Confirm current availability in the status area or dashboard before making it a hard dependency.

Is there a UI, or is it API only?

Both options exist. A dashboard inbox supports reading and responding, while the API exposes equivalent operations for embedding in your own product.

How much does the Messaging API cost?

Each Messages API call is billed at 1 credit. That applies separately to listing threads, fetching thread contents, and posting a reply.

List TikTok conversations response
{
  "success": true,
  "selfId": "6889904165124932609",
  "selfUsername": "yourbrand",
  "conversations": [
    {
      "id": "tt_conv_100000000000001",
      "participants": [
        {
          "id": "6889904165124900000",
          "name": "Jane Doe",
          "username": "jane_doe",
          "profilePictureUrl": "https://p16-sign.tiktokcdn.com/..."
        },
        {
          "id": "6889904165124932609",
          "name": "Your Brand",
          "username": "yourbrand",
          "profilePictureUrl": "https://p16-sign.tiktokcdn.com/..."
        }
      ],
      "lastMessage": {
        "id": "tt_msg_aWdfbXNnXzEyMw",
        "text": "An example comment.",
        "from": {
          "id": "6889904165124900000",
          "name": "Jane Doe"
        },
        "timestamp": "2026-08-05T16:40:00Z"
      },
      "updatedTime": "2026-08-05T16:40:00Z"
    }
  ],
  "nextCursor": "QVFIUl9..."
}