الدليل الشامل لإدارة دورة حياة الجلسات في Wawp

تعد إدارة الجلسات (Sessions) العمود الفقري لمنصة Wawp، وهي العملية التي يتم من خلالها ربط حساب واتساب حقيقي بنظامنا لتمكين الأتمتة وإرسال الرسائل. فهم دورة حياة الجلسة بشكل عميق هو ما يفرق بين نظام هش وخدمة احترافية تضمن استمرارية العمل بنسبة 99.9%.

المفهوم الجوهري للجلسات

في Wawp، لا نتعامل مع أرقام الهاتف بشكل مجرد، بل نتعامل مع "مثيلات" (Instances) أو جلسات معزولة. كل جلسة تعمل في بيئة تقنية مستقلة تماماً، مما يضمن أن نشاطك في جلسة واحدة لا يؤثر على الأخرى. هذا التصميم يمنح المطورين القدرة على إدارة مئات الحسابات بشكل متوازٍ وبأعلى معايير الأمان.

لماذا يعتبر نظام الجلسات الخاص بنا متفوقاً؟

1. العزل التام: كل جلسة تمتلك ملفات تعريف واتساب الخاصة بها ومخزن بيانات مستقل.
2. الاسترداد الآلي: يقوم نظامنا بمراقبة حالة الجلسات وإعادة تشغيل المحركات المعطلة تلقائياً في حالة حدوث خلل برمجي بسيط.
3. الشفافية: نوفر لك نقاط نهاية (Endpoints) تمنحك رؤية كاملة لما يحدث داخل المحرك في كل ثانية.

الحالات الكاملة للجلسة (Deep Dive into Statuses)

فهم الحالات ليس مجرد معرفة الاسم، بل معرفة "المنطق" وراء كل انتقال:

1. STOPPED (المحرك متوقف)

هذه هي حالة "السكون". الجلسة موجودة في قاعدة بياناتنا ولكن المحرك البرمجي المسؤول عن الاتصال بواتساب غير مفعل.

• متى تحدث؟: بعد إنشاء الجلسة مباشرة، أو بعد استدعاء أمر /stop يدوياً، أو في حالات نادرة عند حدوث فشل حرج متكرر.
• الإجراء: يجب استدعاء /v2/session/start لإيقاظ المحرك.

2. STARTING (قيد التشغيل)

هذه حالة انتقالية قصيرة (عادة 5-15 ثانية). في هذه المرحلة، نقوم بتجهيز الحاوية (Container)، تحميل ملفات التعريف، وبدء مصافحة الشبكة مع خوادم واتساب.

• نصيحة: لا تكرر استدعاء start في هذه المرحلة. انتظر حتى تتغير الحالة.

3. SCAN_QR_CODE (انتظار المصادقة)

المحرك يعمل ولكنه غير مرتبط بحساب واتساب. هو الآن يبث "تحدي" (Challenge) يحتاج لهاتفك لفك شفرته.

• الخيارات: يمكنك جلب رمز QR أو طلب رمز اقتران (Pairing Code) للهواتف التي تواجه مشاكل في الكاميرا.

4. WORKING (فعال وجاهز)

هذه هي حالة الهدف. الجلسة الآن متصلة بخوادم واتساب، تم تحميل جهات الاتصال، وهي جاهزة لاستقبال وإرسال أي نوع من الوسائط.

• الاستمرارية: طالما أن الهاتف متصل بالإنترنت ولم يقم المستخدم بتسجيل الخروج يدوياً، ستبقى الجلسة في هذه الحالة.

5. FAILED (فشل الاتصال)

حالة تحذيرية تعني أن المحرك واجه عقبة لا يمكنه تجاوزها تلقائياً (مثل انقطاع مفاجئ في خدمات واتساب العالمية أو خلل في ملفات التعريف المحلية).

• الإجراء التقني: يفضل استدعاء /v2/session/restart بدلاً من البدء من الصفر.

هندسة التدفق المثالي (The Golden Flow)

لضمان أفضل تجربة لمستخدميك، اتبع هذا التسلسل الهندسي:

المرحلة الأولى: التخصيص (Provisioning)

ابدأ بإنشاء الجلسة وحفظ instance_id و server_name في قاعدة بياناتك. لا تترك هذه البيانات للصدفة؛ فهي مفتاحك للتحكم في الجلسة مستقبلاً.

المرحلة الثانية: الإحماء والربط

عندما يفتح المستخدم لوحة التحكم الخاصة بك:

1. تحقق من الحالة عبر /v2/session/info.
2. إذا كانت STOPPED، استدعِ start فوراً في الخلفية.
3. اعرض مؤشر تحميل (Loading) جذاب بينما تنتقل الجلسة من STARTING إلى SCAN_QR_CODE.

المرحلة الثالثة: المراقبة المستمرة

بمجرد وصول الجلسة لحالة WORKING، لا تتوقف عن المتابعة. نوصي بشدة باستخدام الويب هوك (Webhooks). الاستماع لحدث session.status يجعلك تستجيب لحظياً إذا قام العميل بفصل هاتفه، مما يتيح لك إرسال إشعار فوري له: "عذراً، جلسة واتساب الخاصة بك انقطعت، يرجى إعادة المسح".

استراتيجيات التشغيل المتقدمة

الاستجابة للأعطال (Fault Tolerance)

إذا كنت تبني نظاماً لارسال التنبيهات الحساسة (مثل OTP)، لا تعتمد على جلسة واحدة. ابنِ نظام "تبديل الفشل" (Failover) بحيث إذا انتقلت جلسة لحالة FAILED، يقوم النظام تلقائياً بتوجيه الرسالة عبر جلسة بديلة.

توفير الموارد (Resource Optimization)

إذا كان لديك آلاف الجلسات لعملاء مختلفين، وبعضهم لا يستخدم النظام إلا مرة في الأسبوع، استخدم "إيقاف الخمول" (Idle Stop). إذا لم يتم إرسال أو استقبال رسالة خلال 24 ساعة، استدعِ /v2/session/stop. هذا يقلل الضغط على خوادمك ويضمن سرعة استجابة هائلة للجلسات النشطة.

الأسئلة الشائعة والأخطاء البرمجية

لماذا تظل الجلسة في حالة STARTING للأبد؟

هذا يحدث عادة بسبب محاولة تشغيل نفس الجلسة من مكانين مختلفين، أو بسبب وجود عملية صيانة على العقدة (Node) المستضيفة. انتظر 60 ثانية، ثم جرب /restart.

هل يؤثر إيقاف الجلسة على الرسائل الواردة؟

نعم، عندما تكون الحالة STOPPED أو FAILED، لا يمكن لـ Wawp استقبال الرسائل وتوجيهها للويب هوك الخاص بك. بمجرد العودة لحالة WORKING، سيقوم واتساب بمزامنة الرسائل التي وصلت أثناء الانقطاع، وسنقوم بمعالجتها.

متى يجب علي استخدام تسجيل الخروج (Logout)؟

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