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

إعداد webhooks الخاصة بـ TikTok API for Business

تُرسل TikTok API for Business خطافات الويب (webhooks) إلى عنوان استدعاء URL واحد لكل تطبيق مطوّر ولكل نوع حدث، ويُضبط ذلك بطلب POST إلى /business/webhook/update/ باستخدام app_id وsecret الخاص بالتطبيق. يشترك event_type بقيمة VIDEO في أحداث النشر الأربعة للمنشورات، ويشترك COMMENT في comment.update. يصل كل إرسال كطلب HTTPS بطريقة POST موقّع في ترويسة Tiktok-Signature، ويُحسب بخوارزمية HMAC-SHA256 بمفتاح هو سر التطبيق.

يحتفظ easyCoexistence باشتراك webhook التعليقات الخاص بـ TikTok لتطبيقه، ويتحقق من توقيع TikTok، ويمرر كل حدث تعليق لحسابك إلى نقطة النهاية HTTPS الخاصة بك، موقّعا بسر خاص به.

72 hours

المدة التي تعيد فيها TikTok محاولة الإرسال الذي لم يتلقَّ ردا برمز HTTP 200، مع تأخير متصاعد أُسّيًا، قبل حذفه.

100

أكبر عدد من معرّفات المنشورات يمكن أن يحددها item_list الواحدة لقصر أحداث comment.update على منشورات بعينها.

v1.0

القيمة الحالية لترويسة webhook-schema-version التي ترسلها TikTok مع كل إرسال.

No permission

ما تذكره مرجعية TikTok لنقاط النهاية (endpoints) الخاصة بإعداد webhooks، وهي تتحقق بمعرّف التطبيق وسره.

HMAC-SHA256

الخوارزمية وراء Tiktok-Signature: الطابع الزمني ثم نقطة ثم نص الطلب، موقّعة بسر التطبيق ومرمّزة بالنظام السداسي عشري (hex).

Business Comment

الصلاحية التي يحتاجها التطبيق ضمن TikTok Accounts لأحداث comment.update، أما أحداث النشر فتحتاج Business Content.

ما أحداث webhooks التي يمكن لتطبيق حساب TikTok استقبالها؟

فئتان، يُشترك في كل منهما بنوع حدث مستقل event_type. تشمل VIDEO المنشورات المنشورة عبر /business/video/publish/ أو /business/photo/publish/، وتشمل COMMENT التعليقات على منشورات الصور في الحساب ومنشورات الفيديو العامة، سواء نُشرت عبر الواجهة أو داخل تطبيق TikTok:

post.publish.failedVIDEO: the post broke a format rule or its URL was blocked before the download finished
post.publish.completeVIDEO: the file met the format rules and downloaded without problems
post.publish.publicly_availableVIDEO: moderation passed and the post is public, with its post_id
post.publish.no_longer_publicly_availableVIDEO: later moderation, or the owner, took the post out of public view
comment.updateCOMMENT: a comment or reply created, deleted, hidden, set to friends only or made public

ما الذي يحتاجه التطبيق قبل الاشتراك؟

الوصول إلى API for Business، وتطبيق مطوّر، وحسابات TikTok فوّضت التطبيق. يضيف دليل الاشتراك في TikTok صلاحية لكل فئة، ويحتاج حدث التعليق نطاقا يمنحه المالك:

  • أحداث النشر: صلاحية TikTok Accounts وBusiness Content على التطبيق.
  • أحداث التعليقات: صلاحية TikTok Accounts وBusiness Comment على التطبيق.
  • comment.update: النطاق comment.list، يمنحه المالك ويبقى ساريا.
  • عنوان URL للاستدعاء يعمل عبر HTTPS ويرد برمز HTTP 200 فورا.

كيف تشترك؟

بطلب POST إلى /business/webhook/update/، مرة لكل event_type. يأخذ الجسم app_id وsecret وevent_type، أي VIDEO أو COMMENT، وcallback_url؛ وفي حالة COMMENT يمكنه أيضا أخذ item_list. تعيد الاستجابة app_id وevent_type وcallback_url، وكذلك item_list عند ضبطها. وإعادة الاستدعاء لنفس event_type تستبدل عنوان الاستدعاء.

Subscribe the app to comment events
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/' \
  -H 'Content-Type: application/json' \
  -d '{
    "app_id": "<APP_ID>",
    "secret": "<APP_SECRET>",
    "event_type": "COMMENT",
    "callback_url": "https://hooks.example.com/tiktok/"
  }'

{
  "code": 0,
  "message": "OK",
  "request_id": "<REQUEST_ID>",
  "data": { "app_id": "<APP_ID>", "callback_url": "https://hooks.example.com/tiktok/", "event_type": "COMMENT" }
}

كيف تُضيّق item_list أحداث التعليقات؟

تحصر comment.update في المنشورات التي تسمّيها، حتى 100 معرّف من /business/video/list/، ويحدد أول استدعاء قائمة الوضع للتطبيق من تلك اللحظة:

  • أول استدعاء COMMENT مع item_list: تصل الأحداث للمنشورات المدرجة فقط.
  • الاستدعاءات اللاحقة مع item_list: تنضم المنشورات الجديدة إلى ما هو مدرج.
  • استدعاء COMMENT بدون item_list، ولم يُضبط شيء من قبل: تصل الأحداث لمنشورات الحسابات التي فوّضت التطبيق.
  • استدعاء COMMENT بدون item_list، بعد وجود قائمة: تبقى المنشورات المضبوطة كما هي.

كيف تتحقق من الاشتراك أو تزيله؟

يعيد GET إلى /business/webhook/list/ مع app_id وsecret وevent_type الإعداد، فيظهر callback_url فقط إذا وُجد لنوع الحدث ذاك، وitem_list فقط إذا ضُبطت. أما POST إلى /business/webhook/delete/ مع app_id وsecret وevent_type فيزيله؛ وفي حالة COMMENT تزيل item_list في طلب الحذف تلك المنشورات فقط، وبدونها تتوقف أحداث التعليقات لكل المنشورات.

ماذا يجب أن يفعل عنوان URL الخاص بالاستدعاء؟

أن يرد فورا. ترسل TikTok بيانات JSON عبر HTTPS، وتعدّ أي استجابة غير HTTP 200 إرسالا فاشلا، فتعيد المحاولة بتأخير متصاعد أُسّيًا لمدة تصل إلى 72 ساعة قبل حذف الحدث. التسليم مرة واحدة على الأقل، فقد يصل الحدث نفسه مرتين، لذا يجب أن تكون المعالجة آمنة عند التكرار. يحمل كل طلب ثلاث ترويسات تستحق التسجيل: tiktok-signature وwebhook-schema-version وx-tt-logid، ويحمل جسمه client_key وevent وcreate_time بالثواني وuser_openid، وهو business_id الحساب، وcontent، وهو نص JSON متسلسل.

كيف تتحقق من Tiktok-Signature خطوة بخطوة؟

قسّم الترويسة t=<unix>,s=<hex> عند الفواصل، ثم عند علامة المساواة. ابنِ الرسالة الموقّعة من قيمة t ثم نقطة ثم نص الطلب الخام، واحسب عليها HMAC-SHA256 بمفتاح سر التطبيق، ثم رمّزها بالنظام السداسي عشري وقارنها مع s. بعد ذلك تحقق من عمر t، لأن TikTok توقّع وقت الإرسال لمنع إعادة التشغيل، ومثالها الرسمي يقبل تأخيرا قدره 5 ثوان. ويتجنب العمل على نص الطلب الخام كما استُلم إعادة ترميز JSON بشكل مختلف.

Verify a TikTok webhook in Python
import hashlib, hmac, time

def verify_tiktok(raw_body: bytes, header: str, app_secret: str, max_age: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, s = parts.get("t", ""), parts.get("s", "")
    if not t.isdigit():
        return False
    expected = hmac.new(app_secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, s) and abs(time.time() - int(t)) <= max_age

كيف تستقبل أحداث TikTok من خلال easyCoexistence نفسها؟

بإعطاء الحساب وجهة. يحتفظ easyCoexistence بتطبيقه الخاص مشتركا في COMMENT، ويتحقق من توقيع TikTok، ويرد على TikTok فورا، ويرسل كل comment.update لحساب مرتبط إلى نقطة النهاية HTTPS المحددة له. من Claude أو ChatGPT، يأخذ set_social_webhook_destination الحقلين account_id وurl، أو القيمة null للإيقاف، ويعيد سرّ توقيع لا يُعرض إلا مرة واحدة؛ وإعادة استدعائه تُصدر سرًّا جديدًا. أما أحداث النشر فلا تُعاد توجيهها، ويُستخدم get_tiktok_publish_status لمتابعة المنشور بدلا منها.

Set a destination through MCP
set_social_webhook_destination { "account_id": "<ACCOUNT_ID>", "url": "https://hooks.example.com/tiktok/" }
=> {
  "url": "https://hooks.example.com/tiktok/",
  "signing_secret": "whsec_<SECRET>",
  "note": "Shown once: store it as a secret. ..."
}

كيف تضبطه بواجهة Partner API البرمجية؟

بطلب PUT إلى /channels/{id}/webhook على https://easycoexistence.com/api/v1، مع مفتاح ec_live_ الخاص بك كرمز وصول (token) في ترويسة Bearer، وجسم هو {"url": "https://..."}. تحتوي الاستجابة على webhook_url وsigning_secret وnote، ويوقف {"url": null} إعادة التوجيه. يجب أن يكون العنوان HTTPS على مضيف عام، وتُرجع القناة غير المعروفة الرمز 404 not_found، والمحذوفة 409 removed، والموقوفة 402 suspended على التوالي.

Set a destination with the Partner API
curl -X PUT "https://easycoexistence.com/api/v1/channels/$CHANNEL_ID/webhook" \
  -H "Authorization: Bearer $EC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/tiktok/"}'

{ "webhook_url": "https://hooks.example.com/tiktok/", "signing_secret": "whsec_<SECRET>", "note": "..." }

كيف يختلف الإرسالان؟

يختلف التوجيه من easyCoexistence عن إرسال TikTok الأصلي في التوقيع والشكل، لذا يحتاج مستقبِل مكتوب لأحدهما إلى تعديلات ليعمل مع الآخر. تحتفظ الحمولة المعاد توجيهها بحقول تعليقات TikTok، مع تحليل content وجعل المعرّفات نصوصا، أما ما يتغير فهو طريقة توقيع كل إرسال وتحديد نطاقه وإعادة محاولته.

TikTok to your appeasyCoexistence to your endpoint
HeaderTiktok-Signature: t=<unix>,s=<hex>X-EC-Signature: t=<unix>,v1=<hex>
KeyThe developer app's secretThe account's signing secret, shown once
EventsVIDEO and COMMENT, per appcomment.update, per connected account
Bodyclient_key, event, create_time, user_openid, content as a stringplatform, account_id, external_id, entry with content parsed
RetriesUp to 72 hoursNone: one attempt, 8 seconds, no redirects

كيفية إعداده

  1. Grant the permissionsGive the developer app Business Content for publishing events and Business Comment for comment events, and have owners grant comment.list.
  2. Build the callbackServe an HTTPS endpoint that checks Tiktok-Signature and replies 200 before doing any work.
  3. Subscribe each event typeCall /business/webhook/update/ with app_id, secret, event_type and callback_url, once for VIDEO and once for COMMENT.
  4. Confirm the configurationCall /business/webhook/list/ for each event_type and check that the callback_url, and any item_list, came back.
  5. Handle repeatsKey each event on its content, such as comment_id with comment_action, or publish_id with the event name, before acting on it.

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

  • معالجة الحدث قبل الرد. تطلب TikTok رمز 200 فورا وتعيد محاولة الإرسالات التي لم تُقر، لذا ضع العمل في طابور وأرسل الرد أولا.
  • إرسال item_list في أول اشتراك COMMENT بالخطأ. منذ ذلك الحين تُبلغ TikTok عن أحداث التعليقات للمنشورات المدرجة فقط.
  • التحقق بـ token الوصول بدل سر التطبيق. توقّع TikTok الإرسالات بسر التطبيق نفسه الذي يأخذه /business/webhook/update/.
  • توجيه بيئتين إلى تطبيق واحد. لكل نوع حدث عنوان URL واحد لكل تطبيق، وكل استدعاء جديد لـ /business/webhook/update/ يستبدله.
إنجاز ذلك باستخدام EasyCoexistence

اضبطه بـ set_social_webhook_destination من Claude أو ChatGPT، أو عبر PUT /channels/{id}/webhook. من US$ 9 إلى US$ 0.75 لكل اتصال في الشهر، ويقل السعر كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.

الأسئلة الشائعة

ما الترويسات التي يحملها إرسال webhook من TikTok؟

tiktok-signature وwebhook-schema-version، وقيمتها الحالية v1.0، وx-tt-logid، وهو معرّف الإرسال. ويحتوي جسم JSON على client_key وevent وcreate_time وuser_openid وcontent، وهذه كلها حقول في الجسم.

هل ترسل TikTok webhook عند نشر فيديو؟

نعم، بنوع الحدث VIDEO: يصل post.publish.complete بعد أن تنزّل TikTok الملف وتتحقق منه، ثم post.publish.publicly_available مع post_id حين يصبح المنشور متاحا للعامة.

كم مدة إعادة TikTok محاولة webhook فاشل؟

حتى 72 ساعة مع تأخير متصاعد أُسّيًا، ثم يُحذف الحدث. التسليم مرة واحدة على الأقل، فتوقع التكرار.

هل يمكنني تسجيل عنوان URL خاص بي على تطبيق TikTok التابع لـ easyCoexistence نفسه؟

لا. تبقى إعدادات webhook لتطبيق easyCoexistence عنده. أما set_social_webhook_destination فيرسل إليك أحداث التعليقات الخاصة بالحساب بدلا من ذلك.

تابع القراءة

أحداث webhook لتعليقات TikTokكيف يُبلغ حدث comment.update في TikTok عن التعليقات والردود، وما يحمله كل حدث، ووصوله موقّعًا إلى نقطة النهاية (endpoint) الخاصة بك.رموز وصول TikTok API for Business: 24 ساعة والتجديد والإلغاءشرح كيف تصدر واجهة TikTok API for Business رموز الحسابات: تبديل رمز التفويض، ورمز وصول مدته 24 ساعة، والتجديد والإلغاء.نطاقات TikTok API for Business: ما يفتحه كل إذنالأذونات التي تعمل بها TikTok Accounts API بأسمائها الرسمية: ما تفتحه كل منها، ونطاقات الرمز لكل حقل، وكيفية التحقق من الرمز.كيف تنشر فيديو على TikTok عبر واجهة برمجة التطبيقات (API)انشر فيديو على TikTok عبر واجهة TikTok للأعمال، مع نقطة النشر وجسم JSON وshare_id المُعاد وطلب الحالة، بأمثلة curl وPython.ردود تعليقات TikTok والإشراف عليها عبر واجهة برمجة التطبيقات (API)كيف تقرأ واجهة TikTok للأعمال التعليقات وترد عليها وتخفيها وتحذفها، وكيف ترد القواعد والأتمتة على التعليقات الجديدة تلقائياً.كيفية متابعة حالة نشر منشور TikTok عبر واجهة برمجة التطبيقات (API)متابعة منشور TikTok المرسل عبر واجهة برمجة التطبيقات (API): share_id، والحالات PROCESSING_DOWNLOAD وPUBLISH_COMPLETE وFAILED، ومعرّفات المنشور وأسباب الفشل.

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

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

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

تم التحقق في