登入開始免費試用
easyCoexistence 官方 API

透過 API 查找 TikTok 提及:找出提及某帳戶的帖子與留言

TikTok 的 Mentions API 屬於 API for Business,透過 GET /business/mention/video/list/ 返回過去 90 天內在說明文字中 @提及商家帳戶的前 1,000 則公開帖子;透過 /business/mention/comment/list/ 返回提及該帳戶的前 1,000 則留言或回覆。兩者都需要 biz.brand.insights 範圍,以及具備 Advanced Access 或 Verified Business Account 的帳戶。

easyCoexistence 透過 TikTok 的 API for Business 連接 TikTok 帳戶:Claude、ChatGPT 或您自己的程式可以讀取其留言、以專用工具回覆留言,並即時接收其留言事件,而 get_social_credentials 會為您自己的程式提供其他 API for Business 呼叫所需的權杖,包括 TikTok 向該帳戶開放的 Mentions 端點。

1,000

/business/mention/video/list/ 每次最多返回 100 則提及帖子,均為過去 90 天內的公開帖子。

24 to 48 hours

提及發生至可透過 Mentions API 查詢之間的大約延遲。

2 to 3 hours

用戶在說明文字或留言中提及商家後,TikTok 為提及 Webhook 給出的延遲。

Once a day

UTC 0 時至 7 時刷新後,TikTok 建議每個帳戶對各 Mentions 端點的呼叫頻率。

comment.list

除 biz.brand.insights 外,/business/mention/comment/list/ 還需要的範圍,用於返回提及該帳戶的留言。

Mentions API 有哪些端點?

共有六個讀取端點,每個都是對 https://business-api.tiktok.com/open_api/v1.3 的 GET 請求,帳戶的存取權杖放在 Access-Token 標頭中,其 open_id 作為 business_id。兩個列出提及,兩個總結提及帖子的內容,另兩個獲取由 Webhook 通知的單則提及:

/business/mention/video/list/Up to 1,000 posts whose caption mentions the account, 100 a page
/business/mention/comment/list/Up to 1,000 comments or replies whose text mentions the account
/business/mention/top_word/list/The 20 keywords that appear most in mentioned posts' captions
/business/mention/top_hashtag/list/The 20 hashtags used most in those captions
/business/mention/video/get/One mentioned post from a webhook event, within 48 hours
/business/mention/comment/get/One comment mention from a webhook event, within 48 hours

哪些帖子與留言算作提及?

在帖子說明文字或留言內容中以 @ 標記帳戶用戶名,且位於公開帖子或留言上,並通過 TikTok 的其他篩選條件的內容:

  • 帖子發布於過去 90 天內。
  • 作者不屬未成年或年齡不明:在歐洲,17 歲或以下視為未成年;在美國及其他地區,12 歲或以下視為未成年。
  • 排名位於提及該用戶名的帖子或留言中讚好數最高的前 1,000 則之內。
  • 符合這些規則的商家自己的帖子同樣計算在內。
  • 純粹只有提及、沒有其他文字的留言,排名會較低。

使用前帳戶需要具備什麼?

符合資格的帳戶、具備正確權限的應用程式、存取權杖上的範圍,以及擁有人授權應用程式後等待一天:

  • Advanced Access 或 Verified Business Account;/business/get/ 上的 has_advanced_access 會顯示哪些帳戶符合資格。
  • 開發者應用程式上的 Mentions 權限,帖子列明為 Mentions, Content,留言列明為 Mentions, Comment。
  • 存取權杖上的 biz.brand.insights,以及用於留言提及的 comment.list。
  • 根據 TikTok 入門指南,授權後須等待 24 小時才能進行首次拉取。

如何列出提及帳戶的帖子?

使用 GET /business/mention/video/list/。fields 用於選擇欄位,預設為 item_id 與 caption,另可按需請求 create_time、video_link、likes、comments、shares、thumbnail_url、views、reach 與 creator_handle_name。sort_field 可為 CREATE_TIME、LIKES、COMMENTS 或 SHARES,配合 sort_type 的 ASC 或 DESC;number_of_days 縮小 90 天範圍;regions 篩選特定地區的創作者;cursor 配合 has_more 翻頁。views 與 reach 低於 1,000 時返回 null,縮圖連結有效 48 小時:

Mentioned posts, sorted by likes
curl --get 'https://business-api.tiktok.com/open_api/v1.3/business/mention/video/list/' \
  -H 'Access-Token: <ACCESS_TOKEN>' \
  --data-urlencode 'business_id=<OPEN_ID>' \
  --data-urlencode 'fields=["item_id","video_link","caption","likes","creator_handle_name"]' \
  --data-urlencode 'sort_field=LIKES' \
  --data-urlencode 'number_of_days=30' \
  --data-urlencode 'max_count=100'

{
  "code": 0,
  "message": "OK",
  "request_id": "<REQUEST_ID>",
  "data": {
    "videos": [
      {
        "item_id": "<ITEM_ID>",
        "video_link": "https://www.tiktok.com/@/video/<ITEM_ID>",
        "caption": "<CAPTION>",
        "likes": 243,
        "creator_handle_name": "<HANDLE>"
      }
    ],
    "cursor": 100,
    "has_more": true
  }
}

如何列出提及帳戶的留言?

使用 GET /business/mention/comment/list/,其權杖同時需要 comment.list。預設返回 comment_id 與 comment_text;item_id、video_link、caption、video_likes、thumbnail_url、commenter_display_name、comment_type、comment_create_time 與 comment_likes 需按需請求,其中 comment_type 的值為 COMMENT 或 REPLY。每頁預設 10 則,除非 max_count 要求最多 100 則,並可按 VIDEO_LIKES、COMMENT_CREATE_TIME 或 COMMENT_LIKES 排序。由於 TikTok 的信任與安全政策,即使 has_more 仍為 true,頁面也可能返回較少的結果。

如何回覆提及?

透過 TikTok 的留言回覆端點。POST /business/comment/reply/create/ 需要 business_id、設為留言提及中 item_id 的 video_id、comment_id,以及最多 1,200 個字元的 text。回覆會公開顯示在該留言之下,無論該留言位於哪則帖子。TikTok 的參考文件指明該操作需要 comment.list.manage 範圍,帳戶要求與上文相同。其 Mentions 參考文件只列出針對留言提及的回覆。

提及能否透過 Webhook 送達?

可以。擁有 Mentions 權限的應用程式呼叫 POST /business/webhook/update/,並將 event_type 設為 BRAND_MENTION,之後 TikTok 會在提及發生後最多兩至三小時內發送 brand.mention.event,並以 Tiktok-Signature 簽署,與其他 Webhook 相同。content 是序列化的 JSON 字串,內容包括:

  • type_of_event:CREATE、EDIT 或 PRIVACY_CHANGE,後者表示帖子的隱私設定有更改。
  • mention_type:COMMENT 表示留言或回覆,VIDEO_MENTION 表示說明文字中的提及,此時 comment_id 為 0。
  • video_id、video_create_time、share_url 與 video_caption,用於描述帖子。
  • open_id_of_mentioned_user、unique_name_of_mentioned_user,以及 unique_identifier(留言者 ID,在各 API 間保持不變)。
  • 詳情可於事件發生 48 小時內,透過 /business/mention/video/get/ 或 /business/mention/comment/get/ 獲取。

應多久呼叫一次 Mentions 端點?

TikTok 建議每個端點、每個帳戶每天呼叫一次,並於 UTC 7 時之後進行。各端點共用開發者應用程式的全域速率限制,但 TikTok 會在 UTC 0 時至 7 時之間刷新前一天的數據,同一天內再次拉取並無必要。新的提及大約需要 24 至 48 小時才會出現在列表端點中,因此 Webhook 是更快的訊號。

品牌主題標籤如何運作?

它們讓提及範圍擴大到使用商家所選主題標籤的帖子。POST /business/mention/hashtag/add/ 每次請求最多啟用 10 個主題標籤,每個帳戶最多 50 個。主題標籤可取自 /business/mention/hashtag/verify/list/ 建議的最多 100 個,也可包含完整用戶名,例如 @TikTok 的對應標籤為 #drinktiktok。已啟用的主題標籤七天內無法移除,其帖子於啟用 24 小時後可在 /business/mention/hashtag/video/list/ 中查到。

easyCoexistence 能用 TikTok 提及做什麼?

將該帳戶的權杖交給你自己的程式碼:get_social_credentials 會返回權杖與 business_id,用於 business/ 路徑下的 API for Business 路徑,包括 business/mention/。當帳戶與應用程式符合上述要求時,TikTok 會作出回應。提及 Webhook 不在此範圍內:easyCoexistence 只為其應用程式訂閱留言事件,並將 business/webhook/ 路徑保留給自身使用,因此 BRAND_MENTION 事件不會被轉發。帳戶自身帖子的留言(包括提及在內)仍會以 comment.update 事件送達,並由 set_social_webhook_destination 轉發:

Comment mentions and a reply, from your own code
GET https://business-api.tiktok.com/open_api/v1.3/business/mention/comment/list/
  ?business_id=<BUSINESS_ID>
  &fields=["item_id","comment_id","comment_text","commenter_display_name","comment_type"]
  &sort_field=COMMENT_CREATE_TIME&max_count=50
Access-Token: <ACCESS_TOKEN>

POST https://business-api.tiktok.com/open_api/v1.3/business/comment/reply/create/
Access-Token: <ACCESS_TOKEN>
{ "business_id": "<BUSINESS_ID>", "video_id": "<ITEM_ID>", "comment_id": "<COMMENT_ID>", "text": "Thanks for the mention!" }

常見錯誤

  • 為未具備 Advanced Access 的帳戶呼叫 Mentions 端點。TikTok 只向具備 Advanced Access 或 Verified Business Account 的帳戶提供,/business/get/ 上的 has_advanced_access 會顯示是否符合。
  • 在 UTC 午夜後立即拉取提及。TikTok 在 UTC 0 時至 7 時之間刷新前一天的數據,因此 7 時之後拉取才能看到整天的內容。
  • 把 comment_id 為 0 當作留言。在提及 Webhook 中,這表示提及位於帖子的說明文字,mention_type 為 VIDEO_MENTION。
  • 為試用而啟用品牌主題標籤。TikTok 規定已啟用的主題標籤須保留七天才可移除,並且會計入帳戶的 50 個上限之中。
使用 EasyCoexistence 完成這項設定

每個連接每月 US$ 9 至 US$ 0.75,連接越多越便宜,首 3 天免費試用。

常見問題

能在 TikTok API 中找到提及我帳戶的影片嗎?

能,是指說明文字中 @ 提及其用戶名的帖子。/business/mention/video/list/ 最多返回過去 90 天內的 1,000 則公開帖子,creator_handle_name 會標示每位創作者。

私人 TikTok 帖子會計為提及嗎?

不會。Mentions API 只計算過去 90 天內的公開帖子,並會排除作者未成年或年齡不明的情況:歐洲為 17 歲或以下,美國及其他地區為 12 歲或以下。

TikTok 提及需要多久才會顯示?

透過列表端點大約需要 24 至 48 小時,透過 Mentions Webhook 則最多兩至三小時。

easyCoexistence 能在 TikTok 帳戶被提及時發出警報嗎?

不能以轉發事件的形式實現,因為它轉發的是 TikTok 的留言事件,而非提及事件。在帳戶符合資格的情況下,您自己的程式可以憑 get_social_credentials 提供的權杖,按需讀取提及。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期