ВойтиНачать бесплатный пробный период
easyCoexistence Официальные API

Упоминания в 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 открывает их аккаунту.

1,000

Максимальное число постов, которое возвращает /business/mention/video/list/: все публичные, за последние 90 дней, до 100 за один запрос.

24 to 48 hours

Примерная задержка между упоминанием и его появлением в Mentions API.

2 to 3 hours

Задержка, которую TikTok указывает для вебхука Mentions после упоминания бизнеса в подписи или комментарии.

Once a day

Как часто TikTok рекомендует вызывать каждый эндпоинт Mentions для аккаунта после обновления данных с 0:00 до 7:00 UTC.

comment.list

Область доступа /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. Два перечисляют упоминания, два суммируют, что говорят упомянутые посты, и два получают одно упоминание, о котором сообщил вебхук:

/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; 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 часов:

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, 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:

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!" }

Распространённые ошибки

  • Вызов эндпоинтов 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.
Настройка с EasyCoexistence

От 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, если аккаунт подходит.

Читайте дальше

Ответы на комментарии TikTok и модерация через APIКак API TikTok для бизнеса читает и скрывает комментарии, отвечает на них и удаляет свои, а правила по ключевым словам отвечают на новые сами.Проверка вебхуков TikTok: заголовок подписи и как его проверитьПроверка вебхука TikTok API for Business: заголовок Tiktok-Signature, HMAC-SHA256 от t, точки и тела запроса с секретом приложения, на Node.js.Лимиты TikTok API: запросы на аккаунт, приложение и эндпоинтЛимиты TikTok API: 40 запросов в минуту на аккаунт и эндпоинт, 600 или 1 000 в минуту на приложение в Accounts API и четыре уровня приложения.Scope в TikTok API for Business: что открывает каждое разрешениеРазрешения API TikTok Accounts по именам TikTok: что открывает каждое, scope токена для полей и как проверить токен.AI-ответы на комментарии в TikTokСобственный AI бизнеса отвечает на комментарии TikTok публично: автоматизации на новые комментарии, ответы до 150 символов и правила по ключевым словам.События вебхука комментариев TikTokКак вебхук comment.update от TikTok сообщает о комментариях и ответах, что несёт каждое событие и как оно приходит на ваш эндпоинт с подписью.

Подключите первый канал за две минуты.

Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.

  • 3 дня бесплатно
  • Отмена в любой момент
  • Только официальные API
  • Мониторинг 24/7

Проверено по состоянию на