قوالب المصادقة في WhatsApp: كيفية إرسال رموز OTP عبر WhatsApp

الخلاصة: قوالب المصادقة هي الفئة المخصصة لرموز OTP ورموز التحقق ضمن WhatsApp Business Platform. يحدد WhatsApp نص الرسالة، ولا تقدّم سوى الرمز، وتختار زر OTP (نسخ الرمز، أو الملء التلقائي بنقرة واحدة، أو دون أي نقرة). تتم الموافقة عليها عادةً بشكل شبه فوري، ونادرًا ما يتم إيقافها مؤقتًا، ولا تُحتسب رسومها إلا عند تسليمها. يشرح هذا الدليل اختلافها عن القوالب الأخرى، ومتى تستخدمها، وكيفية إنشائها وإرسالها (من لوحة التحكم ومن خلال API)، والفرق بين انتهاء صلاحية الرمز ومدة صلاحية الرسالة (TTL)، وأفضل الممارسات التي تمنع معظم المشكلات في بيئة الإنتاج.

مقدمة

إذا كان تطبيقك يرسل رموز OTP عبر الرسائل النصية القصيرة، فأنت تعرف بالفعل ما يسببه ذلك من مشكلات: ارتفاع التكاليف، وتأخر الرسائل أو تصفيتها، ومستخدمون لا تصلهم الرموز أبدًا. تتيح لك قوالب المصادقة على WhatsApp خيارًا آخر. تصل الرموز عبر تطبيق يتفقده الأشخاص باستمرار، وعلى Android يمكنك توفير الملء التلقائي بنقرة واحدة، ليُدرج الرمز مباشرةً في تطبيقك.

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

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

قوالب المصادقة هي إحدى فئات القوالب الثلاث على WhatsApp Business Platform، إلى جانب قوالب التسويق والخدمات. وهي مخصصة لغرض واحد: إرسال كلمات المرور لمرة واحدة ورموز التحقق لتأكيد هوية المستخدم.

ما يميزها:

• محتواها موحّد. لا يمكنك كتابة نص مخصص للمتن. ينشئ WhatsApp النص بلغة القالب («{{1}} هو رمز التحقق الخاص بك»)، ولا تقدّم سوى الرمز.
• تتطلب زر OTP. يجب استخدام زر نسخ الرمز أو الملء التلقائي بنقرة واحدة، أو خيار دون أي نقرة الذي لا يعرض زرًا مرئيًا. وتتوفر أنواع الأزرار هذه في هذه الفئة وحدها.
• نص انتهاء الصلاحية اختياري. يمكنك إضافة تذييل مثل «تنتهي صلاحية هذا الرمز خلال 5 دقائق».
• تتم الموافقة عليها عادةً بشكل فوري، لأن محتواها محدد مسبقًا وغير ترويجي. وتشير Meta أيضًا إلى أن قوالب المصادقة التي تتضمن أزرار OTP أقل عرضة بكثير للإيقاف المؤقت مقارنةً بالفئات الأخرى.

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

ما يراه المستخدم:

482913 هو رمز التحقق الخاص بك. حرصًا على أمانك، لا تشارك هذا الرمز.

تنتهي صلاحية هذا الرمز خلال 5 دقائق.

[ نسخ الرمز ]

أنواع الأزرار: نسخ الرمز مقابل الملء التلقائي بنقرة واحدة مقابل دون أي نقرة

سلوك الرجوع إلى الخيار البديل مهم. يتطلب قالب الملء التلقائي بنقرة واحدة أو دون أي نقرة منك تحديد تسمية زر نسخ الرمز أيضًا. إذا تعذر على Meta التحقق من عملية المصادقة للملء التلقائي (مثلًا، إذا لم يكن التطبيق مثبتًا)، فستعرض الرسالة زر نسخ الرمز بدلًا منه. لذا لا تنشئ زرين منفصلين لـ«الملء التلقائي ونسخ الرمز»: يتضمن القالب زر OTP واحدًا، وخيار نسخ الرمز البديل مدمج فيه.

ملاحظة حول iPhone. الملء التلقائي بنقرة واحدة وخيار دون أي نقرة هما ميزتان في Android. وفي سياق منفصل، توضح وثائق Meta أنه اعتبارًا من 15 يونيو 2026، على iOS 26 والإصدارات الأحدث، توفر اقتراحات لوحة المفاتيح الملء التلقائي الأصلي لرمز OTP من إشعار الدفع، دون الحاجة إلى أي تكامل من جانبك.

نبذة عن قيمة التجزئة للتوقيع. لاستخدام الملء التلقائي بنقرة واحدة أو خيار دون أي نقرة، عليك تقديم اسم حزمة تطبيقك على Android وقيمة تجزئة للتوقيع من 11 حرفًا، مشتقة من شهادة توقيع تطبيقك. عدم التطابق هو السبب الأكثر شيوعًا لعودة الملء التلقائي بصمت إلى خيار نسخ الرمز، لذا اختبر على جهاز فعلي قبل الإطلاق. تسهّل حزمة OTP Android SDK من Meta عملية المصادقة، ويُنصح باستخدامها.

متى تستخدم قوالب المصادقة

استخدمها لرموز التحقق فقط:

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

متى لا ينبغي استخدامها

قوالب المصادقة مخصصة حصريًا للرموز. واستخدامها لأي غرض آخر يؤدي إلى رفض القوالب أو إعادة تصنيفها:

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

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

المتطلبات والقيود

بالنسبة إلى النشاط التجاري

• حساب WhatsApp Business نشط على منصة WhatsApp Business، ويمكن الحصول عليه عبر مزودين مثل Chakra.
• لا يتطلب النسخ بنقرة واحدة أو التعبئة بنقرة واحدة موافقة خاصة. أما Zero-tap فيتطلب قبول شروط Meta الخاصة به عند إنشاء القالب.

بالنسبة إلى القالب

• نص المتن ثابت. لا يمكن إضافة نص مخصص أو متغيرات إضافية تتجاوز الرمز.
• زر OTP واحد بالضبط.
• نص تسمية الزر: 25 حرفًا كحد أقصى.
• قيمة التوقيع (في حالتي One-tap وZero-tap): 11 حرفًا بالضبط.
• انتهاء صلاحية الرمز (اختياري): من 1 إلى 90 دقيقة.
• استخدم رموزًا بالطول المعتاد، من 4 إلى 8 أرقام، وهو ما صُممت عمليات التعبئة التلقائية لتناسبه.

بالنسبة إلى المستلم

• يجب أن يكون الرقم مرتبطًا بحساب WhatsApp نشط. إذا لم يكن كذلك، فسيفشل التسليم (وسيظهر لك الخطأ 131026)، لذا يُعد إرسال رسالة SMS احتياطية خيارًا منطقيًا للتدفقات المهمة.
• وفقًا لوثائق Meta، لا تُسلَّم رسائل المصادقة إلا إلى جهاز WhatsApp الأساسي للمستخدم.
• تتطلب التعبئة التلقائية بنقرة واحدة أيضًا تثبيت تطبيقك على جهاز Android.

كيفية إنشاء قالب مصادقة

الخيار 1: من لوحة تحكم Chakra

تتيح لك إدارة القوالب في Chakra إنشاء قوالب ضمن جميع الفئات، بما فيها Authentication، مع تولي إرسالها إلى Meta ومزامنة حالة الموافقة نيابةً عنك.

1. افتح إدارة القوالب وأنشئ قالبًا جديدًا.
2. اختر فئة Authentication .
3. أدخل اسم القالب (أحرف إنجليزية صغيرة وأرقام وشرطات سفلية) وحدد لغته.
4. اختر نوع الزر: نسخ الرمز أو التعبئة التلقائية بنقرة واحدة.
5. لخيار التعبئة بنقرة واحدة، أدخل اسم حزمة Android وقيمة التوقيع.
6. فعّل توصية الأمان («لأمانك، لا تشارك هذا الرمز») أو أوقفها.
7. حدد مدة صلاحية الرمز (من المعتاد أن تكون من 5 إلى 10 دقائق لتدفقات تسجيل الدخول).
8. أرسل القالب. عادةً ما تتم الموافقة فورًا.

الخيار 2: عبر API

أنشئ قالبًا لنسخ الرمز:

json

POST https://graph.facebook.com/v{version}/{WABA_ID}/message_templates

{
"name": "login_otp_copy_code",
"language": "en_US",
"category": "AUTHENTICATION",
"message_send_ttl_seconds": 300,
"components": [
{ "type": "BODY", "add_security_recommendation": true },
{ "type": "FOOTER", "code_expiration_minutes": 5 },
{
"type": "BUTTONS",
"buttons": [
{ "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy Code" }
]
}
]
}

أنشئ قالبًا للتعبئة التلقائية بنقرة واحدة (تسمية نسخ الرمز هي الخيار الاحتياطي المضمن):

json

{
"name": "login_otp_autofill",
"language": "en_US",
"category": "AUTHENTICATION",
"message_send_ttl_seconds": 300,
"components": [
{ "type": "BODY", "add_security_recommendation": true },
{ "type": "FOOTER", "code_expiration_minutes": 5 },
{
"type": "BUTTONS",
"buttons": [
{
"type": "OTP",
"otp_type": "ONE_TAP",
"text": "Copy Code",
"autofill_text": "Autofill",
"package_name": "com.yourcompany.app",
"signature_hash": "K8a/AINcGX7"
}
]
}
]
}

مرجع الحقول

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

إرسال الرمز

باستخدام SDK الخاص بـ Chakra

يتضمن SDK الخاص بـ Chakra والمكتوب بلغة TypeScript وسيطًا لـ OTP، لذا لن تحتاج إلى تجميع المكونات يدويًا:

javascript

await client.whatsapp.templateMessages.send({
pluginId: "YOUR_PLUGIN_ID",
toPhoneNumber: "919999999999",
whatsappPhoneNumberId: "YOUR_PHONE_NUMBER_ID",
templateName: "login_otp",
otpCode: "496093",
});

ينبغي أن تتضمن أرقام الهواتف رمز البلد من دون + أو رموز تنسيق.

باستخدام نقطة النهاية بتنسيق Meta

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

bash

curl --request POST \
'https://api.chakrahq.com/v1/ext/plugin/whatsapp/{pluginId}/api/v19.0/{whatsappPhoneNumberId}/messages' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919999999999",
"type": "template",
"template": {
"name": "login_otp",
"language": { "code": "en_US" },
"components": [
{
"type": "body",
"parameters": [ { "type": "text", "text": "482913" } ]
},
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [ { "type": "text", "text": "482913" } ]
}
]
}
}'

يُعدّ إغفال معامل الزر سببًا شائعًا لفشل إرسال رموز OTP. استخدم إصدارًا حديثًا من Graph API في عنوان URL، وراجع مرجع API الخاص بـ Chakra لمعرفة تفاصيل المصادقة والطلب.

انتهاء صلاحية الرمز ومدة صلاحية الرسالة إعدادان مختلفان

من السهل الخلط بين هذين الإعدادين:

• code_expiration_minutes يتحكم في النص الذي يظهر للمستخدم ("تنتهي صلاحية هذا الرمز خلال X دقائق"). وهو يوضح مدة صلاحية الرمز.
• message_send_ttl_seconds يتحكم في المدة التي تواصل Meta خلالها محاولة تسليم الرسالة. القيمة الافتراضية لقوالب المصادقة هي 10 دقائق، ويمكنك تقصيرها. إذا لم يتم التسليم خلال هذه المدة، تحذف Meta الرسالة، ولا تُفرض رسوم على الرسائل التي لم يتم تسليمها.

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

مسار OTP الكامل من البداية إلى النهاية

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

الأسعار

• تُحتسب رسوم رسائل المصادقة لكل رسالة تم تسليمها، وفق سعر المصادقة في بلد المستلِم (Cتحقّق من الأسعار حسب البلد). وتُطبّق في بعض الأسواق أيضًا تعرفة منفصلة للمصادقة الدولية على الأنشطة التجارية المؤهلة.
• لا تُفرض رسوم على الرسائل التي لم يتم تسليمها، بما فيها الرسائل التي تُحذف بعد انتهاء مدة TTL.
• تختلف الأسعار حسب البلد وتتغير بمرور الوقت، لذا راجع أحدث قائمة أسعار لدى Meta قبل إعداد التوقعات.
• لا تضيف Chakra أي هامش ربح على رسائل القوالب: فأنت تدفع السعر المعمول به لدى Meta مقابل الرسائل التي تم تسليمها بنجاح.

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

• ابدأ بخيار نسخ الرمز. فهو يعمل مع جميع المستخدمين. أضف خيار النقرة الواحدة فقط إذا كان لديك تطبيق Android ويمكنك الحفاظ على رمز التوقيع.
• اجعل مدة الصلاحية قصيرة، عادةً من 5 إلى 10 دقائق، واضبط مدة TTL بما يتوافق معها.
• أضف خيارًا احتياطيًا عبر SMS للمستلمين الذين لا يمكنهم تلقي رسائل WhatsApp (131026)، وللرسائل التي لا تتلقى تأكيدًا بالتسليم خلال مدة TTL.
• حدّد معدل طلبات OTP على خادمك، مع فترات انتظار بين عمليات إعادة الإرسال، لمنع إساءة الاستخدام والرسائل المزعجة غير المقصودة. واحسب أيضًا حدود معدل API عند ذروة حركة المرور (تفرض Chakra حدًا قدره 200 مكالمة في الدقيقة).
• أنشئ نسخة بكل لغة تقدم بها الخدمة، ويفضّل استخدام اسم القالب نفسه.
• راقب إشعارات ويب هوك للحالة (تم الإرسال، وتم التسليم، وتمت القراءة، وفشل) لاكتشاف مشكلات قابلية التسليم مبكرًا.
• لا تستخدم قوالب المصادقة مطلقًا لمحتوى لا يتعلق برموز OTP. فهذا أسرع طريق إلى إعادة تصنيف القالب.
• اختبر التعبئة التلقائية على جهاز Android حقيقي قبل الإطلاق. فمشكلات رمز التوقيع لا تظهر إلا هناك.

الأسئلة الشائعة

هل يمكنني تخصيص نص الرسالة في قالب المصادقة؟ لا. نص الرسالة موحّد. خياراتك النصية الوحيدة هي إخلاء المسؤولية الأمني، وسطر انتهاء الصلاحية، وتسميات الأزرار.

هل تحتاج قوالب المصادقة إلى موافقة؟ تمر بعملية الإرسال المعتادة، ولكن نظرًا إلى أن محتواها محدد مسبقًا، تتم الموافقة عليها عادةً على الفور تقريبًا.

ماذا يحدث إذا أرسلت رمز OTP ضمن قالب Utility؟ تكتشف Meta محتوى OTP وتعيد تصنيفه كمصادقة أو ترفضه. استخدم الفئة الصحيحة منذ البداية.

هل تعمل التعبئة التلقائية بنقرة واحدة على iPhone؟ لا. ميزتا النقرة الواحدة وعدم النقر من ميزات Android. أما مستخدمو iPhone فيستخدمون مسار نسخ الرمز، وعلى iOS 26 والإصدارات الأحدث، تقول Meta إن اقتراحات لوحة المفاتيح يمكنها تعبئة الرمز تلقائيًا من الإشعار باستخدام ميزة النظام.

هل يمكنني إرسال القالب نفسه بلغات متعددة؟ نعم. يمكن أن يكون لكل اسم قالب إصدار منفصل معتمد لكل لغة، ويمكنك اختيار رمز اللغة عند الإرسال.

ما طول الرمز الممكن؟ التزم بـ 4 إلى 8 أرقام، وهو المعيار الذي صُممت حوله تدفقات التعبئة التلقائية.

ختامًا

تُعدّ قوالب المصادقة من أبسط الفئات التي يمكن إعدادها على نحو صحيح: محتوى ثابت، وموافقة فورية، وزر OTP يناسب منصتك. إذا كنت تطوّر تدفقات تسجيل الدخول أو إنشاء الحساب أو المصادقة الثنائية، فمن الجدير إضافتها إلى جانب SMS، أو اعتمادها قناة OTP أساسية إذا كان مستخدموك يتواصلون بالفعل عبر WhatsApp. للاطلاع على المرجع الكامل للقوالب والإرسال، راجع وثائق Meta لقوالب المصادقة و وثائق API الخاصة بـ Chakra.