透過 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 端點。
/business/mention/video/list/ 每次最多返回 100 則提及帖子,均為過去 90 天內的公開帖子。
提及發生至可透過 Mentions API 查詢之間的大約延遲。
用戶在說明文字或留言中提及商家後,TikTok 為提及 Webhook 給出的延遲。
UTC 0 時至 7 時刷新後,TikTok 建議每個帳戶對各 Mentions 端點的呼叫頻率。
除 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 通知的單則提及:
哪些帖子與留言算作提及?
在帖子說明文字或留言內容中以 @ 標記帳戶用戶名,且位於公開帖子或留言上,並通過 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 小時:
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 轉發:
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 個上限之中。
每個連接每月 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 監察
驗證日期