إجراءات الدردشة

قائمة المحادثات ونظرة عامة

احصل على قائمة بجميع المحادثات النشطة (الأفراد والمجموعات) مع دعم الترقيم (Pagination).

GET
https://api.wawp.net/v2/chats?access_token=YOUR_ACCESS_TOKEN&instance_id=123456789&limit=20&offset=0&sortBy=id&sortOrder=DESC

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

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

تسجيل الدخول
اختبار /v2/chats
GETPOST

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

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

توصيات

  • رتب حسب 'last_message_time' لإظهار الدردشات الأكثر نشاطًا في الأعلى.

  • قم بتصفية الدردشات المؤرشفة إذا كانت تسبب فوضى في العرض.

إدارة وقائمة المحادثات

استرجع نظرة عامة على جميع المحادثات المتاحة حالياً في مثيل واتساب الخاص بك.

🛡️ أفضل الممارسات

احتراف البريد الوارد: استرجاع المحادثات ومزامنتها على نطاق واسع

تعد نقطة النهاية /v2/chats هي البوابة الإدارية لتاريخ مثيل واتساب الخاص بك. بخلاف نقطة نهاية "نظرة عامة"، التي توفر لقطة سريعة، تم تصميم واجهة برمجة تطبيقات قائمة المحادثات لـ الاكتشاف الشامل و المزامنة العميقة. سواء كنت تقوم بنقل البيانات إلى نظام CRM جديد أو بناء أرشيف قابل للبحث، فإن إتقان تفاصيل هذه النقطة أمر ضروري لتكاملات واتساب الاحترافية.

🏗️ آليات اكتشاف المحادثات

عندما تطلب قائمة المحادثات، يتفاعل محرك Wawp مع قاعدة بياناته المشفرة الداخلية لإعادة بناء رسم المحادثات. تتضمن هذه العملية:

  1. الإرواء (Hydration): ربط معرفات JIDs الخام (مثل 201234567890@c.us) بأسماء العرض الخاصة بها وأحدث حالة.
  2. تصنيف الحالة: تحديد المحادثات "المثبتة" أو "المؤرشفة" أو "المكتومة".
  3. معالجة الترقيم: حساب منطق الإزاحة (offset) والحد (limit) لتقديم مجموعة فرعية محددة من النتائج.

🚀 استراتيجيات الترقيم والفهرسة المتقدمة

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

1. مزامنة "النافذة المنزلقة"

إذا كنت تقوم بمزامنة قاعدة بياناتك المحلية مع Wawp لأول مرة:

  • المرحلة الأولى: جلب أول 50 نتيجة (limit=50, offset=0) للحصول على أحدث نشاط.
  • المرحلة الثانية: استخدام حلقة تكرارية لجلب الصفحات التالية (offset=50, 100, ...) حتى تصبح مصفوفة الاستجابة فارغة.
  • المرونة تجاه الانقطاع: قم بتخزين آخر offset ناجح في قاعدة بياناتك المحلية حتى تتمكن من استئناف المزامنة في حال انقطاع الاتصال.

2. الفرز الاستراتيجي

  • sortBy=id: مفيد للفهرسة الأبجدية أو فحوصات الاتساق.
  • sortOrder=DESC: الإعداد الافتراضي والأكثر توصية. يضمن عودة أحدث السلاسل — تلك التي من المرجح أن تتطلب اهتماماً فورياً — أولاً.

🛡️ أفضل الممارسات للمراقبة الفعالة

بينما تعد الويب هوك (Webhooks) هي الطريقة المفضلة لاستلام الرسائل الجديدة، تظل نقطة النهاية /v2/chats هي المصدر الحقيقي لـ تغييرات حالة المحادثة (مثل تغيير المستخدم لاسم المجموعة أو أرشفة سلسلة محادثات).

  • المزامنة الفرقية (Delta Sync): بدلاً من مراقبة القائمة الكاملة، قم بمراقبة الصفحة الأولى فقط (limit=20) كل ساعة. إذا اكتشفت تغييراً في chatId لم يكن نظامك يعرفه، فقم بإطلاق عملية جلب عميقة لتلك المحادثة المحددة.
  • سياسة الأرشفة: للحفاظ على هذه القائمة قابلة للإدارة، قم بتنفيذ سكربت للأرشفة التلقائية. استخدم قائمة المحادثات لتحديد المحادثات "الخاملة" (لا توجد رسائل لمدة 90 يوماً) واستدعِ نقطة نهاية الأرشفة لنقلها خارج القائمة "النشطة".

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

بناء "مستكشف واتساب"

أنشئ واجهة بحث مخصصة لفريقك.

  • المنطق: جلب قائمة المحادثات بالكامل (بناءً على الترقيم) وفهرسة حقول name و id في مثيل ElasticSearch أو Meilisearch. يتيح ذلك لوكلاء الدعم العثور على أي عميل فوراً دون انتظار استجابة المحرك.

التدقيق الذاتي للبوت

في بيئة متعددة البوتات، استخدم نقطة النهاية هذه للتأكد من أن البوت الخاص بك لم يتم "تركه" في مجموعات لا ينبغي أن يكون فيها. قم بمسح القائمة بانتظام بحثاً عن معرفات مجموعات غير معروفة (@g.us) وغادرها برمجياً.

⚠️ اعتبارات هامة

  • إعادة تشغيل المحرك: أثناء "الإقلاع البارد" للمحرك، قد تستغرق قائمة المحادثات بضع ثوانٍ لتظهر حيث يعيد المزامنة مع التخزين المشفر للهاتف. تعامل مع استجابات 202 Accepted أو القوائم الفارغة بلباقة خلال أول 30 ثانية من الجلسة.
  • أذونات المجموعات: بالنسبة للمجموعات، تعيد نقطة النهاية هذه البيانات الوصدية للمجموعة المتاحة لمثيلك. إذا تمت إزالتك من مجموعة، فقد تظل تظهر في القائمة لـ "فترة سماح" قصيرة قبل أن تختفي.
  • إدارة الذاكرة: يشغل كل كائن محادثة في الاستجابة قدراً صغيراً من الذاكرة. في الطلبات الكبيرة جداً (مثل limit=500)، تأكد من أن طبقة التطبيق لديك (Node.js/Python) لديها مساحة كافية لمعالجة بيانات JSON.

البارامترات

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

بارامترات الرابط

جزء من مسار الرابط أو استعلام
string

Your unique WhatsApp Instance ID

مثال:
string

Your API Access Token

مثال:
string—

الحقل الذي سيتم الفرز بناءً عليه (مثل id)

مثال:
string—

اتجاه الفرز (ASC أو DESC)

مثال:
number—

عدد المحادثات المراد استرجاعها

مثال:
number—

عدد المحادثات المراد تخطيها

مثال:

أمثلة الكود

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

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

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

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

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

Example

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

Command Palette

Search for a command to run...