אזכורים ב-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 של TikTok: Claude, ChatGPT או הקוד שלכם קוראים את התגובות שלו ומשיבים עליהן בעזרת כלים ייעודיים ומקבלים את אירועי התגובות ברגע שהם מגיעים, ו-get_social_credentials נותן לקוד שלכם את האסימון לקריאות נוספות של API for Business, כולל נקודות הקצה של Mentions במקומות ש-TikTok פותחת לחשבון.
הפוסטים המאוזכרים המובילים שמחזירה נקודת הקצה /business/mention/video/list/, כולם ציבוריים ומ-90 הימים האחרונים, עד 100 בכל בקשה.
העיכוב המשוער מרגע האזכור ועד שהוא זמין דרך ה-Mentions API.
ההשהיה ש-TikTok מציין לוובהוק של האזכורים, לאחר שמשתמש מאזכר את העסק בכיתוב או בתגובה.
מומלץ לשאוב פעם ביום, אחרי 7 בבוקר UTC, לכל נקודת קצה ולכל חשבון, כפי שממליץ TikTok בעצמו.
ההיקף הנדרש לצד biz.brand.insights כדי להחזיר תגובות שמאזכרות את החשבון דרך נקודת הקצה /business/mention/comment/list/.
אילו נקודות קצה יש ל-Mentions API?
שש נקודות קריאה, כל אחת GET בכתובת https://business-api.tiktok.com/open_api/v1.3, עם אסימון הגישה (Access Token) של החשבון בכותרת 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 לאזכורי תגובות.
- מדריך ההתחלה של 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 מחזירים 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 עדיין מסמן שיש עוד.
איך עונים לאזכור?
דרך נקודת הקצה של TikTok לתשובה לתגובה. POST /business/comment/reply/create/ מקבל business_id, video_id שערכו הוא item_id של האזכור בתגובה, comment_id וטקסט של עד 1,200 תווים, והתשובה מופיעה בפומבי תחת התגובה, בכל פוסט שהיא נמצאת בו. התיעוד של TikTok מציין את ההיקף comment.list.manage ואותה דרישה לחשבון. התיעוד של Mentions מציין תשובה לאזכורי תגובות בלבד.
אפשר לקבל אזכורים בוובהוק?
כן. עם ההרשאה Mentions, אפליקציה שולחת קריאה לנקודת הקצה POST /business/webhook/update/ עם event_type BRAND_MENTION, ו-TikTok שולח אז את brand.mention.event תוך שעתיים או שלוש מהאזכור, חתום בכותרת Tiktok-Signature כמו שאר הוובהוקים שלו. השדה 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, מזהה מגיב שנשאר זהה בין כל הממשקים. - הפרטים מגיעים מנקודות הקצה /business/mention/video/get/ או /business/mention/comment/get/, תוך 48 שעות מהאירוע.
כמה פעמים כדאי לקרוא לנקודות הקצה של Mentions?
מומלץ לשאוב פעם ביום, אחרי 7 בבוקר UTC, לכל נקודת קצה ולכל חשבון, כפי שממליץ TikTok בעצמו. נקודות הקצה חולקות את מגבלות הקצב הגלובליות של אפליקציית המפתחים, אבל TikTok מרענן את נתוני היום הקודם בין חצות ל-7 בבוקר 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 מרענן את נתוני היום הקודם בין חצות ל-7 בבוקר UTC, כך ששאיבה אחרי 7 בבוקר רואה את כל היום.
- לקרוא את השדה comment_id עם הערך 0 כתגובה. בוובהוק של אזכור, הערך הזה מציין שהאזכור נמצא בכיתוב הפוסט, כשהשדה mention_type הוא VIDEO_MENTION, ולא בתגובה.
- הפעלת האשטאג מותג כדי לנסות אותו. TikTok שומר האשטאג שהופעל במשך שבעה ימים לפני שאפשר להסיר אותו, והוא נספר במכסה של 50 של החשבון.
מ-US$ 9 ועד US$ 0.75 לחיבור בחודש, והמחיר יורד ככל שמוסיפים חיבורים, עם תקופת ניסיון של 3 ימים בחינם.
שאלות נפוצות
האם ה-TikTok API יכול למצוא סרטונים שמאזכרים את החשבון שלי?
כן, אלה שמתייגים את שם המשתמש בכיתוב. נקודת הקצה /business/mention/video/list/ מחזירה עד 1,000 פוסטים ציבוריים מ-90 הימים האחרונים, והשדה creator_handle_name מציין את שם היוצר בכל אחד מהם.
האם פוסטים פרטיים של TikTok נספרים כאזכורים?
לא. ה-Mentions API סופר רק פוסטים ציבוריים מ-90 הימים האחרונים, ומשאיר בחוץ מחברים שהם קטינים או בני גיל לא ידוע: גיל 17 ומטה באירופה, וגיל 12 ומטה בארה"ב ובאזורים אחרים.
כמה זמן לוקח לאזכור ב-TikTok להופיע?
בערך 24 עד 48 שעות דרך נקודות הקצה של הרשימה, ועד שעתיים או שלוש דרך הוובהוק לאזכורים.
האם easyCoexistence יכול להתריע לי כשחשבון ה-TikTok שלי מאוזכר?
לא כאירוע מועבר, כי הוא מעביר את אירועי התגובות של TikTok ולא את אירועי האזכור. הקוד שלכם יכול לקרוא אזכורים לפי בקשה, עם האסימון מ-get_social_credentials, כשהחשבון עומד בתנאים.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-