إدارة الجلسات

بدء الجلسة

تشغيل جلسة واتساب وتجهيزها للاتصال.

POST
https://api.wawp.net/v2/session/start?access_token=YOUR_ACCESS_TOKEN&instance_id=Your_Instance_ID

تسجيل الدخول مطلوب

سجل الدخول لاستبدال المعرفات (Instance ID) ورمز الوصول (Access Token) بمعلومات حسابك الحقيقي لاختبار ال API مباشرة.

تسجيل الدخول
اختبار /v2/session/start
POSTGET

لا توجد معاملات استعلام مطلوبة

هذه النهاية الطرفية لا تتوقع بيانات في الرابط.

توصيات

  • استخدم نقطة النهاية /v2/session/info لجلب رمز QR بمجرد انتقال الحالة إلى 'SCAN_QR_CODE'.

  • إذا تلقيت خطأ 404، فمن المحتمل أن يكون 'instance_id' غير صحيح أو أن النسخة قد حذفت.

تشغيل المحرك: الدليل الكامل لنقطة النهاية /v2/session/start

إذا كان إنشاء الجلسة هو "حجز السيارة"، فإن استدعاء /v2/session/start هو "تشغيل المحرك". بدون هذه الخطوة، تظل الجلسة مجرد سجل في قاعدة البيانات، غير قادرة على الاتصال بواتساب أو معالجة أي بيانات.

ماذا يحدث تقنياً عند النقر على "بدء"؟

عملية البدء هي عملية كثيفة الموارد تتضمن عدة مراحل تقنية دقيقة:

  1. استدعاء الحاوية (Container Awakening): نقوم بإيقاظ البيئة المعزولة المخصصة لجلستك.
  2. تحميل نظام ملفات واتساب (WhatsApp FileSystem): يتم تحميل قاعدة بيانات الـ SQLite المحلية والبيانات التعريفية للمتصفح (Headless Browser) التي تحاكي بيئة واتساب ويب.
  3. مصافحة الشبكة (Network Handshake): يبدأ المحرك في محاولة الاتصال بخوادم واتساب الموزعة عالمياً.
  4. تحديد الحالة التالية:
    • إذا كانت الجلسة مرتبطة مسبقاً برقم هاتفك، فسينتقل المحرك مباشرة إلى حالة WORKING.
    • إذا كانت جلسة جديدة، فسيقوم المحرك بتوليد أول رمز QR وينتقل إلى حالة SCAN_QR_CODE.

الأوركسترا البرمجية: كيف تدمج "البدء" في تطبيقك؟

التعامل مع الحالات الانتقالية

أحد الأخطاء الشائعة هو توقع تغير الحالة فوراً بعد استدعاء start. تذكر أن الحالة ستكون STARTING لعدة ثوانٍ. أفضل ممارسة:

  • أرسل طلب start.
  • ابدأ "بولينج" (Polling) خفيف على نقطة النهاية /v2/session/info كل 3 ثوانٍ.
  • بمجرد رصد انتقال الحالة إلى SCAN_QR_CODE أو WORKING، قم بتحديث واجهة المستخدم فوراً.

استراتيجية "الإحماء التلقائي" (Auto-Warmup)

لتحسين تجربة العميل (UX)، يمكنك البدء بتشغيل المحرك بمجرد دخول المستخدم إلى صفحة الربط، حتى قبل أن يطلب ذلك صراحة. هذا يوفر عليه 10-15 ثانية من وقت الانتظار.

[!TIP] لا تقم أبداً بتلقيم استدعاء start في كل مرة يفتح فيها المستخدم التطبيق إذا كانت الجلسة في حالة WORKING بالفعل؛ فهذا قد يسبب قطع الاتصال النشط وإعادة الاتصال بلا داعٍ.

الأمان والمرونة (Resilience)

التعامل مع حالات الفشل عند التشغيل

في بعض الأحيان، قد يفشل المحرك في البدء بسبب "تضارب الجلسات" (Session Conflict) - وهو أن يحاول المحرك العمل بينما هناك نسخة أخرى منه لا تزال عالقة في الذاكرة. الحل: إذا ظل المحرك في حالة STARTING لأكثر من 60 ثانية، استخدم استراتيجية "الإجبار على الإغلاق ثم البدء" عبر استدعاء /v2/session/stop ثم /v2/session/start.

استمرارية الجلسة (Session Persistence)

تتميز Wawp بقدرتها العالية على الحفاظ على الربط. بمجرد استدعاء start والوصول لحالة WORKING، سيحاول النظام إعادة تشغيل نفسه تلقائياً إذا حدث خلل في الخادم المضيف، دون تدخل منك. ومع ذلك، ننصح دائماً بمراقبة الويب هوك الخاص بحالة الجلسة.

حالات استخدام متقدمة

أ- البوتات المجدولة (Scheduled Bots)

إذا كان لديك بوت يرسل تقارير صباحية في الساعة 8:00 صباحاً، يمكنك جدولة كود برمجي يستدعي start في الساعة 7:55 لضمان أن المحرك "دافئ" وجاهز للإرسال في الموعد المحدد.

ب- أنظمة توفير التكلفة (Cost Efficiency)

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

استكشاف الأخطاء (Troubleshooting)

"Instance is already starting" (400 Bad Request)

هذا يعني أن هناك طلب start قيد المعالجة حالياً. لا تقم بإرسال طلبات متكررة؛ فقط انتظر وراقب الحالة عبر /session/info.

"Session data corrupted"

في حالات نادرة جداً، قد تفشل الجلسة في البدء بسبب تلف ملفات التعريف المحلية. إذا واجهت هذا، الحل الوحيد هو استدعاء /v2/session/logout ثم /v2/session/start من جديد لمسح البيانات التالفة.

ملخص الخطوات

  1. تأكد أن الحالة STOPPED.
  2. استدعِ /v2/session/start.
  3. انتظر انتقالات الحالة (STARTING -> SCAN_QR_CODE/WORKING).
  4. ابدأ في استخدام وظائف المراسلة.

البارامترات

قم بتهيئة المعاملات المطلوبة للتفاعل مع نقطة النهاية هذه. جميع وسائط الاستعلام والبيانات مدرجة أدناه مع تفاصيلها.

محتوى الطلب

يرسل كـ JSON
string

معرف النسخة الفريد

مثال:
string

مفتاح الوصول الخاص بـ API

مثال:

أمثلة الكود

استخدم أمثلة الكود الجاهزة لدمج واجهة برمجة التطبيقات (API) في مشروعك بسرعة وكفاءة. اختر لغة البرمجة والمكتبة التي تفضلها.

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/session/start";
3const params = new URLSearchParams({
4  "instance_id": "Your_Instance_ID",
5  "access_token": "YOUR_ACCESS_TOKEN"
6}).toString();
7
8
9fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
10  method: "POST",
11  headers: { "Content-Type": "application/json" },
12  
13})
14  .then(async (response) => {
15    if (response.ok) {
16      const data = await response.json();
17      console.log("Success:", data);
18      return data;
19    }
20    
21    // Error Handling
22    if (response.status === 400) {
23      console.error("Error 400: طلب غير صالح - معاملات مطلوبة مفقودة");
24    }
25    if (response.status === 400) {
26      console.error("Error 400: طلب غير صالح (تنسيق XML)");
27    }
28    if (response.status === 400) {
29      console.error("Error 400: طلب غير صالح (نص عادي)");
30    }
31    if (response.status === 401) {
32      console.error("Error 401: غير مصرح - مفتاح الوصول غير صالح أو مفقود");
33    }
34    if (response.status === 401) {
35      console.error("Error 401: غير مصرح (تنسيق XML)");
36    }
37    if (response.status === 404) {
38      console.error("Error 404: غير موجود - الجلسة غير موجودة");
39    }
40    if (response.status === 404) {
41      console.error("Error 404: غير موجود (تنسيق XML)");
42    }
43    if (response.status === 500) {
44      console.error("Error 500: خطأ في الخادم الداخلي - فشل غير متوقع");
45    }
46    if (response.status === 500) {
47      console.error("Error 500: خطأ في الخادم الداخلي (HTML)");
48    }
49    if (response.status === 502) {
50      console.error("Error 502: بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي");
51    }
52    if (response.status === 502) {
53      console.error("Error 502: بوابة غير صالحة (تنسيق XML)");
54    }
55
56    const errorText = await response.text();
57    console.error(`Error ${response.status}: ${errorText}`);
58  })
59  .catch((error) => console.error("Network Error:", error));
عينات تفاعلية
Ln 59, Col 1javascript

الردود المتوقعة

استكشف كافة الردود والنتائج المحتملة من الخادم. قمنا بتوثيق كل كود حالة (Status Code) مع أمثلة للبيانات لتسهيل معالجة الأخطاء والنجاح.

Success - Boot Initiated
النوع:
application/json
string *
string *
object *

Example

{
"name": "wawp-84729105",
"status": "STARTING",
"config": {
  "webhooks": {
    },
  "proxy": null
  }
}
طلب غير صالح - معاملات مطلوبة مفقودة
غير مصرح - مفتاح الوصول غير صالح أو مفقود
غير موجود - الجلسة غير موجودة
خطأ في الخادم الداخلي - فشل غير متوقع
بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي
الموضوع السابقإنشاء جلسة
الموضوع التاليإيقاف الجلسة

Command Palette

Search for a command to run...