‏واجهة API التحويلات‏

واجهة API التحويلات لمراسلة الأعمال

تمكن واجهة API التحويلات المعلنين من إرسال أحداث الويب والتطبيق والمتجر الفعلي ومراسلات الأعمال إلى Meta من خلال نقطة نهاية واحدة بدلاً من مصادر متعددة. يمكن أن يؤدي هذا الدمج إلى تبسيط مجموعة التقنيات لدى المعلن وإنشاء عرض أكثر شمولاً داخل مدير الأحداث من Meta باستخدام مجموعات البيانات.

توفر هذه الوثائق إرشادات لدمج أحداث مراسلة الأعمال في واجهة API التحويلات. تشمل مزايا استخدام واجهة API التحويلات في مراسلة الأعمال (على سبيل المثال لا الحصر):

  • رؤية النتائج مباشرة في تقارير مدير الإعلانات: يمكن للمعلنين فهم نتائج حملة النقر للمراسلة استنادًا إلى النتائج التي تهمهم مباشرة على منصات Meta، على سبيل المثال، عدد عمليات الشراء والتكلفة لكل عملية شراء، بدلاً من المحادثات التي بدأت.
  • تبسيط دمج البيانات: API واحدة لاستيعاب البيانات ومشاركتها عبر منصات المراسلة المتعددة (Messenger، واتساب) والقنوات (موقع الويب، التطبيق، المتاجر، الرسائل).
  • تحسين قياس الشركاء: تمكين إسناد حملة النقر للمراسلة مباشرةً في لوحات معلومات الشركاء من خلال API رؤى الإعلانات.

المتطلبات الأساسية

مجموعة البيانات

يجب أن تكون أحداث مراسلة الأعمال المرسلة عبر واجهة API التحويلات مرتبطة بمجموعة بيانات.

تسمح مجموعات البيانات للمعلنين بربط بيانات الأحداث وإدارتها من مصادر أحداث الويب والتطبيقات والمتجر ومراسلة الأعمال إلى واجهة API التحويلات. قد تعرض مجموعات البيانات بيانات الأحداث من أي من عمليات الدمج هذه التي تختار إعدادها:

  • بيكسل Meta (أحداث مواقع الويب)
  • واجهة API أحداث التطبيق (أحداث التطبيق، بما في ذلك مجموعة Facebook SDK لنظام التشغيل iOS أو Android وشركاء قياس الأداء على الهواتف المحمولة (MMP))
  • واجهة API التحويلات بلا اتصال (واجهة API القديمة من Meta لأحداث التحويل بلا اتصال)

تمكنك مجموعات البيانات من عرض جميع أنشطة العملاء من واجهة واحدة. كما تسمح لك أيضًا بتقليل الجهود المبذولة لإنشاء العديد من عمليات دمج API وصيانتها.

في مدير الأحداث، تتوفر لدى المعلنين خيارات مختلفة لإنشاء مجموعة بيانات اعتمادًا على نقطة البداية الخاصة بهم. أو يمكنك إنشاء مجموعة بيانات جديدة تمامًا في مدير الأحداث عن طريق الربط أثناء إنشاء مجموعة أحداث التحويل بلا اتصال أو من خلال تطبيق هاتف محمول موجود أو أثناء مراسلة معلومات إنشاء مجموعة الأحداث. لاحظ أن ربط مجموعة بيانات بأحد التطبيقات مطلوب قبل إرسال أحداث تطبيقات الهواتف المحمولة إلى واجهة API التحويلات ويمكن ربط تطبيق واحد فقط بمجموعة بيانات. يمكنك عرض المزيد من التفاصيل والتعليمات هنا.

الأذونات

تأهيل الشريك

إذا كنت تنفذ دمج الشركاء كمنصة، فيمكنك استخدام أسلوب التأهيل من خلال تسجيل دخول فيسبوك للأعمال (موصى بها) أو ملحق Meta للأعمال.

يرجى الرجوع إلى واجهة API التحويلات للاطلاع على دلائل مراسلة الأعمال، التي تحتوي على دلائل الدمج مع تعليمات تفصيلية.

API مجموعة البيانات للمراسلة وواتساب

يتم استخدام API مجموعة البيانات لاسترداد dataset_id المرفق بالصفحة المحددة. يتم استخدام dataset_id هذا لاحقًا في واجهة API التحويلات. لتتمكن من استخدام API مجموعة البيانات، ستحتاج إلى إذن page_events لأحداث Messenger أو واتساب التي تم منحها لتطبيقك بواسطة العميل من خلال تسجيل دخول فيسبوك للأعمال أو ملحق Meta للأعمال.

لاسترداد dataset_id، يجب تنفيذ استدعاء GET في API مجموعة البيانات مع توفير page_id وaccess_token. اطلع على عينة الاستدعاء أدناه:

https://graph.facebook.com/v16.0/{PAGE_ID}/dataset?access_token={TOKEN}

ستكون الاستجابة عبارة عن معرف يمثل dataset_id. باستخدام هذا المعرف ورمز الوصول الذي تم استلامه مسبقًا، يمكنك الآن استدعاء واجهة API التحويلات لإرسال أحداث المراسلة إلى Meta.

API مجموعة البيانات في Instagram

يتم استخدام API مجموعة البيانات لاسترداد dataset_id المرفق بالصفحة المحددة. يتم استخدام dataset_id هذا لاحقًا في واجهة API التحويلات. لتتمكن من استخدام API مجموعة البيانات، ستحتاج إلى الإذن instagram_manage_events الذي تم منحه لتطبيقك بواسطة العميل من خلال تسجيل دخول فيسبوك للأعمال أو ملحق Meta للأعمال.

لاسترداد dataset_id، يجب تنفيذ استدعاء GET في API مجموعة البيانات مع توفير ig_user_id وaccess_token. فيما يلي عينة من الاستدعاء:

https://graph.facebook.com/v16.0/{IG_USER_ID}/dataset?access_token={TOKEN}

ستكون الاستجابة عبارة عن معرف يمثل dataset_id. باستخدام هذا المعرف ورمز الوصول الذي تم استلامه مسبقًا، يمكنك الآن استدعاء واجهة API التحويلات لإرسال أحداث المراسلة إلى Meta.

التكوين

إعداد معلمات أحداث مراسلة الأعمال

يمكنك الرجوع هنا لمعرفة المجموعة الحالية من المعلمات التي يمكن إرسالها عبر واجهة API التحويلات. لإرسال أحداث مراسلة الأعمال، يمكن مشاركة الحقول التالية في حمولة بيانات المستخدمين لمنصات المراسلة المختلفة:

المنصةالمعلمةالوصف

Messenger

page_id

مطلوب لـ Messenger

معرف صفحة فيسبوك المرتبطة بالنشاط التجاري.

Messenger

page_scoped_user_id

مطلوب لـ Messenger

يتم تحديد المستخدمين الذين يتفاعلون مع الصفحات من خلال معرفات المستخدم على مستوى الصفحة (PSID). يمكن الحصول على معرف PSID من حدث webhook هذا.

واتساب

page_id

مطلوب لواتساب

معرف صفحة الفيسبوك المرتبطة بحساب واتساب للأعمال.

واتساب

ctwa_clid

مطلوب لواتساب

يتوفر ctwa_clid فقط من كائن الإحالة ضمن حدث webhook للرسائل في إصدارات API الأعمال 2.45.1 والإصدارات الأحدث (API داخل المواقع) أو API السحابة.

Instagram

ig_account_id

مطلوب لـ Instagram

معرّف حساب Instagram المرتبط بالنشاط التجاري.

Instagram

ig_sid

مطلوب لـ Instagram

يتم تحديد المستخدمين الذين يتفاعلون مع Instagram بواسطة معرفات المستخدمين على مستوى Instagram (IGSID). يمكن الحصول على معرف IGSID من حدث webhook هذا.


إرسال الأحداث

لإرسال أحداث جديدة، أرسل طلب POST إلى واجهة API التحويلات من هذا المسار:

https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

عند النشر على عنصر الربط هذا، تقوم Meta بإنشاء أحداث جديدة لمراسلة الأعمال. لمزيد من التفاصيل، يرجى الرجوع إلى مستند المطوّر التالي.

فيما يلي نظرة عامة على كيفية توافق المعلمات مع المخطط العام في حمولة البيانات.

بالنسبة لأحداث Messenger:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "messenger",
      "user_data": {
        "page_id": <PAGE_ID>,
        "page_scoped_user_id": <PSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

بالنسبة لأحداث واتساب:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "user_data": {
        "page_id": <PAGE_ID>,
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

بالنسبة لأحداث Instagram:

عينة من طلب CTD في واجهة CAPI

POST /{dataset_id}/events

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "instagram",
      "user_data": {
        "ig_account_id": <IG_ACCOUNT_ID>,
        "ig_sid": <IGSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

استكشاف الأخطاء وإصلاحها

استخدم أداة اختبار الأحداث في مدير الأحداث للاختبار:

  • انتقل إلى مدير الأحداث، وحدّد مجموعة بيانات مرتبطة بالصفحة
  • انقر على علامة التبويب "اختبار الأحداث"
  • حدّد قناة التسويق وقناة المراسلة
  • انقر على زر مستكشف Graph API
  • سيتم ملء م��تكشف Graph API بحمولة البيانات المملوءة مسبقًا
  • انقر على زر "إرسال"

فيديو تفصيلي

شاهد هذا الفيديو للحصول على شرح تفصيلي حول كيفية تنفيذ الدمج.

حدث خطأ ما
لدينا مشكلة في تشغيل هذا الفيديو.
تعرف على المزيد

الأسئلة المتكررة

ما نوع أحداث المراسلة التي تدعمها واجهة API التحويلات لمراسلة الأعمال؟

ج: تدعم واجهة API التحويلات لمراسلة الأعمال حاليًا فقط العملاء المحتملين الذين تم إرسالهم وأحداث الشراء لمراسلة الأعمال. يرجى ملاحظة أن أحداث المراسلة يجب أن تمثل فقط تفاعلات العملاء التي تحدث في سلسلة الرسائل، وليس التحويلات التي تحدث في القنوات الأخرى مثل مواقع الويب. يمكنك تمييز الأحداث بسهولة عن طريق اختيار مصدر الإجراء المقابل أثناء عملية الدمج.

هل هناك إرشادات من Meta تنص على استخدام التطبيق نفسه أو استخدام تطبيقات مختلفة لعمليات دمج واجهة API التحويلات المختلفة؟

ج: من ضمن أفضل الممارسات أن يستخدم الشريك تطبيقًا واحدًا، حتى تتمكن Meta من التعرف على جميع الأحداث المرسلة من جانب الشريك. إذا كنت شريكًا ولديك بالفعل تطبيقات متعددة، فتأكد من تعيين partner_agent على اسم وكيل الشريك الذي تم تعيينه لك. تحدث مع ممثل Meta إذا كنت غير متأكد.

إذا حدث تحويل خارج سلسلة الرسائل (على موقع الويب أو التطبيق، على سبيل المثال)، فكيف يمكننا إرسال الأحداث إلى Meta؟

ج: إذا حدث تحويل خارج سلسلة الرسائل، فيجب إعادة إرسال هذا الحدث إلى Meta باستخدام منتج واجهة API التحويلات ذي الصلة. على سبيل المثال، إذا حدث تحويل على موقعك على الويب، فاستخدم واجهة API التحويلات للويب. إذا حدث التحويل على تطبيقك، فاستخدم واجهة API التحويلات لأحداث التطبيق. وسيظل الحدث منسوبًا إلى معرف النقر في واجهة API التحويلات للويب. يمكن العثور على قائمة كاملة بالمعلمات هنا.

هل تعمل واجهة API التحويلات على تمكين تحسين إعلانات النقر للمراسلة؟

ج: تت��ح واجهة API التحويلات الوصول إلى تحسين الشراء لإعلانات النقر لفتح محادثة في Messenger فقط، ولكنها غير متوفرة لتحسين الإعلانات على واتساب في الوقت الحالي. بالنسبة لإعلانات النقر لفتح محادثة في واتساب، يمكنك تحسين حملاتك الإعلانية للحصول على المزيد من المحادثات.

هل يمكنني إعادة استخدام مجموعة البيانات الحالية في واجهة API التحويلات لمراسلة الأعمال؟

ج: نعم، ندعم الربط مع مجموعة البيانات الحالية، يمكنك الرجوع إلى الخيارات المتوفرة لتحديد الخيار المناسب لنشاطك التجاري.

إذا كنت أستخدم واجهة API التحويلات لموقع الويب حاليًا، فهل تتداخل إضافة مراسلات الأعمال إلى الدمج نفسه مع الدمج الحالي لدي؟

ج: لا يوجد أي خطر من إضافة رسائل الأعمال إلى دمج واجهة API التحويلات الحالي لديك. يعتمد الإسناد على معرف الصفحة/مجموعة البيانات ولا يرتبط بمعرف التطبيق.

كم عدد مجموعات البيانات التي يمكن ربطها بالصفحة؟

ج: يمكنك ربط مجموعة بيانات واحدة فقط بالصفحة.

هل أحتاج إلى إلغاء تكرار الأحداث قبل إرسالها عبر واجهة API التحويلات لمراسلة الأعمال؟

ج: لا تساعد Meta في إلغاء تكرار الأحداث في واجهة API التحويلات لمراسلة الأعمال، لذا نشجع المعلنين بشدة على إلغاء تكرار البيانات قبل إرسالها عبر واجهة API تحويلات لمراسلة الأعمال.

راجع أيضًا