الإشارات على TikTok عبر واجهة برمجة التطبيقات (API): العثور على المنشورات والتعليقات التي تشير إلى حساب
تتيح واجهة Mentions من TikTok، وهي جزء من API for Business، استرجاع أعلى 1,000 منشور عام من آخر 90 يومًا يشير إلى حساب نشاط تجاري في وصفه، عبر GET /business/mention/video/list/، وأعلى 1,000 تعليق أو رد يشير إليه، عبر /business/mention/comment/list/. ويتطلب الاستدعاءان النطاق biz.brand.insights وحسابًا بصلاحية Advanced Access أو حساب نشاط تجاري موثق.
يربط easyCoexistence حساب TikTok عبر API for Business لدى TikTok: يقرأ Claude أو ChatGPT أو الشيفرة البرمجية الخاصة بك تعليقاته ويردّ عليها بأدوات مخصصة، ويستقبل أحداث التعليقات فور وصولها، ويمنح get_social_credentials شيفرتك البرمجية token لاستدعاءات API for Business الأخرى، بما فيها endpoints الإشارات حيث تتيحها TikTok للحساب.
أكثر المنشورات إشارةً التي يعيدها /business/mention/video/list/، وكلها عامة ومن آخر 90 يومًا، بحد أقصى 100 لكل طلب.
التأخير التقريبي بين وقوع الإشارة وتوفرها عبر Mentions API.
زمن الاستجابة الذي تعلنه TikTok لـ webhook الإشارات بعد أن يشير مستخدم إلى النشاط التجاري في وصف أو تعليق.
معدل الاستدعاء الذي توصي به TikTok لكل نقطة نهاية (endpoint) للإشارات لكل حساب، بعد التحديث بين الساعة 0 و7 صباحًا بتوقيت UTC.
النطاق الذي تحتاجه /business/mention/comment/list/ إلى جانب biz.brand.insights لإرجاع التعليقات التي تشير إلى الحساب.
ما هي endpoints الخاصة بواجهة Mentions؟
ست endpoints للقراءة، كل منها طلب GET على https://business-api.tiktok.com/open_api/v1.3، مع رمز الوصول (token) الخاص بالحساب في الترويسة Access-Token، وopen_id الخاص بالحساب بوصفه business_id. اثنتان تسردان الإشارات، واثنتان تلخصان ما تقوله المنشورات المشار إليها، واثنتان تجلبان إشارة واحدة أعلن عنها webhook:
أي المنشورات والتعليقات تُحسب إشارات؟
تلك التي تضع اسم الحساب بعد الرمز @ في وصف المنشور أو نص التعليق، على منشور عام، وتجتاز بقية مرشحات TikTok:
- نُشر المنشور خلال آخر 90 يومًا.
- مؤلفه ليس قاصرًا ولا مجهول العمر: 17 سنة أو أقل تُعد قاصرًا في أوروبا، و12 سنة أو أقل في الولايات المتحدة ومناطق أخرى.
- يأتي ضمن أعلى 1,000 منشور أو تعليق من حيث الإعجابات بين ما يشير إلى الاسم.
- منشورات النشاط التجاري نفسه التي تستوفي هذه القواعد تُحسب أيضًا.
- التعليقات المكوّنة من الإشارة وحدها دون أي نص آخر تُرتّب في مرتبة أدنى.
ما الذي يحتاجه الحساب قبل استخدامها؟
حساب مؤهل، وتطبيق يملك الإذن المناسب، والنطاقات على الرمز، ويوم انتظار بعد أن يفوّض المالك التطبيق:
- Advanced Access أو حساب نشاط تجاري موثق؛ يُظهر
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 صحيحًا.
كيف ترد على إشارة؟
عبر endpoint الرد على التعليق في TikTok. يأخذ POST /business/comment/reply/create/ القيم business_id، وvideo_id مساويًا لـ item_id من إشارة التعليق، وcomment_id، وtext بطول يصل إلى 1,200 حرف، فيظهر الرد علنًا تحت ذلك التعليق، على أي منشور يحمله. ويذكر مرجع TikTok النطاق comment.list.manage ونفس متطلبات الحساب. ولا يدرج مرجع Mentions الرد إلا لإشارات التعليقات.
هل يمكن أن تصل الإشارات عبر webhook؟
نعم. مع إذن Mentions، يستدعي التطبيق POST /business/webhook/update/ بالقيمة event_type وBRAND_MENTION، ثم ترسل TikTok الحدث brand.mention.event خلال ساعتين إلى ثلاث من الإشارة، موقّعًا في Tiktok-Signature كبقية webhooks لديها. و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 ساعة من الحدث.
كم مرة ينبغي استدعاء endpoints الإشارات؟
مرة واحدة يوميًا لكل endpoint وحساب، بعد الساعة 7 صباحًا بتوقيت UTC، هذه نصيحة TikTok. تتشارك endpoints حدود المعدل العامة لتطبيق المطوّر، لكن TikTok تحدّث بيانات اليوم السابق بين منتصف الليل و7 صباحًا بتوقيت UTC، وتعدّ السحوبات الإضافية في اليوم نفسه غير ضرورية. كما تحتاج الإشارة الجديدة إلى نحو 24 إلى 48 ساعة لتصل إلى endpoints القوائم، ولذلك يكون webhook هو الإشارة الأسرع.
كيف تعمل هاشتاغات العلامة التجارية؟
توسّع الإشارات لتشمل المنشورات التي تستخدم الهاشتاغات التي يختارها النشاط التجاري. يفعّل 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 عندما يستوفي الحساب والتطبيق المتطلبات أعلاه. تبقى webhooks الإشارات خارج ذلك: إذ يشترك 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!" }الأخطاء الشائعة
- استدعاء endpoints الإشارات لحساب لا يملك Advanced Access. تقدّمها TikTok للحسابات التي تملك Advanced Access أو حساب نشاط تجاري موثق، وهذا ما يُظهره has_advanced_access في /business/get/.
- سحب الإشارات مباشرة بعد منتصف الليل بتوقيت UTC. تحدّث TikTok بيانات اليوم السابق بين منتصف الليل و7 صباحًا بتوقيت UTC، فالسحب بعد الساعة 7 صباحًا يرى اليوم كاملًا.
- قراءة comment_id بقيمة 0 على أنه تعليق. في webhook الإشارة، تعني هذه القيمة أن الإشارة في وصف المنشور، ويكون 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 المنشورات العامة من آخر 90 يومًا فقط، وتستبعد المؤلفين القاصرين أو مجهولي العمر: 17 سنة أو أقل في أوروبا، و12 سنة أو أقل في الولايات المتحدة ومناطق أخرى.
كم يستغرق ظهور إشارة TikTok؟
نحو 24 إلى 48 ساعة عبر endpoints القوائم، وحتى ساعتين أو ثلاث عبر webhook الإشارات.
هل يستطيع easyCoexistence تنبيهي عند الإشارة إلى حساب TikTok؟
ليس كحدث مُمرَّر، لأنه يمرر أحداث التعليقات من TikTok لا أحداث الإشارات. يمكن لشيفرتك قراءة الإشارات عند الطلب، بواسطة token من get_social_credentials، حيث يكون الحساب مؤهلًا.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في