Threadwire by TriTech

→ مرجع الـ API

WhatsApp OTP

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

1. الرابط (موصى به): الشخص يرسل إليك الرمز

لا يُرسل شيء إلى من لم يكتب أولًا، فرقمك يرد فقط: وهذه أكثر الرسائل أمانًا، بلا حد يومي ولا ساعات ليل ولا انتظار.

POST /v1/otps
{"instance_id": "01K…", "channel": "link", "brand": "Acme", "reference": "signup-7", "locale": "en"}

201 {"data": {"id": "01K…", "channel": "link", "status": "pending", "code": "48291376",
  "link": "https://wa.me/201000000001?text=My%20Acme%20verification%20code%3A%2048291376",
  "qr": "data:image/png;base64,…", "expires_at": "2026-10-04T12:10:00+00:00", "…": "…"}}
  1. اعرض link كزر على الهاتف، أو صورة qr على الكمبيوتر، مع code كبديل يمكن للشخص كتابته.
  2. يرسل الشخص الرسالة. وحين تصل إلى رقمك قبل expires_at يصبح الـ OTP verified.
  3. يأتيك ويب هوك otp.completed ومعه phone: الرقم الذي أرسل الرسالة، وهو ما تسجّل دخول الشخص به.

من المفيد أن تعرف:

  • أضف phone إلى الطلب كلما عرفته، ليُقبل الرمز من ذلك الهاتف فقط. من دونه يُتحقق من أي شخص يرسل الرمز، فقد يعيد أحدهم توجيه رابطك إلى شخص آخر.
  • ضع اسم تطبيقك في brand: يظهر في النص الذي يرسله الشخص («My Acme verification code: …») وفي الرد، فيوضّح الرابط المعاد توجيهه ما الذي يُسجَّل الدخول إليه.
  • code موجود في هذا الرد فقط؛ احتفظ به في صفحتك، لا في سجل. ويمكن كتابته بمسافات أو شرطات أو بالأرقام العربية المشرقية.
  • يرد رقمك برسالة قصيرة «✅ Verified for Acme. You can go back to the app.» بلغة الشخص (locale en أو ar)، كرد. وتصلك رسالة الشخص كذلك كحدث message.received مع إخفاء أرقام الرمز، ولا يُرد عليها برد تلقائي.
  • نادرًا يخفي واتساب رقم المرسل (معرّف خاص): الـ OTP المنشأ بلا phone يكتمل مع ذلك، ويكون phone بقيمة null. لا تسجّل دخول أحد أبدًا بهاتف قيمته null.

2. الرمز: رقمك يرسله

POST /v1/otps
{"instance_id": "01K…", "channel": "code", "phone": "201012345678", "brand": "Acme", "code_length": 6}

يرد بـ 202 مع status: "pending" (ولا يعيد الرمز أبدًا)، ويستلم الشخص «Acme code: 482913. It expires in 10 minutes. Never share it.» (أو نصها العربي، مع locale: "ar").

تحقق مما يكتبه الشخص عبر POST /v1/otps/{id}/check و{"code": "482913"}: الرد 200 مع status: "verified"، أو 422 مع attempts_left. خامس رمز خاطئ يُفشل الـ OTP. والـ OTP المنتهي أو الفاشل أو الملغى أو الذي تم التحقق منه بالفعل يرد بـ 409 مع status الخاص به.

الرمز رسالة مثل أي رسالة أخرى. لمن لم يكتب للرقم من قبل هو رسالة أولى: يُحسب ضمن حد الأشخاص الجدد لليوم وضمن الإحماء، ولا يُرسل ليلًا ولا أثناء تقييد واتساب للرقم. ولأن الرمز المتأخر لا فائدة منه، فهو لا يبقى في الانتظار أبدًا. إن تعذّر إرساله خلال دقيقتين تقريبًا، يفشل الـ OTP فورًا والسبب في failed_reason، مع ويب هوك otp.failed. ولهذا كان الرابط أفضل: فهو يعمل دائمًا. ومن يستلمون رمزًا ولا يردون أبدًا يُحسبون أيضًا على معدل ردود الرقم.

إدارة الـ OTP

  • GET /v1/otps/{id}: status (pending، verified، failed، expired، cancelled)، phone، verified_phone، reference، attempts_left، sends، failed_reason، expires_at، verified_at. يكون verified_phone بقيمة null إذا أخفى واتساب رقم المرسل. ولا يعيد الرمز أبدًا.
  • POST /v1/otps/{id}/resend: رمز جديد (ويتوقف القديم عن العمل) ومدة expires_in جديدة، ما دام الـ OTP قيد الانتظار وبعد خروج الرمز الأخير (409 ما دام في طريقه). المحاولات الخاطئة تظل محسوبة، وتنطبق حدود الهاتف الواحد المذكورة أدناه (429 مع Retry-After)، وبحد أقصى 5 رموز لكل OTP.
  • DELETE /v1/otps/{id}: يلغي OTP قيد الانتظار؛ والرمز الذي لم يُرسل بعد لا يُرسل.
  • في لوحة التحكم، صفحة رمز التحقق (OTP) (في القائمة، للمسؤولين) تعرض كل عمليات OTP، مع التصفية حسب الحالة والطريقة والرقم، وتلغي ما كان قيد الانتظار. وزر جرّبها فيها ينشئ رابطًا تكمله من هاتفك.

الخيارات والحدود

  • expires_in من 1 إلى 30 دقيقة (10 افتراضيًا)، وcode_length من 4 إلى 8 أرقام (6)، وbrand حتى 30 حرفًا (حروف ومسافات و& ' . -؛ بلا أرقام، وبلا عنوان موقع، وليس «WhatsApp» أو «Meta»). الرموز من 6 أرقام أو أكثر أكثر أمانًا: مع 4 أرقام، خمس تخمينات لكل رمز من عشرة رموز في اليوم تمنح الغريب فرصة واحدة تقريبًا من كل 200.
  • يستلم الهاتف الواحد من حسابك رمزًا واحدًا في الدقيقة على الأكثر، و3 في الساعة و10 في اليوم (429 مع Retry-After). ومن لم يكتب للرقم من قبل يستلم 3 في اليوم على الأكثر (الرسالة الأولى واثنتان بعدها)، ولا شيء في يوم لاحق قبل مرور 7 أيام على آخر رمز. طريقة الرابط ليس لها حد كهذا. ويمكن لحسابك بدء 30 عملية OTP في الدقيقة.
  • الرمز يستهلك رسالة واحدة من رسائل باقتك؛ والرابط يستهلك رسالة واحدة لتأكيده فقط، ويُتخطى التأكيد إن لم يبقَ في الباقة متسع.

الأمان

الرموز عشوائية، وتُخزَّن فقط على هيئة هاش بمفتاح، وتُقارن في زمن ثابت، ولا تُعاد أبدًا بعد رد الرابط نفسه. البدء والتحقق يحتاجان مفتاحًا يُسمح له بالإرسال؛ والقراءة تحتاج مفتاحًا يُسمح له بالقراءة؛ والمفتاح الخاص برقم واحد يصل إلى عمليات OTP لذلك الرقم فقط. أرسل ترويسة Idempotency-Key: إعادة المحاولة تعيد أول OTP (بلا رمزه؛ ابدأ واحدًا جديدًا إن فقدته). تُحفظ عمليات OTP لمدة 30 يومًا.