API المحادثات في منصة Messenger

يشرح هذا المستند كيفية الحصول على معلومات حول محادثات Messenger والمراسلة في Instagram. يمكنك الحصول على ما يلي:

• قائمة بالمحادثات في صفحة فيسبوك أو الحساب الاحترافي على Instagram
• قائمة بالرسائل داخل كل محادثة
• تفاصيل حول كل رسالة بما في ذلك وقت إرسال الرسالة ومن هو المرسل

قبل البدء

يفترض هذا العرض التوضيحي أنك قرأت نظرة عامة على منصة Messenger ونظرة عامة على المراسلة في Instagram وقمت بتنفيذ المكونات المطلوبة.

ستحتاج إلى ما يلي:

• معرف صفحة فيسبوك للنشاط التجاري أو صفحة فيسبوك المرتبطة بالحساب الاحترافي على Instagram
• رمز وصول الصفحة المطلوب من جانب الشخص الذي يمكنه تنفيذ المهمة MESSAGING أو MODERATE بالصفحة
• يلزم توفير الوصول المتقدم للوصول إلى المحادثات بين النشاط التجاري والأشخاص الذين ليس لديهم دورًا في تطبيق المراسلة أو الحساب الاحترافي على Instagram أو صفحة فيسبوك أو النشاط التجاري

بالنسبة إلى المحادثات على Messenger بين الأشخاص والصفحة، سيحتاج تطبيقك إلى ما يلي:

• رمز وصول الصفحة المطلوب بواسطة الشخص الذي يمكنه تنفيذ المهمة MESSAGING أو MODERATE بالصفحة
• الإذونات pages_manage_metadata وpages_read_engagement وpages_messaging

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

• رمز وصول الصفحة المطلوب بواسطة الشخص الذي يمكنه تنفيذ المهمة MESSAGING في الصفحة المرتبطة بحساب Instagram للأعمال
• الأذونات instagram_basic وinstagram_manage_messages وpages_manage_metadata
• يجب أن يكون تطبيقك مملوكًا بواسطة نشاط تجاري تم التحقق منه

التقييدات

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

يمكنك الاستفادة من API هذه لمزامنة البريد الوارد بشأن المحادثات السابقة عندما يكون حساب Instagram للأعمال مرتبطًا بتطبيقك مؤخرًا.

الحصول على قائمة بالمحادثات

للحصول على قائمة بالمحادثات، أرسل طلب GET إلى نقطة النهاية /PAGE-ID/conversations مع تعيين المعلمة platform على instagram أو messenger.

عينة من الطلب

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

عند نجاح العملية، سيتلقى تطبيقك كائن JSON يتضمن قائمة بمعرفات المحادثات بينك وبين شخص ما وآخر مرة تم فيها إرسال رسالة.

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
} 

البحث عن محادثة مع مستخدم محدد

للحصول على محادثة بين حسابك الاحترافي على Instagram أو صفحة فيسبوك وشخص محدد، أرسل طلب GET إلى نقطة النهاية /PAGE-ID/conversations مع تعيين المعلمتين platform وuser_id إلى المعرف على مستوى Instagram أو المعرف على مستوى الصفحة لدى هذا الشخص.

عينة من الطلب

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

عند نجاح العملية، سيحصل تطبيقك على معرف المحادثة.

{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
} 

الحصول على قائمة بالرسائل في المحادثة

للحصول على قائمة بالرسائل في المحادثات، أرسل طلب GET إلى نقطة النهاية /CONVERSATION-ID مع تضمين الحقل messages.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

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

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

الحصول على معلومات حول الرسالة

للحصول على معلومات حول الرسالة، مثل المرسل والمستلم ومحتوى الرسالة، أرسل طلب GET إلى نقطة النهاية /MESSAGE-ID يتضمن الحقول التي تهمك.

الحقول الافتراضية هي id وcreated_time.

ملاحظة: ستعمل الاستعلامات التي يتم إرسالها إلى نقطة النهاية /CONVERSATION-ID على إرجاع كل معرفات الرسالة في المحادثة. ومع ذلك، لا يمكنك سوى الحصول على تفاصيل حول آخر 20 رسالة في المحادثة. إذا كنت تستعلم عن رسالة أقدم من آخر 20 رسالة، فسيظهر خطأ يفيد بحذف الرسالة.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

عند نجاح العملية، سيتلقى تطبيقك استجابة JSON التالية: في هذا المثال أرسل العميل رسالة نصية عادية إلى الحساب الاحترافي على Instagram.

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

معرفة المزيد

تفضل بزيارة مرجع:

• نقطة نهاية المحادثات
• نقطة نهاية المحادثة
• نقطة نهاية الرسالة