إرسال الرسائل

إرسال رسالة قائمة (Menu)

إرسال رسالة قائمة تفاعلية (قائمة خيارات) إلى الدردشة. يعرض هذا النوع من الرسائل زراً يفتح قائمة خيارات عند النقر عليه.

POST
https://api.wawp.net/v2/send/list?access_token=YOUR_ACCESS_TOKEN&chatId=201234567890&instance_id=YOUR_INSTANCE_ID&message=%7B%0A++%22title%22%3A+%22Simple+Menu%22%2C%0A++%22description%22%3A+%22Please+choose+an+option%22%2C%0A++%22footer%22%3A+%22Thank+you%21%22%2C%0A++%22button%22%3A+%22Open+Menu%22%2C%0A++%22sections%22%3A+%5B%0A++++%7B%0A++++++%22title%22%3A+%22Main+Options%22%2C%0A++++++%22rows%22%3A+%5B%0A++++++++%7B%0A++++++++++%22title%22%3A+%22Option+1%22%2C%0A++++++++++%22rowId%22%3A+%22opt1%22%2C%0A++++++++++%22description%22%3A+%22Description+for+1%22%0A++++++++%7D%2C%0A++++++++%7B%0A++++++++++%22title%22%3A+%22Option+2%22%2C%0A++++++++++%22rowId%22%3A+%22opt2%22%0A++++++++%7D%0A++++++%5D%0A++++%7D%0A++%5D%0A%7D&message.button=Open+Menu&message.description=Please+select+an+option+below&message.footer=Powered+by+Wawp&message.sections=%5B%7B+title%3A+%27Section+1%27%2C+rows%3A+%5B...%5D+%7D%5D&message.title=Simple+Menu&reply_to=false_111...AAAA

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

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

تسجيل الدخول
اختبار /v2/send/list
POSTGET

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

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

توصيات

  • أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.

  • تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم.

التنقل الحواري: إتقان محرك القوائم التفاعلية

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

قائمة

خيارات قائمة

🏗️ الهيكل الهرمي لرسالة القائمة

رسالة القائمة هي كائن متعدد الطبقات مصمم للوضوح وسهولة المسح البصري:

  1. العنوان الرئيسي (Title): وهو أول ما يراه المستخدم. يجب أن يوضح بوضوح هدف القائمة (مثلاً "قائمة دعم العملاء").
  2. الوصف (Description): استخدم هذا للتعليمات الأساسية أو السياق (مثلاً "يرجى اختيار القسم الذي ترغب في التحدث إليه").
  3. زر التنشيط (Activation Button): تسمية مخصصة (بحد أقصى 20 حرفاً) تفتح القائمة المنبثقة.
  4. الأقسام والصفوف: المحتوى الأساسي. تسمح لك الأقسام بتجميع الخيارات ذات الصلة (مثلاً "الدعم الفني" مقابل "استفسارات الفواتير")، بينما تمثل الصفوف العناصر الفردية القابلة للنقر.

🛡️ أفضل الممارسات الاستراتيجية لتصميم القوائم

1. حد الـ 10 صفوف

يفرض واتساب حداً صارماً بـ 10 صفوف كإجمالي لجميع الأقسام في رسالة قائمة واحدة.

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

2. استراتيجية المعرف الفريد (rowId)

معرف rowId مخصص لنظامك الخلفي، بينما title للمستخدم.

  • الفصل: لا تعتمد أبداً على عنوان الصف في منطقك البرمجي. استخدم دائماً rowId فريداً وأبجدياً رقمياً (مثلاً dept_billing_v1). يتيح لك ذلك تغيير نص العرض لأغراض تسويقية دون كسر منطق المعالجة في نظامك الخلفي.
  • استمرارية الحالة: يمكنك تضمين قطع صغيرة من بيانات الحالة في rowId (مثلاً user_123_opt_4) إذا كان نظامك عديم الحالة تماماً، رغم أننا نوصي بالحفاظ على حالة المستخدم في قاعدة بياناتك الخاصة المرتبطة بـ chatId.

3. المسح البصري والرموز التعبيرية

  • عناوين الأقسام: استخدم عناوين الأقسام كـ "مراسي بصرية".
  • نقاط الرموز التعبيرية: ابدأ عناوين صفوفك برموز تعبيرية (مثلاً "💳 الفواتير"، "🛠️ دعم فني"). يقلل هذا بشكل كبير من الجهد المعرفي للمستخدم، مما يسمح له بالعثور على خياره المطلوب عبر الأيقونات بدلاً من قراءة كل كلمة.

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

أدلة المنتجات المؤتمتة

قم ببناء واجهة متجر مصغرة داخل الدردشة. يمكن أن يكون القسم الأول "وصل حديثاً"، والثاني "الأكثر مبيعاً". عندما ينقر المستخدم على صف، سيقوم Webhooks (list_response) بالتقاط rowId. يمكن لنظامك حينها إرسال صورة /v2/send/image لذلك المنتج فوراً مع رابط "اشترِ الآن".

فرز الدعم الذكي

بدلاً من أن يقوم إنسان بتحية كل مستخدم، أرسل رسالة قائمة. القسم 1: "مشاكل عاجلة"، القسم 2: "معلومات عامة". بناءً على اختيار المستخدم، يمكن للبوت توجيه المحادثة إلى الوكيل الأكثر تأهيلاً أو توفير مقال من قاعدة المعرفة تلقائياً.

🛠️ المزالق الشائعة والحلول

  • طول نص الزر: إذا تجاوز نص الزر 20 حرفاً، ستفشل الرسالة في الإرسال بخطأ Validation Error. اجعل النص مقتضباً: "الخيارات"، "ابدأ هنا"، أو "القائمة".
  • الأقسام الفارغة: يجب أن يحتوي كل قسم على صف واحد على الأقل. إرسال قسم فارغ سيؤدي إلى فشل العرض على شبكة واتساب.
  • فخ "عدم الاستجابة": يفتح المستخدمون أحياناً القائمة ولكن لا يختارون شيئاً. تأكد من أن البوت لديه منطق "مهلة" (Timeout) أو متابعة لإعادة إشراك المستخدم إذا ظل غير نشط لأكثر من 5 دقائق بعد استلام القائمة.

ملخص الإمكانيات:

  • تقديم قوائم تفاعلية منبثقة مع ما يصل إلى 10 صفوف.
  • دعم لأقسام متعددة مجمعة منطقياً مع عناوين مخصصة.
  • تجربة مستخدم عالية التحويل باستخدام أزرار مخصصة وبيانات وصفية للصفوف.
  • تتبع التفاعل في الوقت الفعلي عبر أحداث list_response في Webhook.
  • دعم كامل لـ Markdown لعناوين الأقسام وأوصاف المتن.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

المعرف الفريد لجلسة واتساب

مثال:
string

رمز وصول API

مثال:
string

رقم واتساب للمستلم

مثال:
object

هيكل رسالة القائمة التفاعلية.

مثال:
string

عنوان رأس رسالة القائمة.

مثال:
string

نص متن الرسالة.

مثال:
string

نص صغير في الأسفل.

مثال:
string

النص الموجود على الزر الذي يفتح القائمة.

مثال:
array

مصفوفة من الأقسام، يحتوي كل منها على عنوان وصفوف.

مثال:
string—

معرف الرسالة التي تقوم بالرد عليها

مثال:

أمثلة الكود

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

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/send/list";
3const params = new URLSearchParams({
4  "instance_id": "YOUR_INSTANCE_ID",
5  "access_token": "YOUR_ACCESS_TOKEN"
6}).toString();
7const body = {
8  "chatId": "201234567890",
9  "message": {
10    "title": "Simple Menu",
11    "description": "Please choose an option",
12    "footer": "Thank you!",
13    "button": "Open Menu",
14    "sections": [
15      {
16        "title": "Main Options",
17        "rows": [
18          {
19            "title": "Option 1",
20            "rowId": "opt1",
21            "description": "Description for 1"
22          },
23          {
24            "title": "Option 2",
25            "rowId": "opt2"
26          }
27        ]
28      }
29    ]
30  },
31  "message.title": "Simple Menu",
32  "message.description": "Please select an option below",
33  "message.footer": "Powered by Wawp",
34  "message.button": "Open Menu",
35  "message.sections": "[{ title: 'Section 1', rows: [...] }]",
36  "reply_to": "false_111...AAAA"
37};
38
39fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
40  method: "POST",
41  headers: { "Content-Type": "application/json" },
42  body: JSON.stringify(body)
43})
44  .then(async (response) => {
45    if (response.ok) {
46      const data = await response.json();
47      console.log("Success:", data);
48      return data;
49    }
50    
51    // Error Handling
52    if (response.status === 400) {
53      console.error("Error 400: طلب غير صالح - معاملات مطلوبة مفقودة");
54    }
55    if (response.status === 400) {
56      console.error("Error 400: Bad Request - Invalid Number (Egypt)");
57    }
58    if (response.status === 400) {
59      console.error("Error 400: Bad Request - Invalid Number (Saudi Arabia)");
60    }
61    if (response.status === 400) {
62      console.error("Error 400: Bad Request - Invalid Number (Unknown)");
63    }
64    if (response.status === 400) {
65      console.error("Error 400: طلب غير صالح (تنسيق XML)");
66    }
67    if (response.status === 400) {
68      console.error("Error 400: طلب غير صالح (نص عادي)");
69    }
70    if (response.status === 401) {
71      console.error("Error 401: غير مصرح - مفتاح الوصول غير صالح أو مفقود");
72    }
73    if (response.status === 401) {
74      console.error("Error 401: غير مصرح (تنسيق XML)");
75    }
76    if (response.status === 404) {
77      console.error("Error 404: غير موجود - الجلسة غير موجودة");
78    }
79    if (response.status === 404) {
80      console.error("Error 404: غير موجود (تنسيق XML)");
81    }
82    if (response.status === 429) {
83      console.error("Error 429: طلبات كثيرة جداً - تم تجاوز حد المعدل");
84    }
85    if (response.status === 500) {
86      console.error("Error 500: خطأ في الخادم الداخلي - فشل غير متوقع");
87    }
88    if (response.status === 500) {
89      console.error("Error 500: خطأ في الخادم الداخلي (HTML)");
90    }
91    if (response.status === 502) {
92      console.error("Error 502: بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي");
93    }
94    if (response.status === 502) {
95      console.error("Error 502: بوابة غير صالحة (تنسيق XML)");
96    }
97
98    const errorText = await response.text();
99    console.error(`Error ${response.status}: ${errorText}`);
100  })
101  .catch((error) => console.error("Network Error:", error));
عينات تفاعلية
Ln 101, Col 1javascript

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

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

تم إرسال الرسالة بنجاح
النوع:
application/json
object *
string *
object *
number *
boolean *
string *
string *
number *
string *
string *
string *
boolean *
number *
boolean *
boolean *
boolean *
boolean *
boolean *
array *
array *
array *
boolean *
array *

Example

{
"_data": {
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
  "viewed": false,
  "body": "BASE64_IMAGE_DATA",
  "type": "image",
  "t": 1759108866,
  "from": {
    "server": "c.us",
    "user": "111111111111",
    "_serialized": "111111111111@c.us"
    },
  "to": {
    "server": "c.us",
    "user": "000000000000",
    "_serialized": "000000000000@c.us"
    },
  "ack": 0,
  "isNewMsg": true,
  "star": false,
  "kicNotified": false,
  "caption": "Here's your requested image.",
  "deprecatedMms3Url": "https://example.com/media-url",
  "directPath": "/media/direct/path/example",
  "mimetype": "image/jpeg",
  "filehash": "FILE_HASH_PLACEHOLDER",
  "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
  "size": 192487,
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "mediaKeyTimestamp": 1759108865,
  "streamable": false,
  "mediaHandle": null,
  "isFromTemplate": false,
  "pollInvalidated": false,
  "isSentCagPollCreation": false,
  "latestEditMsgKey": null,
  "latestEditSenderTimestampMs": null,
  "mentionedJidList": {
    },
  "groupMentions": {
    },
  "isEventCanceled": false,
  "eventInvalidated": false,
  "isVcardOverMmsDocument": false,
  "isForwarded": false,
  "isQuestion": false,
  "questionReplyQuotedMessage": null,
  "questionResponsesCount": 0,
  "readQuestionResponsesCount": 0,
  "labels": {
    },
  "hasReaction": false,
  "disappearingModeInitiator": "chat",
  "disappearingModeTrigger": "chat_settings",
  "productHeaderImageRejected": false,
  "lastPlaybackProgress": 0,
  "isDynamicReplyButtonsMsg": false,
  "isCarouselCard": false,
  "parentMsgId": null,
  "callSilenceReason": null,
  "isVideoCall": false,
  "callDuration": null,
  "callCreator": null,
  "callParticipants": null,
  "isCallLink": null,
  "callLinkToken": null,
  "isMdHistoryMsg": false,
  "stickerSentTs": 0,
  "lastUpdateFromServerTs": 0,
  "invokedBotWid": null,
  "bizBotType": null,
  "botResponseTargetId": null,
  "botPluginType": null,
  "botPluginReferenceIndex": null,
  "botPluginSearchProvider": null,
  "botPluginSearchUrl": null,
  "botPluginSearchQuery": null,
  "botPluginMaybeParent": false,
  "botReelPluginThumbnailCdnUrl": null,
  "botMessageDisclaimerText": null,
  "botMsgBodyType": null,
  "requiresDirectConnection": false,
  "bizContentPlaceholderType": null,
  "hostedBizEncStateMismatch": false,
  "senderOrRecipientAccountTypeHosted": false,
  "placeholderCreatedWhenAccountIsHosted": false,
  "galaxyFlowDisabled": false,
  "links": {
    }
  },
"mediaKey": "MEDIA_KEY_PLACEHOLDER",
"id": {
  "fromMe": true,
  "remote": "000000000000@c.us",
  "id": "MSG_ID_123456",
  "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
"ack": 0,
"hasMedia": true,
"body": "Here's your requested image.",
"type": "image",
"timestamp": 1759108866,
"from": "111111111111@c.us",
"to": "000000000000@c.us",
"deviceType": "android",
"isForwarded": false,
"forwardingScore": 0,
"isStatus": false,
"isStarred": false,
"fromMe": true,
"hasQuotedMsg": false,
"hasReaction": false,
"vCards": {
  },
"mentionedIds": {
  },
"groupMentions": {
  },
"isGif": false,
"links": {
  }
}
طلب غير صالح - معاملات مطلوبة مفقودة
غير مصرح - مفتاح الوصول غير صالح أو مفقود
غير موجود - الجلسة غير موجودة
طلبات كثيرة جداً - تم تجاوز حد المعدل
خطأ في الخادم الداخلي - فشل غير متوقع
بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي
الموضوع السابقإرسال ملف PDF
الموضوع التاليإرسال حدث (Event)

Command Palette

Search for a command to run...