أرقام الهواتف التي تم التحقق منها مسبقًا

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

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

المتطلبات

• يجب أن يكون نشاطك التجاري شريك حلول معتمدًا.
• يجب أن يكون مستخدم التطبيق مسؤول مدير أعمال في حساب الأعمال الذي تتم إضافة أرقام هواتف النشاط التجاري التي تم التحقق منها إليه.
• مستخدم أو رمز وصول مستخدم النظام.
• الإذن business_management.
• يجب أن تكون أرقام هواتف النشاط التجاري صالحة.

التقييدات

• لا تتوفر إلا من خلال دفق التسجيل المُضمن الجديد. راجع مستند دفق تضمين التسجيل للتعرف على كيفية تمكين الدفق الجديد.
• أنت مسؤول عن تتبع أي شخص يطالب برقم هاتف النشاط التجاري الذي تم التحقق منه مسبقًا.
• إذا لم يطالب العميل النهائي برقم هاتف النشاط التجاري الذي تم التحقق منه مسبقًا في دفق التسجيل المُضمن خلال 90 يومًا من التحقق، فستتغير حالة الرقم إلى "غير مثبّت" ويجب التحقق منه مرة أخرى لاستعادة الحالة لمدة 90 يومًا أخرى.
• لا يمكن إعادة التحقق من أرقام هواتف الأعمال التي لم يتم التحقق منها مسبقًا إلا بعد 45 يومًا قبل جدولتها للعودة إلى حالة "غير مثبّت". هذا الوقت موضح من قبل الحقل verification_expiry_time.
• إذا أضفت رقم هاتف إلى مجموعة أرقام الهواتف التي تم التحقق منها (الخطوة الأولى) ولكن لم تتحقق منه خلال 90 يومًا (الخطوة الثالثة)، فستتم إزالته من المجموعة وسيتعين عليك إضافته مرة أخرى.

إنشاء أرقام تم التحقق منها مسبقًا

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

الخطوة الأولى: إنشاء رقم هاتف نشاط تجاري تم التحقق منه مسبقًا

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

بنية الطلب

POST /<BUSINESS_ACCOUNT_ID>/add_phone_numbers
  ?phone_number=<PHONE_NUMBER>

الاستجابة

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

{
  "id": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>"
}

عينة من الطلب

curl -X POST 'https://graph.facebook.com/v19.0/506914307656634/add_phone_numbers?phone_number=15550783881' \
-H 'Authorization: Bearer EAAJB...'

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

{
  "id": "106540352242922"
}

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

الخطوة الثانية: طلب رمز تحقق

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

بنية الطلب

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/request_code
  ?code_method=<CODE_METHOD>
  &language=<LANGUAGE>

الاستجابة

عند نجاح العملية ستُرجع API القيمة true.

{
  "success": <SUCCESS>
}

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

بنية رسالة SMS لكلمة السر لمرة واحدة

WhatsApp code <CODE>

بنية الرسالة الصوتية لكلمة السر لمرة واحدة

يتم التكرار ثلاث مرات.

Verification code is <CODE>

عينة من الطلب

curl -X POST 'https://graph.facebook.com/v19.0/106540352242922/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

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

{
  "success": true
}

عينة من رسالة SMS كلمة السر لمرة واحدة

WhatsApp code 123-456

عينة من الرسالة الصوتية لكلمة السر لمرة واحدة

يتم التكرار ثلاث مرات.

Verification code is 123456

راجع مرجع نقطة النهاية رقم هاتف واتساب للأعمال الذي تم التحقق منه > طلب الرمز للتعرف على أساليب طلب الرمز واللغات ومعلمات الاستعلام المدعومة.

الخطوة الثالثة: التحقق من الرقم

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

بنية الطلب

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/verify_code
  ?code=<CODE>

الاستجابة

عند نجاح العملية، سترجع API القيمة true وسيتم تعيين code_verification_status لرقم هاتف النشاط التجاري على VERIFIED لمدة 90 يومًا.

{
  "success": <SUCCESS>
}

عينة من الطلب

curl -X POST 'https://graph.facebook.com/v19.0/106540352242922/verify_code?code=123456' \
-H 'Authorization: Bearer EAAJB...'

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

{
  "success": true
}

راجع مرجع نقطة النهاية رقم هاتف النشاط التجاري الذي تم التحقق منه > التحقق من الرمز للتعرف على معلمات الاستعلام المدعومة.

بمجرد الحصول على رقم هاتف النشاط التجاري الذي تم التحقق منه وتتغير حالته (أو مجموعة من تلك الأرقام)، يمكنك عرضه في دفق التسجيل المُضمن الجديد.

عرض الأرقام التي تم التحقق منها في التسجيل المُضمن

يمكنك عرض أرقام الهواتف التي تم التحقق منها مسبقًا في دفق التسجيل المُضمن الجديد عبر بيانات النموذج المحضر مسبقًا. لتنفيذ ذلك، أضف الكائن preVerifiedPhone بخاصية ids إلى الكائن setup وقم بتعيين معرفات أرقام هواتف النشاط التجاري التي تم التحقق منها مسبقًا كمصفوفة سلاسل على الخاصية ids:

{
  scope: '<SCOPE>',
  extras: {
    feature: '<FEATURE>',
    setup: {
      preVerifiedPhone: {
        ids: [<IDS>]
      }
    }
  }
}

على سبيل المثال:

{
  scope: 'business_management,whatsapp_business_management',
  extras: {
    feature: 'whatsapp_embedded_signup',
    version: 2,
    setup: {
	business: {
	  name: 'Acme Inc.',
	  email: 'johndoe@acme.com',
	  phone: {
	    code: 1,
	    number: '6505551234'
        },
	  website: 'https://www.acme.com',
        address: {
          streetAddress1: '1 Acme Way',
          city: 'Acme Town',
          state: 'CA',
          zipPostal: '94000',
          country: 'US'
        },
        timezone: 'UTC-08:00'
      },
      phone: {
        displayName: 'Acme Inc.',
        category: 'ENTERTAIN',
        description: 'Gears and widgets'
      },
      preVerifiedPhone: {
        ids: ['106540352242922','105954558954427']
      }
    }
  }
}

لاحظ أنه إذا لم تتم المطالبة برقم هاتف النشاط التجاري الذي تم التحقق منه مسبقًا وكان بالحالة VERIFIED خلال 90 يومًا من التحقق، فسيتم تعيين الحالة على UNVERIFIED ولكنه سيظل مرئيًا في دفق التسجيل المُضمن الجديد. إذا حاول العميل النهائي المطالبة برقم لم يتم التحقق منه، فيجب إكمال التحقق بمفرده، وهذا يعني أنه يجب عليه طلب كلمة سر لمرة واحدة منك.

لمنع التعرض لتجربة المستخدم غير السارة تلك، نوصي بتتبع عملية التحقق من الرقم وإعادة التحقق منه قبل أن يتغير إلى الحالة "غير مثبّت".

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

تحديد ما إذا تمت المطالبة بالرقم من خلال التسجيل المُضمن

راجع الحصول على معرفات أرقام الهواتف التي تمت المطالبة بها.

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

يمكنك إرسال طلب GET إلى نقطة النهاية حساب واتساب للأعمال > أرقام الهواتف والذي يُرجع أرقام هواتف واتساب للأعمال الموجودة في حساب واتساب للأعمال.

قم بتحليل الخاصية display_phone_number في كل كائن تم إرجاعها في المجموعة النتائج. إذا كان للكائن رقم هاتف معروض (مثال 16505551234) باعتباره القيمة display_phone_number، فقد تمت المطالبة به. انسخ قيمة الخاصية id للكائن، نظرًا إلى أن هذا هو معرف كائن رقم هاتف واتساب للأعمال الذي يمثل الآن هذا الرقم (لن يعمل المعرف القديم بعد الآن).

بدلاً من ذلك، يمكنك استخدام نقطة النهاية ذاتها مع ملحق field لطلب الحقل display_phone_number وتحديد رقم الهاتف المعروض. على سبيل المثال:

GET /102290129340398/phone_numbers?display_phone_number=16505551234

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

الحصول على أرقام هواتف النشاط التجاري التي تم التحقق منها مسبقًا

استخدم نقطة النهاية حساب الأعمال > الأرقام التي تم التحقق منها للحصول على قائمة بكل كائنات رقم هاتف واتساب للأعمال الذي تم التحقق منه، بغض النظر عن حالة التحقق في مجموعة حساب الأعمال لأرقام هواتف النشاط التجاري التي تم التحقق منها مسبقًا:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers

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

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers?code_verification_status=VERIFIED

مشاركة الأرقام التي تم التحقق منها مسبقًا وإلغاء مشاركتها

أرسل طلب POST إلى نقطة نهاية النشاط التجاري > مشاركة الأرقام التي تم التحقق منها مسبقًا لمشاركة أرقام هواتف الأنشطة التجارية التي تم التحقق منها مسبقًا مع شركاء الأعمال، أو أرسل طلب DELETE إلى نقطة النهاية نفسها لإلغاء مشاركة الأرقام.

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

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

مشاركة بنية الطلب

POST /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

إلغاء مشاركة بنية الطلب

DELETE /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

الاستجابة

عند نجاح العملية ستُرجع API القيمة true. في حالة المشاركة، أبلغ شريك الأعمال بالرقم الذي تم التحقق منه والذي تمت مشاركته حديثًا وزوده بمعرف الرقم. في حالة إلغاء المشاركة، لن يظهر الرقم بعد الآن في تنفيذ الشريك للتسجيل المضمن.

{
  "success": <SUCCESS>
}

مثال على طلب المشاركة

curl -X POST 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

مثال على طلب إلغاء المشاركة

curl -X DELETE 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

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

{
  "success": true
}

تسجيل الأرقام التي تم التحقق منها مسبقًا برمجيًا

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

بنية الطلب

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

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers

نص المنشور

{
  "preverified_id": "<PREVERIFIED_ID>",
  "country_dial_code": "<COUNTRY_DIAL_CODE>",
  "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
  "verified_name": "<VERIFIED_NAME>"
}

الخصائص

بنية الاستجابة

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

{
  "id": "<ID>"
}

خصائص الاستجابة

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

curl 'https://graph.facebook.com/v19.0/506914307656634/phone_numbers' \
-H 'Content-Type: text/plain' \
-H 'Authorization: Bearer EAAH7...' \
-d '
{
  "preverified_id": "6635066806614622",
  "country_dial_code": "1",
  "display_phone_number": "5550783881",
  "verified_name": "Lucky Shrub"
}'

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

{
  "id": "108692048990658"
}