أمان الجلسة

حافظ على سرية معرف الجلسة session_id ولا تشاركه علنًا أبدًا.

حالة الجلسة

تحقق من حالة الجلسة بانتظام أو استخدم Webhooks للتحديثات.

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

عملية البدء هي عملية كثيفة الموارد تتضمن عدة مراحل تقنية دقيقة: 1. استدعاء الحاوية (Container Awakening): نقوم بإيقاظ البيئة المعزولة المخصصة لجلستك. 2. تحميل نظام ملفات واتساب (WhatsApp FileSystem): يتم تحميل قاعدة بيانات الـ SQLite المحلية والبيانات التعريفية للمتصفح (Headless Browser) التي تحاكي بيئة واتساب ويب. 3.

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

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

استراتيجية "الإحماء التلقائي"

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

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

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

استمرارية الجلسة

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

أ- البوتات المجدولة

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

ب- أنظمة توفير التكلفة

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

"Instance is already starting"

هذا يعني أن هناك طلب 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. ابدأ في استخدام وظائف المراسلة.

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

تشغيل جلسة الواتساب

بدء تشغيل السيرفر السحابي للجلسة المتصلة.

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

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

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

Async Operation

This endpoint returns 'STARTING' immediately. The actual connection happens asynchronously in the background.

توصيات

Use the /v2/status endpoint to fetch the QR code once the state transitions to 'SCAN_QR_CODE'.
If you receive a 404 error, the 'instance_id' is likely incorrect or the instance was deleted.

Starting the Engine: The Deep Dive into /v2/session/start

If creating a session is like "registering a car," then calling /v2/session/start is the act of "turning the ignition." Without this step, your session is merely a passive record in our database, incapable of communicating with the WhatsApp network. This endpoint is the primary catalyst for the entire automation lifecycle.

🏗️ What Happens Technically During "Start"?

When you trigger a start request, Wawp orchestrates several high-concurrency operations:

Container Awakening: The isolated environment dedicated to your instance is powered on.
Library Initialization: The underlying WhatsApp libraries (Baileys/WAWebJS) are loaded into memory and configured with your instance's specific security parameters.
Network Handshake: The engine attempts to establish a secure WebSocket bridge between our high-performance nodes and WhatsApp's official servers.
Credential Fetching: If previous authentication exists, the engine attempts to "resume" the session. If not, it transitions to a state where it can generate a fresh QR code.

🛡️ Strategic Best Practices

1. The "State Check" Prerequisite

Never call start blindly. Always check the current status via /v2/session/info first.

The Ideal Condition: Only call start if the status is STOPPED.
The Risk: Calling start on a session that is already WORKING can cause a protocol conflict, potentially leading to a temporary disconnection or a "Session conflict" notice on the user's mobile device.

2. Handling the "Async" Nature

The start command is non-blocking. It will return a success response (200 OK) almost immediately, but the engine may still be "warming up" for several seconds.

Developer Action: Do not poll for a QR code immediately. Implement a 5-10 second "settle time" before your application starts aggressively checking for status changes.

3. "Warm Booting" for Better UX

In a production dashboard, don't wait for the user to click "Connect."

The Optimization: If you detect a user has logged into your CRM and their WhatsApp status is STOPPED, call start in the background. By the time they click on the WhatsApp integration tab, the engine will be ready to display a QR code, making the experience feel instantaneous.

💡 Industry-Standard Use Cases

A. Automated Re-connection Workers

Build a background "Watcher" service that runs every hour. If it finds a session that should be online (e.g., a "Gold Tier" customer) but has a status of STOPPED, it should trigger a start command automatically.

B. "Morning Boot" Scheduling

If your business only operates during specific hours, you can call /v2/session/stop at night to save system resources and call start 30 minutes before your agents start their shift.

⚠️ Common Errors and Troubleshooting

"Instance Not Found" (404 Not Found)

This occurs if the instance_id provided is incorrect or has been permanently deleted from our servers. Double-check your database persistence layer.

Stuck in "STARTING"

On very rare occasions, a session may hang in the "STARTING" state due to a network timeout at the WhatsApp bridge level.

Fix: If the status remains STARTING for more than 45 seconds, we recommend calling the /v2/session/restart endpoint to force a clean environment reset.

Summary of Responsibilities:

Power on the isolated WhatsApp engine.
Initiate the connection protocol with WhatsApp servers.
Transition the instance state from STOPPED to STARTING or WORKING.
Prepare the environment for QR code or Pairing code generation.

البارامترات

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

محتوى الطلب

يرسل كـ JSON

	`string`		The 12-character ID of the instance مثال:
	`string`		Your API Access Token مثال:

برمج بالذكاء الاصطناعي باستخدام Wawp MCP

MCP READY

قم بربط الـ API مباشرة مع Cursor أو Windsurf أو Claude Desktop، ودع الذكاء الاصطناعي يكتب لك كود الربط وينفذه تلقائياً!

طريقة الربط والإعداد

أمثلة الكود

استخدم أمثلة الكود الجاهزة لدمج واجهة برمجة التطبيقات (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));

عينات تفاعليةUTF-8

Ln 59, Col 1javascript

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

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

Success - Boot Initiated

3 نسخ

النوع:

application/json

string *

object *

Example

{
"name": "wawp-84729105",
"status": "STARTING",
"config": {
  "webhooks": {
    },
  "proxy": null
  }
}

طلب غير صالح - معاملات مطلوبة مفقودة

3 نسخ

غير مصرح - مفتاح الوصول غير صالح أو مفقود

2 نسخ

Command Palette

Search for a command to run...