الاشتراك في التواجد

اشترك في تحديثات التواجد في الوقت الفعلي (متصل/غير متصل) لجهة اتصال معينة.

POST
https://api.wawp.net/v2/presence/{chatId}/subscribe?access_token=123456789&chatId=201234567890%40c.us&instance_id=123456789

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

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

تسجيل الدخول
اختبار /v2/presence/{chatId}/subscribe
POST
POST

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

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

توصيات

  • اشترك فقط عندما يكون المستخدم في نافذة دردشة نشطة.

  • قم بإلغاء الاشتراك عندما يتم إلغاء تحميل مكون واجهة المستخدم لتوفير النطاق الترددي.

النبض الرقمي: الاشتراك في التواجد في الوقت الفعلي

تعد نقطة النهاية /v2/presence/{chatId}/subscribe هي "السلك الحي" لواجهة برمجة التطبيقات. على عكس طريقة "اللقطة"، يصدر هذا الأمر تعليمات لمحرك واتساب لفتح تدفق بيانات مستمر لمستخدم معين.


⚡ ميكانيكا الاشتراك

كيف يعمل؟

عندما تستدعي نقطة النهاية هذه لهدف معين (مثل 12345@c.us):

  1. المصافحة: يرسل مثيلك بروتوكولاً إلى خوادم واتساب يقول "أنا مهتم بـ 12345".
  2. التدفق: تبدأ خوادم واتساب في دفع أحداث presence.update إلى الـ socket الخاص بك.
  3. المدة: هذا التدفق ليس دائماً. يستمر عادةً لمدة تتراوح بين 20 إلى 60 ثانية بعد آخر تفاعل أو تجديد للاشتراك.

🏗️ بنية التنفيذ

لبناء ميزة "حالة مباشرة" قوية (مثل نقطة "متصل" في واجهة الدردشة)، تحتاج إلى حلقة نبضات القلب (Heartbeat Loop).

حلقة نبضات القلب

  1. حدث الواجهة: الوكيل يفتح نافذة الدردشة للمستخدم أ.
  2. الواجهة: ترسل حدث "تركيز" إلى نظامك الخلفي.
  3. النظام الخلفي: يستدعي /v2/presence/UserA/subscribe.
  4. الحلقة: كل 30 ثانية طالما نافذة الدردشة مفتوحة، يكرر النظام الخلفي استدعاء الاشتراك.
  5. التوقف: عندما يغلق الوكيل نافذة الدردشة، يوقف النظام الخلفي الحلقة. ينتهي الاشتراك تلقائياً بعد 30 ثانية.

🛡️ القيود الاستراتيجية

  • حدود التزامن: عادةً لا يمكنك الاشتراك في أكثر من ~50-100 مستخدم فريد في نفس الوقت.
  • حالة الاستخدام: تم تصميم هذه الميزة لـ "الدعم الفردي" (رؤية الوكيل للأعضاء النشطين)، وليس لـ "المراقبة الجماعية" لجميع عملائك في وقت واحد.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

Your unique WhatsApp Instance ID

مثال:
string

Your API Access Token

مثال:
string

المعرف الخاص بجهة الاتصال (@c.us)

مثال:

أمثلة الكود

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

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/presence/201234567890@c.us/subscribe";
3const params = new URLSearchParams({
4 "instance_id": "123456789",
5 "access_token": "123456789"
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) مع أمثلة للبيانات لتسهيل معالجة الأخطاء والنجاح.

ناجح - تم إكمال الطلب بنجاح
النوع:
application/json
boolean *
string *

Example

{
"success": true,
"message": "Operation completed successfully"
}
طلب غير صالح - معاملات مطلوبة مفقودة
غير مصرح - مفتاح الوصول غير صالح أو مفقود
غير موجود - الجلسة غير موجودة
خطأ في الخادم الداخلي - فشل غير متوقع
بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي
الموضوع السابقالحصول على التواجد العام
الموضوع التاليحالة واتساب (القصص)

Command Palette

Search for a command to run...