دليل بدء الاستخدام لشركاء الحلول

يوضح هذا الدليل الخطوات المطلوبة من جانب شركاء الحلول لتوفير API السحابة للعملاء. توجد 4 مراحل أساسية:

1. التحضير والتخطيط
2. إعداد الأصول
3. توقيع العقود
4. إنشاء الدمج

بعد الانتهاء، يُرجى متابعة التحديثات الشهرية.

التحضير والتخطيط

قراءة الوثائق

قبل البدء، نوصي بقراءة وثائق المطوّر ومجموعة Postman. هذا يساعدك في فهم كيفية عمل API السحابة، بما في ذلك كيفية بدء الاستخدام وترحيل الأرقام.

تخطيط الإعداد والترحيل

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

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

بمجرد تحديد العملاء الذين سيتم ترحيلهم، يمكنك إنشاء خطة ترحيل وجدول زمني.

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

تخطيط التواصل مع العملاء

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

اتخاذ قرارات التسعير

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

إعداد الأصول

لاستخدام API السحابة، يحتاج شركاء الحلول إلى الحصول على الأصول التالية:

توقيع العقود

قبول شروط الخدمة

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

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

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

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

إنشاء الدمج

الخطوة الأولى: الحصول على رمز وصول مستخدم النظام

تستخدم استدعاءات واجهة Graph API رموز الوصول للمصادقة. لمزيد من المعلومات، راجع رموز الوصول. نوصي باستخدام مستخدم النظام لإنشاء الرمز.

لإنشاء رمز وصول مستخدم النظام:

1. انتقل إلى مدير الأعمال > إعدادات مدير الأعمال > المستخدمون > مستخدمو النظام لعرض مستخدم النظام الذي أنشأته.
2. انقر على هذا المستخدم وحدّد إضافة الأصول. ويفتح هذا الإجراء نافذة جديدة.
3. ضمن تحديد نوع الأصل على الجزء الجانبي الأيمن، حدّد التطبيقات. ضمن تحديد الأصول، اختر تطبيق Meta الذي تريد استخدامه (يجب أن يحصل تطبيقك على الأذونات الصحيحة). مكّن تطوير التطبيق لهذا التطبيق.
4. حدّد حفظ التغييرات لحفظ الإعدادات والعودة إلى شاشة مستخدم النظام الرئيسية.
5. أصبحت مستعدًا الآن لإنشاء الرمز. في شاشة مستخدم النظام الرئيسية، انقر على إنشاء رمز وحدّد تطبيق Meta. بعد تحديد التطبيق، ستظهر قائمة الأذونات المتوفرة. حدّد whatsapp_business_management وwhatsapp_business_messaging. انقر على إنشاء رمز.
6. سيتم فتح نافذة جديدة تضم مستخدم النظام والتطبيق المعين ورمز الوصول. احفظ الرمز.
7. يمكنك النقر على الرمز بشكل اختياري وعرض مصحح أخطاء الرمز. في مصحح الأخطاء، من المفترض أن ترى الإذنين اللذين حددتهما. يمكنك أيضًا لصق الرمز مباشرةً في مصحح أخطاء رمز الوصول.

الخطوة الثانية: إعداد أحداث Webhooks

بعد إعداد أحداث Webhooks، يمكنك تلقي إشعارات HTTP فوريًا من منصة واتساب للأعمال. وهذا يعني أنه سيتم إرسال إشعار إليك عندما تحصل على رسالة من عميل على سبيل المثال أو عندما توجد تغييرات في حساب واتساب للأعمال (WABA).

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

إعداد التطبيق

بمجرد أن تصبح نقطة النهاية جاهزة، يمكنك تكوينها ليتم استخدامها بواسطة تطبيق Meta لديك:

ما عليك سوى إعداد أحداث Webhook مرة واحدة لكل تطبيق لديك. يمكنك استخدام حدث Webhook ذاته لتلقي أنواع أحداث متعددة من حسابات واتساب للأعمال المختلفة. لمزيد من المعلومات، اطلع على قسم أحداث Webhooks.

الخطوة الثالثة: الاشتراك في حساب واتساب للأعمال

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

curl -X POST \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
-H 'Authorization: Bearer ACCESS_TOKEN'

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

{
  "success": true
}

الخطوة الرابعة: الحصول على معرف رقم الهاتف

لإرسال الرسائل، يجب تسجيل رقم الهاتف الذي تريد استخدامه - هذا هو رقم هاتف النشاط التجاري الذي تم ذكره في قبل البدء.

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

curl -X GET \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
-H 'Authorization: Bearer ACCESS_TOKEN'

إذا نجح الطلب، فستتضمن الاستجابة كل أرقام الهواتف المرتبطة بحساب واتساب للأعمال:

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

احفظ معرف رقم الهاتف الذي تريد تسجيله. راجع قراءة أرقام الهواتف لمزيد من المعلومات حول نقطة النهاية هذا.

استثناء الترحيل

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

لمجرد توفر معرف رقم الهاتف، يمكنك تسجيله. في استدعاء API التسجيل، يمكنك تنفيذ إجراءين في الوقت ذاته:

1. تسجيل الهاتف.
2. تمكين التحقق بخطوتين عن طريق تعيين رمز تسجيل مكون من 6 أرقام، ويجب تعيين هذا الرمز من جانبك. احفظ هذا الرمز وتذكره حيث إنه يمكن طلبه لاحقًا.

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

عينة من الطلب:

curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp","pin": "6_DIGIT_PIN"}'

عينة من الاستجابة:

{
  "success": true
}

مستخدمو التسجيل المضمن

الخطوة السادسة: تلقي رسالة من تطبيق المستهلك

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

من تطبيق واتساب شخصي لنظام iOS/Android، أرسل رسالة إلى رقم الهاتف الذي سجلته للتو. بمجرد إرسال الرسالة، من المفترض أن تتلقى رسالة واردة إلى حدث Webhook تتضمن إشعارًا بالتنسيق التالي.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315551234",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16315555555"
              }
            ],
            "messages": [
              {
                "from": "16315555555",
                "id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXmuSf",
                "timestamp": "1602139392",
                "text": {
                  "body": "Hello!"
                },
                "type": "text"
                }
            ]
          },
        "field": "messages"
        }
      ]
    }
  ]
}

الخطوة السابعة: إرسال رسالة اختبارية

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

curl -X  POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp", "to": "16315555555","text": {"body" : "hello world!"}}'

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

عينة من الاستجابة:

{
  "id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}

متابعة التحديثات الشهرية

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

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

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

الأسئلة المتكررة حول التنفيذ التقني

What is the architecture of the Cloud API?

The Cloud API architecture significantly simplifies the Solution Partner's operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings). For details, refer to the architecture diagram comparing the On-Premises and Cloud API deployments.

الرابط الثابت

الأسئلة المتكررة حول خصوصية البيانات والأمان

الأسئلة المتكررة حول الامتثال التنظيمي