إرسال رموز المرور لمرة واحدة عبر WhatsApp باستخدام واجهة Flowella البرمجية

ينشئ تطبيقك رمز مرور لمرة واحدة، ويرسله إلى WhatsApp الخاص بالعميل باستخدام واجهة Flowella البرمجية، ثم يتحقق من الرمز الذي يكتبه العميل. تستخدم الرسالة قالب مصادقة يحتوي على زر نسخ الرمز. دور HubSpot اختياري: يمكن لتطبيقك تسجيل النتيجة على جهة الاتصال.

لا يمكن لسير عمل في HubSpot إرسال رموز المرور. لا يمكن لإجراء Send WhatsApp Template من Flowella إعطاء زر OTP أو زر نسخ الرمز قيمة مختلفة لكل جهة اتصال، ولا ينبغي أن يحتفظ HubSpot بالرموز. أرسل الرموز من تطبيقك باستخدام الواجهة البرمجية بدلًا من ذلك.

نظرة سريعة

العنصر	التفاصيل
المُشغِّل	تسجيل دخول أو إجراء حساس في تطبيقك
Flowella	`POST /v1/templates/send` مع `buttonParameters` خاصة بكل مستلم
القالب	قالب مصادقة واحد يحتوي على زر نسخ الرمز (Authentication)
HubSpot	اختياري. يسجّل تطبيقك النتيجة على جهة الاتصال، وليس الرمز أبدًا
التوقيت	يُرسل الرمز فورًا. اسمح بإعادة الإرسال بعد 15 ثانية على الأقل

كيف يعمل

يوضح المخطط محاولة تسجيل دخول واحدة، من طلب الرمز حتى تسجيل الدخول أو القفل.

قبل أن تبدأ

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

إنشاء القالب

أنشئ القالب في WhatsApp Manager لدى Meta، بفئة Authentication وزر نسخ الرمز. لا يمكن أن تحمل رمز مرور لمرة واحدة إلا قوالب المصادقة، وهي تحتاج إلى زر نسخ الرمز أو زر النقرة الواحدة. تحدد Meta الصياغة: “<code> is your verification code.” يمكنك إضافة تذكير بعدم مشاركة الرمز وسطر لمدة الصلاحية من 1 إلى 90 دقيقة. لا يُسمح بعناوين URL والوسائط والرموز التعبيرية، ويمكن أن يصل طول الرمز إلى 15 حرفًا. بمجرد أن تعتمد Meta القالب، يظهر في Flowella. راجع إرشادات تصنيف القوالب وقوالب المصادقة بزر نسخ الرمز لدى Meta. إذا كنت تراسل العملاء أيضًا بشأن القفل، فاستخدم قالب Utility منفصلًا، مثل

Hi {{1}}, we have paused sign-in to your account after several incorrect codes. Try again in 30 minutes or contact our support team.

يناسب تنبيه أمان الحساب الخالي من أي ترويج فئة Utility.

إرسال رمز

اعثر على القالب والقناة

استدعِ GET /v1/templates?status=APPROVED. دوّن id وwabaId الخاصين بقالبك، وwhatsappChannelId للرقم الذي ترسل منه. راجع القنوات المتعددة إذا كان لديك عدة أرقام.

أنشئ الرمز في تطبيقك

أنشئ رمزًا عشوائيًا يصل طوله إلى 15 حرفًا. خزّن تجزئة له مع مدة صلاحية قصيرة، وعلّمه للاستخدام مرة واحدة.

أرسل الطلب

ضع الرمز مرتين: مرة كمعلمة في النص الأساسي ومرة كقيمة لزر نسخ الرمز. يتعامل تنسيق الإرسال لدى Meta مع زر نسخ الرمز كزر URL، لذا استخدم subType بالقيمة url، مع index بالقيمة 0 للزر الأول.

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY" \
  -H "Idempotency-Key: otp-7f3c2a91" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "1234567890123456",
    "templateWabaId": "102290129340398",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [
      {
        "phone": "+447700900123",
        "bodyParameters": ["482913"],
        "buttonParameters": [
          { "index": 0, "subType": "url", "text": "482913" }
        ]
      }
    ]
  }'

تعني الاستجابة 202 مع "status": "accepted" أن Flowella وضع الإرسال في قائمة الانتظار. ولا تؤكد التسليم.

تحقق من الرمز

عندما يكتب العميل الرمز، قارنه بالتجزئة المخزّنة. اقبله مرة واحدة فقط، وقبل انتهاء صلاحيته فقط.

تعامل مع إعادة الإرسال والقفل

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

سجّل النتيجة في HubSpot (اختياري)

اجعل تطبيقك يحدّث جهة الاتصال في HubSpot عبر واجهة HubSpot البرمجية، مثل Last WhatsApp verification (Date and time picker) وLast verification result (Dropdown select: Passed، Failed، Locked). يمكن لسير عمل في HubSpot بعد ذلك إنشاء مهمة عندما تكون النتيجة Locked. لا تخزّن الرموز في HubSpot أبدًا.

استخدم Idempotency-Key جديدًا لكل رمز، مثل معرّف التحقق الخاص بك. يؤدي التكرار بالمفتاح نفسه خلال 7 أيام إلى إرجاع id الأصلي دون إرسال أي شيء.

اختبار التكامل

أرسل رمزًا إلى رقم WhatsApp الخاص بك وتحقق من أن زر نسخ الرمز ينسخه.
أدخل رمزًا خاطئًا، ثم اطلب إعادة الإرسال بعد المهلة، وتحقق من أن الرمز القديم لم يعد يعمل.
راقب التسليم باستخدام أحداث webhook message.delivered وmessage.failed. راجع Webhooks.

استكشاف الأخطاء وإصلاحها

العَرَض	السبب	الحل
استجابة `401`	المفتاح مفقود أو غير صالح، أو استخدمت رمز وصول OAuth	استخدم مفتاح API صالحًا. راجع مفاتيح API.
استجابة `429`	تجاوزت حد المعدل	انتظر المدة المذكورة في ترويسة `Retry-After`، ثم أعد المحاولة.
لا تصل إعادة الإرسال أبدًا	أُرسلت خلال 15 ثانية من الرمز السابق، أو أعادت استخدام `Idempotency-Key`	انتظر 15 ثانية واستخدم مفتاحًا جديدًا.
لا يصل أي رمز لعميل معيّن	ألغى الرقم اشتراكه في الرسائل من رقم WhatsApp الخاص بك	يمكن للعميل إرسال `START` لإعادة الاشتراك. راجع إلغاء الاشتراكات.
يفشل الإرسال مع الرموز الطويلة	يتجاوز طول الرمز 15 حرفًا	استخدم رمزًا أقصر.

البدء

أساسيات

استخدام التطبيق

الإعدادات

إعداد Meta وWhatsApp

تكامل HubSpot

التدفقات والحملات

مرجع API

استكشاف الأخطاء

سجل التغييرات

إرسال رموز المرور لمرة واحدة عبر WhatsApp باستخدام واجهة Flowella البرمجية

نظرة سريعة

كيف يعمل

قبل أن تبدأ

إنشاء القالب

إرسال رمز

اختبار التكامل

استكشاف الأخطاء وإصلاحها

ذات صلة

​نظرة سريعة

​كيف يعمل

​قبل أن تبدأ

​إنشاء القالب

​إرسال رمز

​اختبار التكامل

​استكشاف الأخطاء وإصلاحها

​ذات صلة

نظرة سريعة

كيف يعمل

قبل أن تبدأ

إنشاء القالب

إرسال رمز

اختبار التكامل

استكشاف الأخطاء وإصلاحها

ذات صلة