通过 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 权限范围,且账户须已开通高级访问权限或为已验证商业账户。
easyCoexistence 通过 TikTok 的 API for Business 连接 TikTok 账户:Claude、ChatGPT 或您自己的代码可使用专用工具读取账户评论并回复,并接收其评论事件,同时 get_social_credentials 会向您自己的代码提供令牌,用于其他 API for Business 调用,在 TikTok 对账户开放时也包括 Mentions 端点。
/business/mention/video/list/ 返回的帖子上限,均为过去 90 天内的公开帖子,每次请求最多 100 条。
用户提及发生到可通过 Mentions API 查询之间的大约延迟。
用户在说明文字或评论中提及业务账户后,TikTok 给出的 Mentions Webhook 延迟。
TikTok 建议每个账户调用各 Mentions 端点的频率,即在 UTC 时间凌晨 0 点至 7 点刷新之后。
除 biz.brand.insights 外,/business/mention/comment/list/ 返回提及账户的评论还需要的权限范围。
Mentions API 有哪些端点?
共六个只读端点,均为对 https://business-api.tiktok.com/open_api/v1.3 的 GET 请求。请求头 Access-Token 中填写账户的访问令牌,business_id 填写其 open_id。其中两个列出提及,两个汇总被提及帖子的内容,另外两个获取由 Webhook 通知的单条提及:
哪些帖子和评论算作提及?
在帖子说明文字或评论文本中用 @ 标注账户用户名、且为公开内容、并通过 TikTok 其他筛选的,即算作提及:
- 帖子发布于过去 90 天内。
- 作者不是未成年人,也不是年龄不明者:欧洲 17 岁及以下算作未成年,美国及其他地区 12 岁及以下算作未成年。
- 属于提及该用户名的前 1,000 条最受欢迎帖子或评论。
- 业务账户自己的帖子,只要符合这些规则,同样算作提及。
- 只包含提及本身、没有其他文字的评论,排名较靠后。
使用前账户需要具备什么?
需要符合条件的账户、拥有正确权限的应用、访问令牌上的权限范围,以及账户所有者授权应用后等待一天:
- 已开通高级访问权限或为已验证商业账户;/business/get/ 上的
has_advanced_access显示哪些账户符合条件。 - 开发者应用上的 Mentions 权限,帖子对应 Mentions, Content,评论对应 Mentions, Comment。
- 访问令牌上需要 biz.brand.insights,评论提及还需要 comment.list。
- 授权后等待 24 小时再进行首次拉取,这是 TikTok 入门指南的要求。
如何列出提及该账户的帖子?
使用 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 用于翻页。播放量低于 1,000 时,views 和 reach 返回 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 权限范围及相同的账户要求,其提及参考文档仅将回复功能列为评论提及的操作。
提及能否通过 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 会返回用于 API for Business 下 business/ 路径(包括 business/mention/)的令牌和 business_id。当账户和应用符合上述要求时,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!" }常见错误
- 在没有高级访问权限的账户上调用 Mentions 端点。TikTok 只向拥有高级访问权限或已验证商业账户的账户开放,/business/get/ 上的 has_advanced_access 会显示是否符合条件。
- 在 UTC 时间午夜后立即拉取提及。TikTok 会在 UTC 时间 0 点至 7 点之间刷新前一天的数据,因此 7 点之后的拉取才能看到整天的数据。
- 把 comment_id 为 0 理解为评论。在提及 Webhook 中,这表示提及位于帖子的说明文字中,mention_type 为 VIDEO_MENTION。
- 为了试用而启用品牌话题标签。已启用的话题标签七天内无法移除,并且会计入账户的 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 监控
验证时间