تسجيل الدخولابدأ الفترة التجريبية المجانية
easyCoexistence واجهات API الرسمية

الإشارات على 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 للحساب.

1,000

أكثر المنشورات إشارةً التي يعيدها /business/mention/video/list/، وكلها عامة ومن آخر 90 يومًا، بحد أقصى 100 لكل طلب.

24 to 48 hours

التأخير التقريبي بين وقوع الإشارة وتوفرها عبر Mentions API.

2 to 3 hours

زمن الاستجابة الذي تعلنه TikTok لـ webhook الإشارات بعد أن يشير مستخدم إلى النشاط التجاري في وصف أو تعليق.

Once a day

معدل الاستدعاء الذي توصي به TikTok لكل نقطة نهاية (endpoint) للإشارات لكل حساب، بعد التحديث بين الساعة 0 و7 صباحًا بتوقيت UTC.

comment.list

النطاق الذي تحتاجه /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:

/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 أو حساب نشاط تجاري موثق؛ يُظهر 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 صحيحًا.

كيف ترد على إشارة؟

عبر 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 إلى الوجهة:

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

الأخطاء الشائعة

  • استدعاء 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 للحساب.
إنجاز ذلك باستخدام EasyCoexistence

من 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، حيث يكون الحساب مؤهلًا.

تابع القراءة

ردود تعليقات TikTok والإشراف عليها عبر واجهة برمجة التطبيقات (API)كيف تقرأ واجهة TikTok للأعمال التعليقات وترد عليها وتخفيها وتحذفها، وكيف ترد القواعد والأتمتة على التعليقات الجديدة تلقائياً.التحقق من خطاف الويب (webhook) في TikTok: ترويسة التوقيع وطريقة فحصهاالتحقق من webhook في TikTok API for Business: ترويسة Tiktok-Signature وHMAC-SHA256 مع مثال Node.js.حدود معدل TikTok API: الطلبات لكل حساب وتطبيق ونقطة نهايةحدود معدل TikTok API: 40 طلباً في الدقيقة لكل حساب ونقطة نهاية، و600 أو 1,000 في الدقيقة لكل تطبيق في Accounts API، والمستويات الأربعة للتطبيق.نطاقات TikTok API for Business: ما يفتحه كل إذنالأذونات التي تعمل بها TikTok Accounts API بأسمائها الرسمية: ما تفتحه كل منها، ونطاقات الرمز لكل حقل، وكيفية التحقق من الرمز.ردود الذكاء الاصطناعي على تعليقات TikTokذكاء اصطناعي خاص بالنشاط التجاري يرد علنًا على تعليقات TikTok: أتمتة للتعليقات الجديدة، وردود حتى 150 حرفًا، وقواعد للكلمات المفتاحية.أحداث webhook لتعليقات TikTokكيف يُبلغ حدث comment.update في TikTok عن التعليقات والردود، وما يحمله كل حدث، ووصوله موقّعًا إلى نقطة النهاية (endpoint) الخاصة بك.

اربط قناتك الأولى في دقيقتين.

لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.

  • 3 أيام مجانًا
  • إلغاء في أي وقت
  • واجهات API الرسمية فقط
  • مراقبة على مدار الساعة 24/7

تم التحقق في