Authentication-templates

OTP

قوالب المصادقة

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

تتكون قوالب المصادقة مما يلي:

• نص ثابت تم تعيينه مسبقًا: <VERIFICATION_CODE> هو رمز التحقق.

• إخلاء مسؤولية أمنية اختياري: لأغراض الأمان، لا تشارك هذا الرمز.

• تحذير انتهاء صلاحية اختياري: تنتهي صلاحية هذا الرمز في غضون <NUM_MINUTES> من الدقائق.

• زر الملء التلقائي بضغطة واحدة أو زر نسخ الرمز أو بدون زر على الإطلاق إذا كنت لا تستخدم أي ضغطات.

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

راجع الإرشادات الإضافية لمعرفة الوقت المناسب لاستخدام قالب مصادقة.

أمان الجهاز المرتبط

تحتوي قوالب المصادقة الآن على ميزة أمان الجهاز المرتبط. وهذا يعني أنه لا يتم عرض رسائل المصادقة إلا على جهاز واتساب الرئيسي للمستخدم.

يتم إخفاء رسائل المصادقة التي يتم إرسالها إلى الأجهزة المرتبطة لدى المستخدم من خلال مطالبة توجه المستخدم لعرض الرسالة على جهازه الأساسي.

يتم تمكين هذه الميزة بشكل افتراضي ولا تتطلب تغييرات في الرمز. كما يتعذر تكوينها أو تخصيصها. وتتوفر فقط في API السحابة.

قوالب مصادقة الملء التلقائي بضغطة واحدة

تتضمن قوالب المصادقة زر الملء التلقائي بضغطة واحدة.

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

راجع قوالب مصادقة الملء التلقائي بضغطة واحدة للتعرف على كيفية استخدامها.

قوالب مصادقة زر نسخ الرمز

تسمح لك قوالب مصادقة زر نسخ الرمز بإرسال كلمة سر لمرة واحدة أو رمز مع زر نسخ الرمز إلى المستخدمين.

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

راجع قوالب مصادقة زر نسخ لرمز للتعرف على كيفية استخدامها.

قوالب المصادقة بدون أي ضغطات

تسمح قوالب المصادقة بدون أي ضغطات للمستخدمين بتلقي كلمات سر لمرة واحدة أو الرموز عبر واتساب بدون الحاجة إلى الخروج من التطبيق.

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

راجع قوالب المصادقة بدون أي ضغطات للتعرف على كيفية استخدامها.

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

• تأكد من رقم هاتف المستخدم في واتساب قبل إرسال كلمة السر لمرة واحدة أو الرمز لذلك الرقم.

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

راجع أيضًا أفضل ممارسات مصادقة المستخدمين عبر واتساب.

تخصيص فترة الصلاحية

راجع تخصيص فترة الصلاحية.

إرسال رسائل قوالب المصادقة

استخدم API السحابة أو API داخل المواقع لإرسال قوالب المصادقة في رسالة قالب.

• إرسال رسائل قوالب المصادقة باستخدام API السحابة
• إرسال رسائل قوالب المصادقة باستخدام API داخل المواقع

معاينات القالب

يمكنك إنشاء معاينات لنصوص قوالب المصادقة بلغات مختلفة تتضمن سلسلة توصية الأمان وسلسلة انتهاء صلاحية الرمز أو تستبعدها باستخدام نقطة النهاية GET /<WABA_ID>/message_template_previews.

بنية الطلب

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_template_previews
  ?category=AUTHENTICATION,
  &language=<LANGUAGE>, // Optional
  &add_security_recommendation=<ADD_SECURITY_RECOMMENDATION>, // Optional
  &code_expiration_minutes=<CODE_EXPIRATION_MINUTES>, // Optional
  &button_types=<BUTTON_TYPES> // Optional

معلمات سلسلة الاستعلام

العنصر النائب	الوصف	مثال على القيمة
<LANGUAGE> قائمة مفصولة بفاصلة	اختياري. قائمة مفصولة بفاصلة تتضمن رموز اللغات والإعدادات المحلية لإصدارات اللغة التي تريد إرجاعها. إذا تم الحذف، فسيتم إرجاع إصدارات كل اللغات المدعومة.	en_US,es_ES
<ADD_SECURITY_RECOMMENDATION> Boolean (قيمة منطقية)	اختياري. يتم التعيين على true إذا أردت تضمين سلسلة نص توصية الأمان في الاستجابة. إذا تم الحذف، فلن يتم تضمين سلسلة توصية الأمان.	true
<CODE_EXPIRATION_MINUTES> Int64	اختياري. يتم التعيين على عدد صحيح إذا تم تضمين سلسلة تذييل انتهاء صلاحية الرمز في الاستجابة. إذا تم الحذف، فلن يتم تضمين سلسلة تذييل انتهاء صلاحية الرمز. تشير القيمة إلى عدد الدقائق المتبقية حتى انتهاء صلاحية الرمز. الحد الأدنى 1 والحد الأقصى 90.	10
<BUTTON_TYPES> قائمة سلاسل مفصولة بفاصلة	مطلوب. قائمة سلاسل مفصولة بفاصلة تشير إلى نوع الزر. إذا تم التضمين، فستتضمن الاستجابة نص الزر لكل زر في الاستجابة. بالنسبة إلى قوالب المصادقة، يجب أن تكون هذه القيمة OTP.	OTP

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

curl 'https://graph.facebook.com/v17.0/102290129340398/message_template_previews?category=AUTHENTICATION&languages=en_US,es_ES&add_security_recommendation=true&code_expiration_minutes=10&button_types=OTP' \
-H 'Authorization: Bearer EAAJB...'

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

{
  "data": [
    {
      "body": "*{{1}}* is your verification code. For your security, do not share this code.",
      "buttons": [
        {
          "autofill_text": "Autofill",
          "text": "Copy code"
        }
      ],
      "footer": "This code expires in 10 minutes.",
      "language": "en_US"
    },
    {
      "body": "Tu código de verificación es *{{1}}*. Por tu seguridad, no lo compartas.",
      "buttons": [
        {
          "autofill_text": "Autocompletar",
          "text": "Copiar código"
        }
      ],
      "footer": "Este código caduca en 10 minutos.",
      "language": "es_ES"
    }
  ]
}

الإدارة المجمّعة

استخدم نقطة النهاية POST /<WABA_ID>/upsert_message_templates لتحديث قوالب المصادقة أو إنشائها بشكل مجمّع بلغات متعددة والتي تتضمن تحذيرات الأمان وانتهاء الصلاحية الاختيارية أو تستبعدها.

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

بنية الطلب

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

نص المنشور

{
  "name": "<NAME>",
  "languages": [<LANGUAGES>],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": <ADD_SECURITY_RECOMMENDATION> // Optional
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": <CODE_EXPIRATION_MINUTES> // Optional
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "<OTP_TYPE>",
          "supported_apps": [
            {
              "package_name": "<PACKAGE_NAME>", // One-tap and zero-tap buttons only
              "signature_hash": "<SIGNATURE_HASH>" // One-tap and zero-tap buttons only
            }
          ]
        }
      ]
    }
  ]
}

الخصائص

كل خصائص إنشاء القالب مدعومة، مع الاستثناءات التالية:

• خاصية language غير مدعومة. بدلاً من ذلك، استخدم languages وقم بتعيين قيمتها على مصفوفة سلاسل رمز اللغة والإعداد المحلي. على سبيل المثال: ["en_US","es_ES","fr"].
• الخاصية text غير مدعومة.

• الخاصية autofill_text غير مدعومة.

مثال على طلب نسخ الرمز

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

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_copy_code_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 10
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE"
        }
      ]
    }
  ]
}'

مثال على طلب الملء التلقائي بضغطة واحدة

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

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_autofill_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 15
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ONE_TAP",
          "supported_apps": [
            {
              "package_name": "com.example.luckyshrub",
              "signature_hash": "K8a/AINcGX7"
            }
          ]
        }
      ]
    }
  ]
}'

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

{
  "data": [
    {
      "id": "954638012257287",
      "status": "APPROVED",
      "language": "en_US"
    },
    {
      "id": "969725527415202",
      "status": "APPROVED",
      "language": "es_ES"
    },
    {
      "id": "969725530748535",
      "status": "APPROVED",
      "language": "fr"
    }
  ]
}

عينة من التطبيق

راجع عينة تطبيق يحتوي على كلمة سر لمرة واحدة (OTP) في واتساب لنظام Android على Github. تعرض عينة التطبيق كيفية إرسال كلمات سر OTP والرموز وتلقيها عبر API وكيفية دمج أزرار الملء التلقائي بضغطة واحدة وأزرار نسخ الرمز وكيفية إنشاء قالب وكيفية تشغيل عينة من الخادم.

راجع أيضًا

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