‏منصة Messenger‏

مرجع واجهة API الإرسال

واجهة API الإرسال هي واجهة API الرئيسية المستخدمة في إرسال الرسائل إلى المستخدمين، بما في ذلك نص الرسالة والمرفقات والقوالب وإجراءات المرسلين وغير ذلك الكثير.

الإنشاء

يمكنك إنشاء الرسائل وإرسالها إلى عملائك أو إلى الأشخاص المهتمين بصفحتك على فيسبوك.

قبل البدء

ستحتاج إلى:

  • رمز وصول صفحة يطلبه الشخص الذي يمكنه أداء مهمة MESSAGE على الصفحة
  • الإذن pages_messaging
  • يجب أن يكون متلقي الرسالة قد أرسل رسالة إلى صفحتك خلال آخر 24 ساعة أو وافق على تلقي رسائل من صفحتك خارج مدة المراسلة القياسية البالغة 24 ساعة

القيود

  • لا يمكن استخدام علامات الرسائل لإرسال محتوى ترويجي

لاحظ أن API الإرسال لا تتضمن recipient_id في الاستجابة للرسائل المرسلة باستخدام recipient.user_ref أو recipient.phone_number لتحديد مستلم الرسالة.

نموذج طلب

لإرسال رسالة إلى شخص، أرسل طلب POST إلى نقطة نهاية /PAGE-ID/messsages تحتوي على مجموعة معلمات messaging_type وrecipient، ومحتوى الرسالة.

تعيين التنسيق لسهولة القراءة.

المثال التالي عبارة عن رد على رسالة الشخص عندما تكون الرسالة التي ترسلها صفحتك عبارة عن نص فقط.

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages
    ?recipient={'id':'PSID'}
    &messaging_type=RESPONSE
    &message={'text':'hello,world'}
    &access_token=PAGE-ACCESS-TOKEN

في حالة النجاح، سيتلقى تطبيقك استجابة JSON التالية:

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
}

المعلمات

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

message

الكائن

نوع الرسالة التي ترسلها صفحتك. يجب تعيين text أو attachement عند استخدام هذه المعلمة.

  • كائن attachment - يعرض معاينة لعنوان URL. يُستخدم لإرسال رسائل تحتوي على وسائط أو رسائل ذات بنية محددة. يجب تعيين text أو attachment.

    • type - نوع المرفق. يمكن أن يكون audio أو file أو image أو template أو video. الحد الأقصى لحجم الملف 25 ميجابايت.
    • payload - كائن يحتوي على محتوى قالب أو محتوى ملف

  • metadata - سلسلة بيانات إضافية تريد تمريرها في message_echo webhook. يجب أن تكون أقل من 1000 حرف

  • quick_replies - مصفوفة ردود سريعة مقرر إرسالها في رسالة
  • text - رسالة تحتوي على نصف فقط. يجب أن تكون بتنسيق UTF-8 وأقل من 2000 حرف.

messaging_type

تعداد

مطلوب

نوع الرسالة التي يتم إرسالها

notification_type

تعداد

نوع الإشعار المباشر الذي سيتلقاه الشخص

  • NO_PUSH- لا توجد إشعارات
  • REGULAR (افتراضي) - صوت أو اهتزاز عند تلقي الشخص للرسالة
  • SILENT_PUSH - إشعار على الشاشة فقط

recipient

الكائن

مطلوب

الشخص الذي سيتلقى الرسالة التي ترسلها صفحتك

  • id - معرف الشخص على مستوى الصفحة الخاص والذي يتم استخدامه لإرسال رسالة ردًا على تلقي صفحتك لرسالة خلال آخر 24 ساعة أو لشخص وافق على تلقي رسائل من صفحتك خارج فترة المراسلة القياسية البالغة 24 ساعة
  • user_ref - معرف الشخص والذي يتم استخدامه لإرسال رسالة استجابة لمربع اختيار أو المكون الإضافي "دردشة العملاء"
  • comment_id - معرف التعليق والذي يتم استخدامه لإرسال رسالة كرد خاص استجابة لتعليق أحد الزوّار على منشور بصفحتك
  • post_id - معرف منشور الصفحة والذي يتم استخدامه لإرسال رسالة كرد خاص استجابة لمنشور أحد الزوّار بصفحتك

sender_action

تعداد

أيقونة الإجراء التي تظهر في نافذة المراسلة والتي تمثل الإجراء الذي اتخذته الصفحة بشأن رسالة تلقتها الصفحة من أحد الأشخاص.

  • typing_on - عرض فقاعة الكتابة عند قيام الصفحة بإعداد رد
  • typing_off- عدم عرض فقاعة الكتابة
  • mark_seen - عرض أيقونة تم المشاهدة للرسائل التي شاهدتها الصفحة

لا يتم إرسالها إلا بالمعلمة recipient. لا يمكن إرسالها بالمعلمة message ولكن يجب إرسالها كطلب منفصل.

tag

تعداد

علامة تمكّن صفحتك من إرسال رسالة إلى شخص خارج فترة المراسلة القياسية البالغة 24 ساعة.

  • ACCOUNT_UPDATE - وضع علامة على الرسالة التي ترسلها إلى عميلك كتحديث غير متكرر بشأن طلبه أو حسابه. عرض الاستخدامات المسموح بها.

    غير متوفرة لواجهة Instagram Messaging API.

  • CONFIRMED_EVENT_UPDATE - وضع علامة على الرسالة التي ترسلها إلى عميلك كتذكير بمناسبة قادمة أو تحديث لمناسبة جارية قام العميل بالتسجيل فيها. عرض الاستخدامات المسموح بها.

    غير متوفرة لواجهة Instagram Messaging API.

  • CUSTOMER_FEEDBACK - وضع علامة على الرسالة التي ترسلها إلى عميلك في صورة استبيان ملاحظات العملاء . يجب إرسال رسائل ملاحظات العملاء في غضون 7 أيام من آخر رسالة للعميل. عرض الاستخدامات المسموح بها.

    غير متوفرة لواجهة Instagram Messaging API.

  • HUMAN_AGENT - مطلوبة لواجهة Instagram Messaging API. عند إضافة هذه العلامة إلى رسالة يتم إرسالها إلى شخص، فإنها تتيح لممثل فعلي الرد على رسالة الشخص. يمكن إرسال الرسائل خلال 7 أيام من رسالة الشخص. يتم تقديم الدعم من خلال ممثل فعلي في حالة المشكلات التي لا يمكن حلها خلال المدة القياسية للرسائل. عرض الاستخدامات المسموح بها.
    • ستحتاج التطبيقات إلى تقديم طلب للحصول على الإذن Human Agent من خلال لوحة معلومات تطبيق المطوّر. انتقل إلى لوحة معلومات تطبيق المطوّر - > مراجعة التطبيق -> الأذونات والميزات -> ممثل فعلي. التطبيقات التي سبقت الموافقة عليها للوصول التجريبي إلى إذن الممثل الفعلي لا تحتاج إلى تقديم طلب مرة أخرى للوصول.

    الإذن Human Agent غير متوفر في وضع الوصول القياسي أو المطوّر. سيلزمك إكمال عملية مراجعة التطبيق قبل أن تتمكن من الاستفادة من علامة الممثل الفعلي. خلال إرسال التطبيق للمراجعة، يرجى تقديم إرشادات واضحة وشرح واضح للطريقة التي تنوي بها الاستفادة من علامة الممثل الفعلي في تجاربك.

  • POST_PURCHASE_UPDATE - وضع علامة على الرسالة التي ترسلها إلى عميلك كتحديث لعملية شراء حديثة أجراها العميل. عرض الاستخدامات المسموح بها.

    غير متوفرة لواجهة Instagram Messaging API.

استخدام علامة الرسالة

يذكر الجدول التالي أنواع المراسلات لكل علامة رسالة.

علامة الرسالةالاستخدام

ACCOUNT_UPDATE

الاستخدامات المسموح بها

  • إشعار بوجود تغيير في حالة الطلب، على سبيل المثال، لبطاقة ائتمان أو طلب توظيف
  • إشعار بوجود نشاط مشبوه، على سبيل المثال، تنبيهات الاحتيال

الاستخدامات غير المسموح بها (على سبيل المثال لا الحصر)

  • المحتوى الترويجي، بما في ذلك، على سبيل المثال لا الحصر، المحتوى المتكرر للصفقات وعمليات الترويج والقسائم والخصومات (مثال: كشف الحساب جاهز، الفاتورة مستحقة، وظائف جديدة)
  • المطالبات الخاصة بأي استبيان أو استطلاع رأي أو مراجعات غير مرتبطة بتفاعل سابق في Messenger

غير متوفرة لواجهة Instagram Messaging API.

CONFIRMED_EVENT_UPDATE

الاستخدامات المسموح بها

  • تذكير بفصل دراسي أو موعد أو مناسبة قادمة قام المستخدم بجدولتها
  • تأكيد حجز أو حضور المستخدم لمناسبة أو موعد مقبول
  • إشعار بشأن سفر أو رحلة مجدولة للمستخدم، مثل الوصول أو الإلغاء أو تأخر الأمتعة أو أي تغيير آخر في حالة السفر

الاستخدامات غير المسموح بها (على سبيل المثال لا الحصر)

  • المحتوى الترويجي، بما في ذلك، على سبيل المثال لا الحصر، الصفقات والعروض والقسائم والخصومات
  • المحتوى المرتبط بمناسبة لم يسجل فيها المستخدم (على سبيل المثال، تذكيرات بشراء تذاكر المناسبات، بيع تذاكر مناسبات أخرى، جداول جولات السفر، وغير ذلك)
  • الرسائل المرتبطة بالمناسبات السابقة
  • المطالبات الخاصة بأي استبيان أو استطلاع رأي أو مراجعات غير مرتبطة بتفاعل سابق في Messenger

غير متوفرة لواجهة Instagram Messaging API.

CUSTOMER_FEEDBACK

الاستخدامات المسموح بها

  • استبيان للحصول على ملاحظات دعم الشراء
  • استبيان للحصول على ملاحظات بشأن المناسبة
  • آراء حول المنتج

الاستخدامات غير المسموح بها (على سبيل المثال لا الحصر)

  • يمكن استخدام العلامة فقط مع قالب ملاحظات العملاء. يُحظر وسيفشل استخدامها بأي شكل آخر.

غير متوفرة لواجهة Instagram Messaging API.

HUMAN_AGENT

الاستخدامات المسموح بها

  • دعم الممثل الفعلي للمشكلات التي لا يمكن حلها خلال مدة المراسلة القياسية البالغة 24 ساعة، مثل حل المشكلات التي تحدث خارج أوقات العمل المعتادة أو المشكلات التي يتطلب حلها أكثر من 24 ساعة

الاستخدامات غير المسموح بها (على سبيل المثال لا الحصر)

  • الرسائل التلقائية
  • المحتوى غير المرتبط باستفسار المستخدم

مطلوبة لواجهة Instagram Messaging API.

POST_PURCHASE_UPDATE

الاستخدامات المسموح بها

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

الاستخدامات غير المسموح بها (على سبيل المثال لا الحصر)

  • المحتوى الترويجي، بما في ذلك، على سبيل المثال لا الحصر، الصفقات والعروض الترويجية والقسائم والخصومات
  • الرسائل التي تعرض منتجات أو خدمات ذات صلة أو ترغب في بيع البديل الأغلى
  • المطالبات الخاصة بأي استبيان أو استطلاع رأي أو مراجعات غير مرتبطة بتفاعل سابق في Messenger

غير متوفرة لواجهة Instagram Messaging API.

القراءة

لا يمكنك تنفيذ هذه العملية في نقطة النهاية هذه.

للحصول على معلومات عن المحادثات التي تشارك فيها صفحتك، قم بزيارة مرجع محادثات الصفحة.

التحديث

لا يمكنك تنفيذ هذه العملية في نقطة النهاية هذه.

الحذف

لا يمكنك تنفيذ هذه العملية في نقطة النهاية هذه.

راجع أيضًا

دعم المطوّر

  • استخدم أداة حالة Meta للتحقق من حالة منتجات الأنشطة التجارية في Meta وحالات الانقطاع.
  • استخدم أداة دعم مطوّر Meta للإبلاغ عن الأخطاء وعرض الأخطاء التي تم الإبلاغ عنها والحصول على المساعدة بشأن الإعلانات أو مدير الأعمال والمزيد.
  • تفضل بزيارة موارد الدعم في منصة Messenger لعرض المزيد من الموارد المخصصة لدعم منصة Messenger.