Упоминания в TikTok через API: поиск постов и комментариев с упоминанием аккаунта
Mentions API TikTok, часть API for Business, возвращает до 1 000 самых популярных публичных постов за последние 90 дней, в подписи которых есть @упоминание бизнес-аккаунта, через GET /business/mention/video/list/, и до 1 000 комментариев или ответов с упоминанием через /business/mention/comment/list/. Для обоих нужна область доступа biz.brand.insights и аккаунт с Advanced Access или Verified Business Account.
easyCoexistence подключает аккаунт TikTok через API for Business: Claude, ChatGPT или ваш собственный код читают его комментарии и отвечают на них через специальные инструменты и получают события комментариев по мере поступления, а get_social_credentials даёт вашему собственному коду токен для других вызовов API for Business, включая эндпоинты Mentions там, где TikTok открывает их аккаунту.
Максимальное число постов, которое возвращает /business/mention/video/list/: все публичные, за последние 90 дней, до 100 за один запрос.
Примерная задержка между упоминанием и его появлением в Mentions API.
Задержка, которую TikTok указывает для вебхука Mentions после упоминания бизнеса в подписи или комментарии.
Как часто TikTok рекомендует вызывать каждый эндпоинт Mentions для аккаунта после обновления данных с 0:00 до 7:00 UTC.
Область доступа /business/mention/comment/list/ требует помимо biz.brand.insights, чтобы вернуть комментарии с упоминанием аккаунта.
Какие эндпоинты есть у Mentions API?
Шесть эндпоинтов для чтения, каждый из них это GET-запрос на https://business-api.tiktok.com/open_api/v1.3 с токеном доступа аккаунта в заголовке Access-Token и его open_id в качестве business_id. Два перечисляют упоминания, два суммируют, что говорят упомянутые посты, и два получают одно упоминание, о котором сообщил вебхук:
Какие посты и комментарии считаются упоминаниями?
Те, что отмечают никнейм аккаунта через @ в подписи поста или в тексте комментария, у публичного поста, и которые проходят остальные фильтры TikTok:
- Пост опубликован за последние 90 дней.
- Автор не несовершеннолетний и не неизвестного возраста: в Европе это 17 лет и младше, в США и других регионах 12 лет и младше.
- Входит в 1 000 постов или комментариев с наибольшим числом лайков, в которых упомянут никнейм.
- Посты самого бизнеса, которые соответствуют этим правилам, тоже считаются.
- Комментарии, состоящие только из упоминания без другого текста, занимают в выдаче более низкое место.
Что нужно аккаунту, чтобы их использовать?
Подходящий аккаунт, приложение с нужным разрешением, области доступа в токене и сутки ожидания после того, как владелец авторизует приложение:
- Advanced Access или Verified Business Account;
has_advanced_accessв /business/get/ показывает, какие аккаунты подходят. - Разрешение 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 листает результаты. views и reach показывают null при значении ниже 1 000, а ссылки на миниатюры действуют 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, video_id, равный item_id из упоминания в комментарии, comment_id и text до 1 200 символов. Ответ публично появляется под этим комментарием, на любом посте, где он есть. В справке TikTok указана область comment.list.manage и то же требование к аккаунту. В справке по Mentions ответ указан только для упоминаний в комментариях.
Могут ли упоминания приходить через вебхук?
Да. С разрешением Mentions приложение вызывает POST /business/webhook/update/ с event_type BRAND_MENTION, и TikTok затем отправляет brand.mention.event в течение двух-трёх часов после упоминания. Событие подписано в заголовке Tiktok-Signature, как и другие вебхуки TikTok. 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.- Подробности берутся из /business/mention/video/get/ или /business/mention/comment/get/ в течение 48 часов после события.
Как часто вызывать эндпоинты Mentions?
Рекомендация TikTok: раз в сутки на каждый эндпоинт и аккаунт, после 7:00 UTC. Эндпоинты делят глобальные ограничения частоты запросов приложения разработчика, но TikTok обновляет данные за предыдущий день между 0:00 и 7:00 UTC, а дополнительные запросы в тот же день не нужны. Новое упоминание появляется в списочных эндпоинтах примерно через 24–48 часов, поэтому вебхук быстрее.
Как работают брендовые хештеги?
Они расширяют упоминания до постов с хештегами, которые выбрал бизнес. POST /business/mention/hashtag/add/ включает до 10 хештегов за запрос и до 50 на аккаунт, взятых из до 100 предложенных в /business/mention/hashtag/verify/list/, либо содержащих полный никнейм, например #drinktiktok для @TikTok. Включённый хештег нельзя удалить в течение семи дней, а его посты попадают в /business/mention/hashtag/video/list/ через 24 часа после включения.
Что easyCoexistence может делать с упоминаниями TikTok?
Передайте своему коду токен аккаунта: get_social_credentials возвращает токен и business_id для путей API for Business под business/, включая business/mention/. TikTok отвечает, если аккаунт и приложение соответствуют требованиям выше. Вебхуки упоминаний в этот набор не входят: 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 для аккаунта без Advanced Access. TikTok отдаёт их аккаунтам с Advanced Access или Verified Business Account, что показывает has_advanced_access в /business/get/.
- Запрос упоминаний сразу после полуночи UTC. TikTok обновляет данные за предыдущий день между 0:00 и 7:00 UTC, поэтому запрос после 7:00 видит весь день.
- Принимать comment_id, равный 0, за комментарий. В вебхуке упоминания это значит, что упоминание находится в подписи поста, с mention_type VIDEO_MENTION.
- Включить брендовый хештег для пробы. TikTok хранит включённый хештег семь дней, прежде чем его можно удалить, и он засчитывается в лимит аккаунта в 50.
От US$ 9 до US$ 0,75 за подключение в месяц, цена снижается по мере добавления подключений, с бесплатным пробным периодом в 3 дня.
Часто задаваемые вопросы
Может ли API TikTok найти видео с упоминанием моего аккаунта?
Да, те, где в подписи есть @упоминание его никнейма. /business/mention/video/list/ возвращает до 1 000 публичных постов за последние 90 дней, а creator_handle_name называет каждого автора.
Считаются ли упоминаниями приватные посты TikTok?
Нет. Mentions API учитывает только публичные посты за последние 90 дней и исключает авторов несовершеннолетних или неизвестного возраста: 17 лет и младше в Европе, 12 лет и младше в США и других регионах.
Сколько времени занимает появление упоминания в TikTok?
Примерно 24–48 часов через списочные эндпоинты и до двух-трёх часов через вебхук Mentions.
Может ли easyCoexistence уведомлять меня, когда упоминают мой аккаунт TikTok?
Не в виде пересылаемого события, так как он пересылает события комментариев TikTok, а не события упоминаний. Ваш код может читать упоминания по запросу, с токеном из get_social_credentials, если аккаунт подходит.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на