إرسال رموز التحقق بأمان

واتساب قناة ممتازة لرموز الدخول والتحقق إذا أرسلتها بعناية، فالرقم المحظور لا يرسل شيئاً على الإطلاق.

الوصفة

curl -X POST "https://api.yasend.dev/v1/messages?async=true" \
  -H "Authorization: Bearer $YASEND_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: otp-$OTP_REQUEST_ID" \
  -d '{
    "sessionId": "'$SESSION_ID'",
    "to": "963912345678",
    "text": "Your Acme code is 482913. It expires in 5 minutes. Don'\''t share it.",
    "templateKey": "otp_login",
    "expiresInSeconds": 300
  }'

الإعداد	السبب
`?async=true`	لا تنتظر شاشة الدخول 3–10 ثوانٍ، ويرى المستخدم "أُرسل الرمز" فوراً
`templateKey`	يخبر YASend أن هذه رسالة قالب، فلا تُرفض نصوصها المتشابهة كرسائل مزعجة مكررة. استخدم مفتاحاً لكل قالب (`otp_login`، `otp_reset`…)
`expiresInSeconds`	الرمز الذي يصل بعد انتهاء صلاحيته لا فائدة منه. إذا كان الرقم يعيد الاتصال، تُلغى الرسالة عند انتهاء صلاحيتها وتصلك `message.failed` بالرمز `EXPIRED`، فتعرض الرسائل القصيرة أو "إعادة الإرسال"
`Idempotency-Key`	إذا انتهت مهلة طلبك وأعدت المحاولة، يصل المستخدمَ رمز واحد لا رمزان

استمع للويب هوك message.failed (الويب هوك)، أو استعلم دورياً عبر GET /v1/messages/{id}، لتنتقل إلى البديل بسرعة.

اكتب رموزاً تبدو كرموز

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

استخدم رقماً مُحمّى

الرقم المربوط حديثاً محدود في أسابيعه الأولى: 10 رسائل يومياً في أول يومين، ثم يزداد تدريجياً حتى 200 يومياً بعد شهر. ويحتاج إلى اسم وصورة في الملف الشخصي ومحادثة حقيقية واحدة على الأقل قبل فتح الإرسال الآلي. راجع الأمان والإحماء.

لرموز التحقق:

اربط الرقم قبل الإطلاق بوقت كافٍ؛
استخدمه كحساب عادي لبضعة أيام؛
في الباقة المتقدمة، أضف رقماً ثانياً احتياطياً.

احمِ نقطة النهاية لديك

حدّد عدد طلبات "أرسل لي رمزاً" لكل مستخدم ولكل عنوان IP في نظامك. وإلا يستطيع أي شخص أن يجعل رقمك يرسل مئات الرموز، فيستنفد حصتك ويضر بسمعة رقمك.

إذا واجه الرقم مشكلة

يراقب YASend صحة كل رقم.

رقم في خطر: إذا تراكمت أخطاء التسليم أو بدأ واتساب برفض الرسائل، يتوقف الإرسال بالرمز SESSION_AT_RISK لحماية الرقم.
التعافي: راجع GET /v1/sessions/{id}/health وخفّف الإرسال حتى يتعافى الرقم.
البديل: احتفظ ببديل عبر الرسائل القصيرة في كودك للرموز التي يجب أن تصل.