tiktok-business-messaging
Integrate with the TikTok Business API — OAuth, direct messages, conversations, media, comments, auto-messages (welcome/suggested/chat prompts), video insights, comment-to-message direct replies, and webhook subscriptions for DIRECT_MESSAGE / BRAND_MENTION / VIDEO / COMMENT events. Use when working with `business-api.tiktok.com/open_api/v1.3/business/*` or `tt_user/oauth2/*` endpoints; building TikTok DM bots, inboxes, or comment automation for Business Accounts; handling `im_*`, `brand.mention.event`, `comment.update`, or `post.publish.*` webhooks; or when the user mentions TikTok Business Messaging, TikTok DMs, TikTok Business Account auth, brand mention webhooks, video insights, chat prompts, or `business_id`/`open_id` tokens.
- License 许可
- MIT
- 所属仓库
- justomat/skills
- 最近更新
- 2026-09-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tiktok-business-messaging
- description
- Integrate with the TikTok Business API — OAuth, direct messages, conversations, media, comments, auto-messages (welcome/suggested/chat prompts), video insights, comment-to-message direct replies, and webhook subscriptions for DIRECT_MESSAGE / BRAND_MENTION / VIDEO / COMMENT events. Use when working with `business-api.tiktok.com/open_api/v1.3/business/*` or `tt_user/oauth2/*` endpoints; building TikTok DM bots, inboxes, or comment automation for Business Accounts; handling `im_*`, `brand.mention.event`, `comment.update`, or `post.publish.*` webhooks; or when the user mentions TikTok Business Messaging, TikTok DMs, TikTok Business Account auth, brand mention webhooks, video insights, chat prompts, or `business_id`/`open_id` tokens.
02 资源文件 10
- 参考文档references/authentication.md3.0 KB
- 参考文档references/comments.md4.9 KB
- 参考文档references/conversations.md2.5 KB
- 参考文档references/direct-reply.md2.1 KB
- 参考文档references/media.md1.4 KB
- 参考文档references/messages.md5.7 KB
- 参考文档references/publish.md1.8 KB
- 参考文档references/videos.md3.3 KB
- 参考文档references/webhook-events.md18.5 KB
- 参考文档references/webhooks.md2.0 KB
03 SKILL.md 正文
TikTok Business API
Quick guide. The full OpenAPI 3.1 spec (every field, enum, example, "Try-it-now") lives at https://tiktok-business-api-docs.pages.dev/ — go there for exhaustive schemas. This file plus references/ covers gotchas, common workflows, and progressive lookup.
Quick start
Base URL: https://business-api.tiktok.com/open_api/v1.3/
Auth header on /business/* calls: Access-Token: <short-term token>. Token valid 1 day; refresh token valid 1 year.
- Share the TikTok account holder authorization URL with the business; capture
codefrom the redirect. POST /tt_user/oauth2/token/withauth_code(valid 10 min, single-use) → returnsaccess_token,refresh_token,open_id.- Use
open_idasbusiness_idon every/business/*call. POST /tt_user/oauth2/refresh_token/before the 1-day expiry.
Send a text message:
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/business/message/send/' \
-H "Access-Token: $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-d '{"business_id":"'"$OPEN_ID"'","recipient_type":"CONVERSATION","recipient":"'"$CONV"'","message_type":"TEXT","text":{"body":"Hi"}}'
Hard constraints (gotchas)
These are environment-specific facts that defy reasonable assumptions — read these before designing anything:
- Rate limit: 10 QPS across Business Messaging endpoints. On error
40100, back off. - 48-hour reply windows (non-mutual follow conversations):
- After user's first message → up to 10 replies in 48 h.
- After each user reply → unlimited for 48 h.
- After 48 h of silence → only 3 more messages until they reply again.
- Cannot initiate — never message a user who hasn't messaged the business first. The sole exception is
direct_replyto high-intent comments (VN/ID/TH accounts only). - Message is text XOR image, never both. Text body cap: 6,000 chars (incl. spaces/emoji).
conversation_idencoding: URL-encode+as%2Bin query strings, or you'll get "Param conversation_id is invalid".- EU/EEA/UK senders trigger
im_receive_msg_eu(notim_receive_msg). That payload omits sender, conversation_id, and content — you must pollconversation/list/+content/list/to retrieve the body. - Webhook
contentis a stringified JSON — alwaysJSON.parse(payload.content). - Image download requires header
x-user: <Access-Token>when GETting thedownload_url. - Big number IDs:
comment.updatewebhook serializescomment_id/video_id/parent_comment_idas bare numbers exceedingNumber.MAX_SAFE_INTEGER. Use a BigInt reviver orjson-bigint— naïveJSON.parsesilently truncates. - Expiry table: access token 1 d · refresh token 1 y · auth code 10 min (single-use) ·
media_id30 d ·download_url24 h · profile/sticker/AI-emoji URLs perx-expires(typically 30 d). - Pagination caps: conversation list max 100 (past 90 days only). Message list max 20 most recent per conversation. Comment list returns dupes past the first 500.
- Comment-to-Message only for Business Accounts in VN/ID/TH replying to APAC/LATAM/METAP accounts; five eligibility conditions must all hold per reply (see
references/direct-reply.md).
Common errors
| Code | Meaning | Fix |
|---|---|---|
| 40001 | No permission | Check app scopes; re-authorize user if scopes changed |
| 40002 | Param error | Read message for the field name |
| 40007 | Object doesn't exist | Verify ID + URL path |
| 40064 | DM blocked | Likely outside 48 h window or initiating cold conversation |
| 40100 | Rate limited | Back off; respect 10 QPS |
| 40105 | Bad/expired access token | Refresh via /tt_user/oauth2/refresh_token/ |
| 40908 | Unsupported file type | JPG/PNG only, ≤ 3 MB for image upload |
| 51065 | System error | Retry with backoff; escalate if persistent |
Endpoint map & progressive disclosure
26 endpoints across 9 categories. Load only the reference file whose topic you're working on — each lives in references/:
| Category | Load file | When |
|---|---|---|
| Authentication | references/authentication.md |
Implementing OAuth flow, refreshing tokens, or introspecting scopes (/tt_user/oauth2/*, /tt_user/token_info/get/) |
| Messages | references/messages.md |
Sending DMs (/business/message/send/), templates, sender actions, or managing welcome / suggested questions / chat prompts (/business/message/auto_message/*) |
| Conversations | references/conversations.md |
Listing conversations or reading message history (/business/message/conversation/list/, /content/list/) |
| Media | references/media.md |
Uploading or downloading images/video attachments (/business/message/media/upload/, /download/, /capabilities/get/) |
| Direct Reply | references/direct-reply.md |
Toggling Comment-to-Message or replying to a high-intent comment (/business/message/direct_reply/*) |
| Comments | references/comments.md |
Reading or replying to comments on owned videos (/business/comment/*) |
| Publish | references/publish.md |
Polling publish status (/business/publish/status/) |
| Videos | references/videos.md |
Listing posts and engagement insights (/business/video/list/) |
| Webhooks | references/webhooks.md |
Creating, listing, or deleting webhook subscriptions (/business/webhook/*) |
| Webhook event payloads | references/webhook-events.md |
Implementing a callback handler, or you encounter any of: im_* event names, brand.mention.event, comment.update, post.publish.*, the DIRECT_MESSAGE/BRAND_MENTION/VIDEO/COMMENT event_type values, or a webhook content JSON payload |
Canonical schema source: https://tiktok-business-api-docs.pages.dev/ — full OpenAPI 3.1 spec with every field, enum, and example. Load when you need an exhaustive schema for a specific endpoint.
Workflows
Inbound DM → reply:
DIRECT_MESSAGEwebhook fires. Handle bothim_receive_msgandim_receive_msg_eu— seereferences/webhook-events.md§ EU/EEA caveat (the EU variant is stripped; poll to retrieve content).- Parse the envelope's
contentfield (stringified JSON) to getconversation_id. POST /business/message/send/withrecipient_type=CONVERSATION,recipient=<conversation_id>.
Send an image:
GET /business/message/capabilities/get/withcapability_types=["IMAGE_SEND"]for that conversation. Image sharing isn't available in all country pairs.POST /business/message/media/upload/(multipart, JPG/PNG ≤ 3 MB) →media_id(valid 30 d).POST /business/message/send/withmessage_type=IMAGE,image.media_id=<media_id>.
Reply to a high-intent comment (Comment-to-Message):
- Verify
direct_reply/get/returnsoperation_status=ENABLE. If not,direct_reply/update/to enable. - From the
im_receive_high_intent_commentwebhook capturecomment_id. POST /business/message/send/withdirect_reply.reply_type=COMMENT_REPLY,comment_reply.comment_id=<id>,message_type=TEXT.
Comment lifecycle webhook → fetch body:
comment.updatewebhook fires (within 5 min of any comment change) withcomment_id,video_id,comment_action. The body is NOT in the payload.- For
insertevents:GET /business/comment/list/?comment_ids=[<comment_id>]to fetch text/author/likes. - For
deleteevents: the comment is gone — the webhook is the only record.
Video publish lifecycle:
POST /business/video/publish/returnsshare_id.- Either poll
GET /business/publish/status/?publish_id=<share_id>until terminal, or subscribe to theVIDEOwebhook for the four-stage lifecycle (post.publish.failed/complete/publicly_available/no_longer_publicly_available). post_idfirst appears inpost.publish.publicly_available(or inpost_ids[]on the polling endpoint when status flips toPUBLISH_COMPLETE— may take up to 3 min). Use it asvideo_idsfilter in/business/video/list/.
Manage chat prompts (auto-messages):
POST /business/message/auto_message/status/update/withCHAT_PROMPT+ENABLE. Destructive: if any chat prompts already exist, enabling disables all of them.POST /business/message/auto_message/create/once per prompt (max 6). Wait foraudit_status=APPROVEDviaauto_message/get/(a few seconds to ~2–3 h).POST /business/message/auto_message/sort/to reorder — pass all prompt IDs in the desired order.
Permission scopes
Webhook event types require specific user-granted scopes to remain valid. Check granted scopes via POST /tt_user/token_info/get/ (see references/authentication.md):
| Webhook | Scope required |
|---|---|
im_* (DIRECT_MESSAGE) |
Business Messaging permission |
im_auto_message_* |
Additionally requires message.list.read |
comment.update (COMMENT) |
comment.list |
post.publish.* (VIDEO) |
TikTok Accounts > Business Content |
brand.mention.event |
Mentions permission |
04 同仓库更多 Skills
why
Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
unslop
Cut AI tells from any writing. Must always apply.
typescript-best-practices
TypeScript best practices. Use when reading or editing any .ts or .tsx file.
technical-writing
Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for /technical-writing or when writing or reviewing docs, RFCs, readmes, PR descriptions, or commit messages.
teach
Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'.
tdd
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.