Wzmianki na TikToku przez API: wyszukiwanie postów i komentarzy ze wzmianką o koncie
Mentions API TikToka, część API for Business, zwraca 1 000 najpopularniejszych publicznych postów z ostatnich 90 dni, w których w opisie oznaczono przez @ konto firmy, za pośrednictwem GET /business/mention/video/list/, oraz 1 000 najpopularniejszych komentarzy lub odpowiedzi, które o nim wspominają, za pośrednictwem /business/mention/comment/list/. Oba wymagają zakresu biz.brand.insights oraz konta z Advanced Access lub Verified Business Account.
easyCoexistence łączy konto TikToka przez API for Business TikToka: Claude, ChatGPT lub Twój własny kod odczytują jego komentarze i odpowiadają na nie dedykowanymi narzędziami i odbierają zdarzenia komentarzy w miarę ich nadejścia, a get_social_credentials daje Twojemu własnemu kodowi token do innych wywołań API for Business, w tym endpointów Mentions, gdy TikTok udostępnia je kontu.
Maksymalna liczba wzmiankowanych postów, które zwraca /business/mention/video/list/: wszystkie publiczne, z ostatnich 90 dni, do 100 w jednym żądaniu.
Przybliżone opóźnienie między dokonaniem wzmianki a jej dostępnością w Mentions API.
Czas, jaki TikTok podaje dla webhooka wzmianek od chwili, gdy użytkownik wspomni firmę w opisie lub komentarzu.
Jak często TikTok zaleca wywoływanie każdego endpointu Mentions dla konta, po odświeżeniu danych między 0 a 7 rano UTC.
Zakres, którego /business/mention/comment/list/ wymaga oprócz biz.brand.insights, aby zwrócić komentarze ze wzmianką o koncie.
Jakie endpointy ma Mentions API?
Sześć endpointów do odczytu, każdy jako GET pod adresem https://business-api.tiktok.com/open_api/v1.3, z tokenem dostępu konta w nagłówku Access-Token i jego open_id jako business_id. Dwa zwracają listy wzmianek, dwa podsumowują, co mówią wzmiankowane posty, a dwa pobierają pojedynczą wzmiankę, o której poinformował webhook:
Które posty i komentarze liczą się jako wzmianki?
Te, które oznaczają nazwę konta znakiem @, w opisie posta lub w tekście komentarza, w publicznym poście, i które spełniają pozostałe filtry TikToka:
- Post został opublikowany w ciągu ostatnich 90 dni.
- Autor nie jest niepełnoletni ani nie ma nieznanego wieku: w Europie za niepełnoletnich uznaje się osoby w wieku 17 lat lub młodszym, w USA i innych regionach w wieku 12 lat lub młodszym.
- Znajduje się wśród 1 000 najbardziej lubianych postów lub komentarzy wspominających nazwę konta.
- Posty samej firmy, spełniające te zasady, również się liczą.
- Komentarze składające się wyłącznie z samej wzmianki, bez innego tekstu, są niżej w rankingu.
Czego konto potrzebuje, zanim będzie mogło z nich korzystać?
Kwalifikującego się konta, aplikacji z odpowiednim uprawnieniem, zakresów na tokenie i doby oczekiwania po autoryzacji aplikacji przez właściciela:
- Advanced Access lub Verified Business Account;
has_advanced_accessw /business/get/ pokazuje, które konta się kwalifikują. - Uprawnienie Mentions w aplikacji deweloperskiej, wymienione jako Mentions, Content dla postów i Mentions, Comment dla komentarzy.
- biz.brand.insights na tokenie dostępu, a dla wzmianek w komentarzach także comment.list.
- 24 godziny po autoryzacji, zanim nastąpi pierwsze pobranie, zgodnie z zaleceniem przewodnika TikToka dla początkujących.
Jak pobrać listę postów ze wzmianką o koncie?
Za pomocą GET /business/mention/video/list/. fields wybiera dane: domyślnie item_id i caption, a na żądanie także create_time, video_link, likes, comments, shares, thumbnail_url, views, reach i creator_handle_name. sort_field przyjmuje CREATE_TIME, LIKES, COMMENTS lub SHARES wraz z sort_type ASC lub DESC, number_of_days zawęża 90 dni, regions ogranicza twórców do wybranych regionów, a cursor z has_more stronicuje wyniki. views i reach mają wartość null poniżej 1 000, a linki do miniatur są ważne przez 48 godzin:
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
}
}Jak pobrać listę komentarzy ze wzmianką o koncie?
Za pomocą GET /business/mention/comment/list/, którego token wymaga także comment.list. Domyślnie zwraca comment_id i comment_text; item_id, video_link, caption, video_likes, thumbnail_url, commenter_display_name, comment_type, comment_create_time i comment_likes dostępne są na żądanie, a comment_type przyjmuje COMMENT lub REPLY. Strona zawiera 10 pozycji, chyba że max_count prosi o do 100, z sortowaniem według VIDEO_LIKES, COMMENT_CREATE_TIME lub COMMENT_LIKES. Ze względu na zasady TikToka dotyczące zaufania i bezpieczeństwa strona może zwrócić mniej wyników, mimo że has_more nadal ma wartość true.
Jak odpowiedzieć na wzmiankę?
Przez endpoint TikToka do odpowiadania na komentarze. POST /business/comment/reply/create/ przyjmuje business_id, video_id ustawione na item_id z wzmianki w komentarzu, comment_id oraz pole text do 1 200 znaków, a odpowiedź pojawia się publicznie pod tym komentarzem, pod postem, który go zawiera. Dokumentacja TikToka wskazuje zakres comment.list.manage oraz ten sam wymóg dotyczący konta. W jej opisie Mentions odpowiedź dotyczy wyłącznie wzmianek w komentarzach.
Czy wzmianki mogą przychodzić przez webhook?
Tak. Z uprawnieniem Mentions aplikacja wywołuje POST /business/webhook/update/ z event_type BRAND_MENTION, a TikTok wysyła następnie brand.mention.event w ciągu maksymalnie dwóch lub trzech godzin od wzmianki, podpisane w Tiktok-Signature, podobnie jak inne webhooki. content to zserializowany ciąg JSON, który zawiera:
type_of_event: CREATE, EDIT lubPRIVACY_CHANGEdla zmiany ustawień prywatności posta.mention_type: COMMENT dla komentarza lub odpowiedzi,VIDEO_MENTIONdla opisu, gdziecomment_idma wartość 0.video_id,video_create_time,share_urlivideo_caption, które opisują post.open_id_of_mentioned_user,unique_name_of_mentioned_userorazunique_identifier, czyli identyfikator autora komentarza, który pozostaje stały we wszystkich API.- Szczegóły pobiera się z /business/mention/video/get/ lub /business/mention/comment/get/, w ciągu 48 godzin od zdarzenia.
Jak często wywoływać endpointy Mentions?
Raz dziennie dla każdego endpointu i konta, po godzinie 7 UTC, zaleca TikTok. Endpointy współdzielą globalne limity żądań aplikacji deweloperskiej, ale TikTok odświeża dane z poprzedniego dnia między północą a 7 UTC, a kolejne pobrania w tym samym dniu uznaje za zbędne. Nowa wzmianka potrzebuje też około 24 do 48 godzin, by pojawić się w endpointach zwracających listy, dlatego webhook jest szybszym sygnałem.
Jak działają hashtagi marki?
Rozszerzają wzmianki na posty używające hashtagów wybranych przez firmę. POST /business/mention/hashtag/add/ włącza do 10 hashtagów na żądanie i 50 na konto, wybranych spośród do 100 zasugerowanych przez /business/mention/hashtag/verify/list/ lub zawierających pełną nazwę konta, jak #drinktiktok dla @TikTok. Włączonego hashtagu nie da się usunąć przez siedem dni, a jego posty trafiają do /business/mention/hashtag/video/list/ 24 godziny po włączeniu.
Co easyCoexistence może zrobić z wzmiankami na TikToku?
Przekaż własnemu kodowi token konta: get_social_credentials zwraca token i business_id do ścieżek API for Business pod business/, w tym business/mention/. TikTok odpowiada, gdy konto i aplikacja spełniają wymagania opisane wyżej. Webhooki wzmianek pozostają poza tym: easyCoexistence subskrybuje aplikację tylko do zdarzeń komentarzy, zachowuje ścieżki business/webhook/ dla siebie, więc zdarzenia BRAND_MENTION nie są przekazywane. Komentarze do postów konta, także te ze wzmiankami, nadal docierają jako zdarzenia comment.update, które set_social_webhook_destination przekazuje dalej:
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!" }Typowe błędy
- Wywoływanie endpointów Mentions dla konta bez Advanced Access. TikTok udostępnia je kontom z Advanced Access lub Verified Business Account, co pokazuje has_advanced_access w /business/get/.
- Pobieranie wzmianek tuż po północy UTC. TikTok odświeża dane z poprzedniego dnia między północą a 7 UTC, więc pobranie po 7 UTC obejmuje cały dzień.
- Odczytanie comment_id równego 0 jako komentarza. W webhooku wzmianki oznacza to, że wzmianka jest w opisie posta, z mention_type VIDEO_MENTION.
- Włączenie hashtagu marki tylko na próbę. TikTok przechowuje włączony hashtag przez siedem dni, zanim da się go usunąć, a wlicza się on do limitu 50 na konto.
Od US$ 9 do US$ 0.75 za połączenie miesięcznie, mniej przy każdym kolejnym połączeniu, z pierwszymi 3 dniami bezpłatnie.
Najczęściej zadawane pytania
Czy TikTok API może znaleźć filmy ze wzmianką o moim koncie?
Tak, te, które oznaczają jego nazwę w opisie. /business/mention/video/list/ zwraca do 1 000 publicznych postów z ostatnich 90 dni, z creator_handle_name wskazującym każdego twórcę.
Czy prywatne posty TikToka liczą się jako wzmianki?
Nie. Mentions API uwzględnia wyłącznie publiczne posty z ostatnich 90 dni i pomija autorów niepełnoletnich lub nieznanego wieku: w wieku 17 lat lub młodszym w Europie, a 12 lat lub młodszym w USA i innych regionach.
Jak długo wzmianka na TikToku potrzebuje, by się pojawić?
Około 24 do 48 godzin w endpointach zwracających listy, a do dwóch lub trzech godzin przez webhook wzmianek.
Czy easyCoexistence może mnie powiadomić o wzmiance na moim koncie TikToka?
Nie jako przekazywane zdarzenie, bo przekazuje zdarzenia komentarzy TikToka, a nie zdarzenia wzmianek. Twój własny kod może odczytać wzmianki na żądanie, z tokenem z get_social_credentials, o ile konto się kwalifikuje.
Czytaj dalej
Połącz pierwszy kanał w dwie minuty.
Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.
- 3 dni za darmo
- Rezygnacja w każdej chwili
- Tylko oficjalne API
- Monitorowanie 24/7
Zweryfikowano w