TikTok Mentions API:アカウントに言及している投稿とコメントを見つける
TikTok の Mentions API は API for Business の一部で、過去 90 日以内の公開投稿のうち、キャプションで企業アカウントを @ で言及している上位 1,000 件を GET /business/mention/video/list/ で返します。コメントや返信で言及しているものの上位 1,000 件は /business/mention/comment/list/ で取得できます。どちらも biz.brand.insights スコープと、Advanced Access または Verified Business Account を持つアカウントが必要です。
easyCoexistence は TikTok の API for Business を通じて TikTok アカウントを接続します。
/business/mention/video/list/ が返す言及投稿は、すべて公開かつ過去 90 日以内のもので、1 リクエストあたり最大 100 件です。
言及が行われてから Mentions API で利用可能になるまでの、おおよその遅延。
ユーザーがキャプションまたはコメントで企業を言及してから、TikTok が示す Mentions Webhook の遅延。
UTC 0 時から 7 時までの更新の後に、アカウントごとに各 Mentions エンドポイントを呼び出す頻度として TikTok が推奨するもの。
アカウントに言及したコメントを返すために、biz.brand.insights に加えて /business/mention/comment/list/ が必要とするスコープ。
Mentions API にはどのエンドポイントがありますか?
読み取り用のエンドポイントは 6 つあり、いずれも https://business-api.tiktok.com/open_api/v1.3 への GET です。アクセストークンは Access-Token ヘッダーで渡し、アカウントの open_id を business_id として指定します。2 つは言及を一覧し、2 つは言及された投稿で何が語られているかを要約し、2 つは Webhook で通知された個別の言及を 1 件取得します。
どの投稿とコメントが言及に当たりますか?
公開投稿で、キャプションまたはコメントのテキスト内でアカウントのハンドルに @ を付けて言及しており、TikTok のその他のフィルターを通過したものです。次のルールが適用されます:
- 投稿は過去 90 日以内に公開されたものです。
- 投稿者が未成年または年齢不明ではないこと。欧州では 17 歳以下、米国やその他の地域では 12 歳以下が未成年とみなされます。
- ハンドルを言及している投稿またはコメントのうち、いいね数が多い上位 1,000 件に入っていること。
- 企業自身の投稿も、これらのルールを満たせば言及として数えられます。
- ハンドルの言及だけで他のテキストがないコメントは、順位が低くなります。
利用する前にアカウント側で必要なものは何ですか?
対象となるアカウント、適切な権限を持つ開発者アプリ、アクセストークンに付与されたスコープ、そしてオーナーがアプリを認可してから 1 日待つことが必要です:
- 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 になります。max_count を指定しない場合は 1 ページ 10 件で、最大 100 件まで指定できます。並び順は VIDEO_LIKES、COMMENT_CREATE_TIME、COMMENT_LIKES から選べます。TikTok の信頼と安全に関するポリシーにより、has_more が true のままでも、1 ページの件数が少なく返されることがあります。
言及に返信するにはどうしますか?
TikTok のコメント返信エンドポイントを使います。POST /business/comment/reply/create/ には business_id、コメント言及の item_id を指定した video_id、comment_id、最大 1,200 文字の text を渡します。返信は、そのコメントの下に、それを含む投稿上で公開表示されます。TikTok のリファレンスでは、そのために comment.list.manage スコープと同じアカウント要件が示されています。Mentions のリファレンスでは、返信はコメントの言及に対してのみ記載されています。
言及は Webhook で届きますか?
はい。Mentions の権限を持つアプリは、event_type を BRAND_MENTION にして POST /business/webhook/update/ を呼び出します。すると TikTok は、言及から最大で 2 から 3 時間以内に brand.mention.event を送信します。他の Webhook と同様に Tiktok-Signature で署名されます。content はシリアライズされた JSON 文字列で、次の情報を含みます:
type_of_eventは CREATE、EDIT、PRIVACY_CHANGEのいずれかで、PRIVACY_CHANGEは投稿のプライバシー設定の変更を示します。mention_typeは、コメントや返信の場合は COMMENT、キャプションの場合はVIDEO_MENTIONです。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。unique_identifierは、API をまたいで変わらないコメント投稿者の ID です。- 詳細は、イベントから 48 時間以内に /business/mention/video/get/ または /business/mention/comment/get/ で取得できます。
Mentions エンドポイントはどのくらいの頻度で呼び出すべきですか?
エンドポイントごと、アカウントごとに 1 日 1 回、UTC 7 時以降に呼び出すことを TikTok は勧めています。エンドポイントは開発者アプリのグローバルなレート制限を共有します。TikTok は前日分のデータを UTC 0 時から 7 時の間に更新するため、同日中にさらに取得を重ねる必要はないとしています。新しい言及が一覧エンドポイントに反映されるまでにはおおよそ 24 から 48 時間かかるため、Webhook の方が速いシグナルになります。
ブランドのハッシュタグはどのように機能しますか?
企業が選んだハッシュタグを使う投稿も、言及の対象に加えられます。POST /business/mention/hashtag/add/ では、1 リクエストあたり最大 10 個、アカウントあたり 50 個までハッシュタグを有効にできます。候補は /business/mention/hashtag/verify/list/ が提案する最大 100 件から選ぶか、ハンドル全体を含むものを使います。例えば @TikTok なら #drinktiktok です。一度有効にしたハッシュタグは 7 日間削除できず、有効にしてから 24 時間後に、その投稿が /business/mention/hashtag/video/list/ に反映されます。
easyCoexistence で TikTok の言及に対してできることは何ですか?
ご自身のコードにアカウントのトークンを渡してください。get_social_credentials は、business/ 以下の API for 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!" }よくある間違い
- Advanced Access を持たないアカウントに対して Mentions エンドポイントを呼び出すこと。TikTok が対象とするのは Advanced Access または Verified Business Account を持つアカウントで、/business/get/ の has_advanced_access がそれを示します。
- UTC 0 時を過ぎた直後に言及を取得すること。TikTok は前日分のデータを UTC 0 時から 7 時の間に更新するため、7 時以降の取得で 1 日分が揃います。
- comment_id が 0 のものをコメントとして読むこと。Webhook の言及では、これはその言及がキャプションにあることを意味し、mention_type は VIDEO_MENTION になります。
- 試しにブランドのハッシュタグを有効にすること。TikTok は有効にしたハッシュタグを 7 日間削除できないようにしており、アカウントの 50 個の上限にも含まれます。
Claude、ChatGPT、または自社のコードが、専用のツールでコメントを読み取って返信し、コメントイベントを届き次第受け取ります。また、TikTok が対象とする場合は Mentions エンドポイントを含め、その他の API for Business の呼び出し用のトークンを、get_social_credentials が自社のコードに渡します。接続 1 件あたり月額 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 では最大 2 から 3 時間です。
easyCoexistence は TikTok の言及が発生したときに通知できますか?
転送イベントとしては対応していません。easyCoexistence が転送するのは TikTok のコメントイベントで、言及イベントは転送しないためです。自社のコードは、対象となるアカウントであれば get_social_credentials のトークンを使って、必要なときに言及を読み取れます。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日