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.
curl "{{API_BASE_URL}}/v1/messages?platform=tiktok&accountId=acc_tt_012&limit=20" \
-H "x-access-key: your-api-key"curl "{{API_BASE_URL}}/v1/messages?platform=tiktok&accountId=acc_tt_012&limit=20" \
-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.
| Field | Type in sample | Purpose |
|---|---|---|
| Method | POST | Page-local contract label for the list request |
| Path | /v1/messages | Unified messages endpoint |
| platform (query) | string: tiktok | Selects TikTok |
| accountId (query) | string: acc_tt_012 | Connected TikTok account identifier |
| limit (query) | number: 20 | Page size for the list request |
| x-access-key (header) | string: your-api-key | API key authentication |
Captured from the list-conversations sample; history and reply request fields are not captured and are held as gaps.
| Field | Type in sample | Purpose |
|---|---|---|
| success | boolean: true | Whether the request succeeded |
| selfId | string | Connected account ID |
| selfUsername | string: yourbrand | Connected account username |
| conversations[].id | string | Conversation identifier |
| conversations[].participants[].id | string | Participant ID |
| conversations[].participants[].name | string | Participant display name |
| conversations[].participants[].username | string | Participant username |
| conversations[].participants[].profilePictureUrl | string | Participant profile picture URL |
| conversations[].lastMessage.id | string | Most recent message ID |
| conversations[].lastMessage.text | string | Most recent message text |
| conversations[].lastMessage.from.id | string | Sender ID |
| conversations[].lastMessage.from.name | string | Sender display name |
| conversations[].lastMessage.timestamp | string (ISO 8601) | Most recent message timestamp |
| conversations[].updatedTime | string (ISO 8601) | Conversation updated time for sorting |
| nextCursor | string | Pagination cursor for the next page |
Captured from the list-conversations sample response.
| Case | What to check | Handling |
|---|---|---|
| Recipient DM settings reject a send | Whether the recipient accepts messages from the connected account | Treat as a per-recipient rejection and surface the reason returned by the API |
| TikTok messaging availability | Current platform availability for the connected account | Check status or dashboard before building a hard dependency |
| Missing or invalid accountId | Whether accountId identifies a connected TikTok account | Do not treat an empty result as a confirmed empty inbox until accountId is verified |
| Message history request | Exact history endpoint parameters are not captured | Hold implementation until the history contract is confirmed |
| Send reply request | Exact reply endpoint parameters are not captured beyond the sent message ID claim | Hold 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.
{
"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..."
}