التحقق: رموز OTP عبر SMS وواتساب والمكالمات والبريد
أثبت أن الشخص يملك رقم الهاتف. الرموز عشوائية، تُستخدم مرة واحدة، تنتهي صلاحيتها، ولا تُعرض لك أو تُحفظ بشكل مقروء.
- sms
- رمز برسالة قصيرة من هاتفك.
- يرسل Echo الرمز بالبريد من أحد حسابات بريدك؛ يكتبه الشخص.
- رمز عبر واتساب من رقمك المربوط.
- phone_call
- يتصل Echo بالرقم ويُنهي المكالمة عند الرنين؛ يكتب الشخص الرقم الذي اتصل.
- missed_call
- يتصل الشخص بهاتفك؛ لا رمز لكتابته.
البدء
POST /v1/echo/verificationsالقناة اختيارية. بدونها يختار Echo أول طريقة يستخدمها تطبيقك ويستطيع تقديمها: البريد الإلكتروني إذا كان to عنواناً؛ وإلا واتساب، ثم SMS، ثم مكالمة هاتفية، ثم مكالمة فائتة. وإذا لم تكن أي منها ممكنة فالرد 409 no_method_available.
تحقق من الرمز
POST /v1/echo/verifications/VERIFICATION_ID/checkمكالمة هاتفية: يتصل Echo بالشخص
مع القناة phone_call يتصل Echo بالرقم من إحدى شرائحك ويُنهي المكالمة فور الرنين. يكتب الشخص الرقم الذي اتصل به؛ أرسله إلى /check كقيمة code (الرقم كاملاً أو آخر 6 أرقام منه فأكثر؛ المسافات و+ وصفر البداية مقبولة). محاولتان خاطئتان فقط. لا تُعيد الواجهة هذا الرقم أبداً. تعتمد قوة الطريقة على عدد الأرقام المختلفة التي يستطيع Echo الاتصال منها، لذلك لا تُقبل وحدها (جلسة طريقتها الوحيدة phone_call أو رمز واحد) إلا إذا كان 20 رقماً مختلفاً على الأقل يستطيع الاتصال بتلك الوجهة؛ وإلا فاجمعها مع sms أو whatsapp أو missed_call.
POST /v1/echo/verifications/VERIFICATION_ID/checkالتحقق بمكالمة فائتة
مع missed_call، اعرض للشخص الرقم الموجود في call_to واطلب منه الاتصال به. يرى هاتفك المكالمة، يُنهيها، وتصبح عملية التحقق مقبولة. استعلم عنها أو انتظر الـ webhook.
- خمسة رموز خاطئة تُنهي عملية التحقق (رقمان خاطئان في المكالمة الهاتفية).
- البدء مجدداً للرقم نفسه يرسل رمزاً جديداً (5 مرات كحد أقصى).
- تنتهي صلاحية الرمز بعد المدة المحددة لتطبيقك (10 دقائق افتراضياً).
- كل رمز يقول السطر نفسه، أياً كان من يرسله: Your OTP is 123456، بالإنجليزية ما لم تطلب locale بقيمة ar أو tr (العربية أو التركية). لا يمكن إضافة أي شيء إليه، حتى اسم علامة تجارية.
عدة طرق، عميل واحد
أرسل methods (مع email و/أو phone) بدلاً من channel و to. يردّ Echo برابط: يفتحه العميل في صفحة Echo نفسها، ويطلب كل رمز بدوره ويكتبه. require يحدد كم طريقة يجب التحقق منها، من 1 حتى جميعها.
POST /v1/echo/verifications- لا يُرسل شيء عند إنشاء الجلسة. يضغط العميل على «احصل على الرمز» لكل طريقة، واحدة تلو الأخرى، مثل التحقق الأمني.
- كل الطرق مطلوبة: تُنجز بالترتيب واحدة تلو الأخرى. عدد أقل مطلوب: يختار العميل أيّها.
- لكل طريقة انتظار 60 ثانية بين الرموز وبحد أقصى 3 رموز. تدوم الجلسة 30 دقيقة.
- كل رمز هو عملية تحقق: يكلّف ما يكلّفه رمز، مع أجهزة تطبيقك ومفاتيحه وأجهزة Echo كأي رمز. ويقول الرمز السطر الثابت نفسه (locale بقيمة en أو ar أو tr).
- لا يكتب العميل أبداً بريداً إلكترونياً أو رقماً: أنت تعطيها عند إنشاء الجلسة، ويعرضها Echo مخفية جزئياً.
- يُرسل echo.verification.approved عند اعتماد الجلسة. و return_url الاختياري (https) يضيف زر «متابعة» في النهاية.
لبناء صفحتك الخاصة بدلاً من ذلك: GET للجلسة، ثم POST إلى /send مع method و POST إلى /check مع method والرمز (يمكن حذف method إذا كانت الجلسة بطريقة واحدة).
POST /v1/echo/verifications/VERIFICATION_ID/sendتضمين الصفحة واستبدال الإثبات
لعرض صفحة العميل داخل صفحتك، مرّر embed_origin (أصل صفحتك، https أو http على localhost) عند إنشاء الجلسة، وافتح الرابط مع ?embed=1 (وأضف &theme=dark لصفحة داكنة). وحده هذا الأصل يستطيع تضمينها، ووحده يتلقى النتيجة.
- تخبر الصفحة المضمَّنة صفحتك بما يحدث عبر postMessage، ومعها دائماً source: "echo": ارتفاعها ({type: "resize", height}) والنتيجة ({type: "verified", proof}) أو انتهاء الجلسة ({type: "ended"}) وإغلاق العميل لها ({type: "closed"}). تحقّق أن event.origin هو أصل Echo.
- يسلّم خادمك الإثبات عبر POST /v1/echo/verifications/redeem مع proof: فيعود valid: true والطرق التي تم التحقق منها ومرجعك. يعمل الإثبات مرة واحدة، ولتطبيقك أنت فقط، ولجلسة معتمدة فقط.
- المرجع reference (حتى 800 حرف) ملاحظتك الخاصة: يحفظه Echo مختوماً، ولا يعرضه للعميل أبداً، ويعيده مرة واحدة عند الاستبدال ثم يمحوه.
- skip_unavailable: true يطلب كل ما تريد ويستبعد ما لا يستطيع تطبيقك تقديمه (يجب أن تبقى طريقة واحدة على الأقل). decoy: true ينشئ جلسة تبدو حقيقية لكنها لا ترسل شيئاً ولا تكلّف شيئاً ولا تنجح أبداً، لاسم غير موجود، فلا تكشف الشاشة شيئاً.
POST /v1/echo/verifications/redeem