الترحيل من API داخل المواقع إلى API السحابة

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

لاحظ أن ترحيل رقم هاتف النشاط التجاري من API إلى أخرى لا يشبه عملية ترحيل رقم الهاتف من حساب واتساب للأعمال (WABA) إلى آخر.

للترحيل من API السحابة إلى API داخل المواقع، راجع الترحيل من API السحابة إلى API داخل المواقع.

طريقة العمل

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

لا يؤثر الترحيل على ما يلي:

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

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

المتطلبات

تطبيق Meta

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

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

مراجعة التطبيقات

يجب أن يخضع تطبيق Meta إلى عملية مراجعة التطبيقات وأن تتم الموافقة عليه (أي يحصل على الوصول المتقدم) للحصول على الإذنين whatsapp_business_messaging وwhatsapp_business_management.

أفضل الممارسات

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

نوصي أيضًا بإجراء الترحيل عندما يكون عدد زيارات النشر في API داخل المواقع منخفضًا.

اختلافات API

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

Webhooks

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

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

• التكوين: أحداث Webhooks لواتساب
• حمولات بيانات حدث webhook في API السحابة: مرجع حمولة بيانات إشعار أحداث Webhooks
• حمولات بيانات حدث webhook في API إدارة الأعمال: إعداد أحداث Webhooks

لاحظ أنه بعد ترحيل رقم هاتف النشاط التجاري إلى API السحابة، يجب استخدام نقطة النهاية حساب واتساب للأعمال > التطبيقات المشتركةلتسجيل اشتراك تطبيق Meta في أحداث webhooks على حساب واتساب للأعمال المرتبط برقم النشاط التجاري:

بنية الطلب

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

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

الوسائط

يتعذر استخدام معرفات الوسائط لأي وسائط تم تحميلها على API داخل المواقع عند إرسال الرسائل من خلال API السحابة، حيث يجب إعادة تحميل الوسائط باستخدام API السحابة لإنشاء معرفات وسائط جديدة أو استخدام عناوين URL الوسائط إذا تمت استضافة الوسائط على خادم عام. راجع رسائل الوسائط وقوالب الرسائل المستندة إلى الوسائط.

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

رموز الأخطاء

تختلف رموز الأخطاء في API السحابة وAPI إدارة الأعمال عن رموز الأخطاء في API داخل المواقع. راجع المستندات التالية:

• رموز الأخطاء في API السحابة
• رموز الأخطاء في API إدارة الأعمال

التحقق من صحة الخاصية

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

رسائل الضغط للتحدث

تتعرف الواجهة داخل المواقع على رسائل الضغط للتحدث (PTT) في أحداث webhooks عن طريق تعيين messages.type على voice، ولكن تتعرف API السحابة على رسائل PTT عن طريق تعيين messages.audio.voice على true.

حزم الملصقات

لا تدعم API السحابة حزم الملصقات.

زمن التوقف

يبدأ زمن التوقف بمجرد تنفيذ خطوة الترحيل الأخيرة (تسجيل الرقم للاستخدام مع API السحابة) ومن المفترض أن يستمر لبضع ثوانٍ فقط. أثناء هذا الوقت، سيتم تجاهل الرسائل المرسلة إلى الرقم من مستخدمي واتساب.

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

معدل الإرسال

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

الحسابات التجارية الرسمية

إذا كنت تحاول ترحيل رقم هاتف نشاط تجاري لديه حالة حساب تجاري رسمي (OBA)، فسيتم الاحتفاظ بالحالة إذا قمت بتضمين بيانات التعريف (التي تم إنشاؤها في الخطوة 2) عند تسجيل الرقم (الخطوة 3). إذا قمت بحذف هذه البيانات، فسيفقد الرقم حالة OBA (حساب تجاري رسمي).

دعم الترحيل

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

• الموضوع: WABiz: API السحابة
• نوع الطلب" API داخل المواقع -> مشكلات ترحيل API السحابة

الخطوة الأولى: تعطيل التحقق بخطوتين

إذا كنت تعرف رقم التعريف الشخصي (PIN) لرقم هاتف النشاط التجاري، فيمكنك تخطي هذه الخطوة.

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

الخطوة الثانية: إنشاء بيانات تعريف رقم الهاتف

استخدم API النسخ الاحتياطي والاستعادة لإنشاء بيانات تعريف رقم هاتف النشاط التجاري.

بنية الطلب

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

يمكن أن يكون <PASSWORD> أي سلسلة. سيتم استخدام هذه القيمة لترميز بيانات التعريف، لذلك احفظها لأنك ستحتاج إليها في الخطوة التالية.

الاستجابة

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

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

• <METADATA> — هذه سلسلة تم ترميزها تصف رقم هاتف النشاط التجاري وإعداداته. احتفظ بهذه القيمة حيث إنك ستحتاج إليها في الخطوة التالية.
• <API_STATUS> — حالة نشر API داخل المواقع.
• <API_VERSION> —رقم إصدار API داخل المواقع التي تقوم بتشغيلها.

مثال على الطلب

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

مثال على الاستجابة

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

الخطوة الثالثة: تسجيل الرقم

استخدم نقطة النهاية رقم هاتف واتساب للأعمال > التسجيل في API السحابة لتسجيل الرقم لاستخدامه مع API السحابة.

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

بنية الطلب

POST /<BUSINESS_PHONE_NUMBER_ID>/register

نص المنشور

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}

• <NEW_OR_EXISTING_PIN> — رقم التعريف الشخصي الموجود أو رقم التعريف الشخصي الذي تريد تعيينه على رقم هاتف النشاط التجاري.
• <PASSWORD> — كلمة السر التي استخدمتها لإنشاء بيانات تعريف رقم هاتف النشاط التجاري في الخطوة السابقة.
• <METADATA> —السلسلة التي تم ترميزها التي تصف رقم هاتف النشاط التجاري وإعداداته، والتي تم إنشاؤها في الخطوة السابقة.

الاستجابة

{
  "success": <SUCCESS>
}

ستستجيب API بتعيين success على true إذا كان التسجيل ناجحًا، أو false إذا كان هناك خطأ.

مثال على الطلب

curl 'https://graph.facebook.com/v21.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

مثال على الاستجابة

{
  "success": true
}

الخطوة الرابعة: التحقق من حالة أداء المراسلة (اختياري)

اطلب الحقل health_status في رقم هاتف النشاط التجاري وتحقق من إمكانية استخدامه للمراسلة من خلال API السحابة. راجع حالة أداء المراسلة.