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

إرسال استطلاع رأي (Poll)

إرسال استطلاع رأي تفاعلي بخيارات متعددة.

POST
https://api.wawp.net/v2/send/poll?access_token=123456789&chatId=201234567890%40c.us&instance_id=123456789&poll=%7B%0A++%22name%22%3A+%22How+are+you%3F%22%2C%0A++%22options%22%3A+%5B%0A++++%22Awesome%21%22%2C%0A++++%22Good%21%22%2C%0A++++%22Not+bad%21%22%0A++%5D%2C%0A++%22multipleAnswers%22%3A+true%0A%7D&reply_to=null

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

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

تسجيل الدخول
اختبار /v2/send/poll
POST
POST

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

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

توصيات

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

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

الديمقراطية في الدردشة: إتقان محرك استطلاعات الرأي التفاعلية

تعد استطلاعات الرأي (/v2/send/poll) المعيار الذهبي لجمع الملاحظات المنظمة في بيئة حوارية. فهي تقضي على "إجهاد اتخاذ القرار" المرتبط بكتابة الردود النصية وتوفر طريقة مرئية نظيفة للمستخدمين للتعبير عن تفضيلاتهم. في تطبيقات Wawp، تعمل استطلاعات الرأي كنقاط إدخال بيانات تفاعلية يمكنها إطلاق سير عمل خلفي معقد بناءً على اختيار المستخدم.

🏗️ مسار مزامنة الخيارات المتعددة

عندما تستدعي نقطة النهاية /send/poll، يبدأ Wawp تدفق مزامنة متخصص:

  1. التحقق من المخطط (Schema): يتحقق المحرك من أن مصفوفة الخيارات (options) تحتوي على خيارين على الأقل ولا تتجاوز الحد الأقصى لواتساب وهو 12 خياراً. كما يضمن أن طول كل خيار أقل من 255 حرفاً.
  2. اتساق البيانات الوصفية: يتم تسلسل name (سؤالك) و options في حزمة استطلاع واتساب أصلية. يحافظ Wawp على تعيين بين خيارات النصوص هذه ومعرفات فهرسها الداخلية، مما يضمن أنه عندما يصوت المستخدم، تحصل على قيمة نظيفة ويمكن التنبؤ بها في Webhook الخاص بك.
  3. منطق الإجابات المتعددة (MultipleAnswers): يؤدي تعيين multipleAnswers: true إلى توجيه شبكة واتساب لعرض مربعات اختيار (Checkboxes) بدلاً من أزرار الاختيار (Radio buttons). هذا يغير طبيعة التفاعل من "اختيار واحد" إلى "استطلاع رأي متكامل"، مما يسمح بجمع بيانات أكثر تعقيداً.

🛡️ أفضل الممارسات الاستراتيجية للتفاعل مع الملاحظات

1. قاعدة "قوة الخمسة"

بينما يمكنك إرسال 12 خياراً، تشير الأبحاث إلى أن معدل التحويل ينخفض بشكل ملحوظ بعد الخيار الخامس.

  • تأثير تجربة المستخدم: على شاشات الجوال، تتطلب استطلاعات الرأي الطويلة التمرير، مما يؤدي إلى تخلي المستخدمين عنها. ابقِ خياراتك الأكثر أهمية في المراكز الثلاثة الأولى.
  • الوضوح: استخدم الرموز التعبيرية في نصوص الخيارات (مثل "✅ نعم"، "❌ لا") لتوفير إشارات مرئية فورية تتجاوز حواجز اللغة.

2. تتبع التصويت بدقة عالية

قيمة استطلاع الرأي تكمن في البيانات التي ينتجها.

  • المراقبة: استخدم دائماً Webhooks (poll.vote) لالتقاط تفاعل المستخدم. عندما يغير المستخدم تصويته، يرسل واتساب حدثاً جديداً. يجب أن يكون نظامك الخلفي قادراً على التعامل مع التكرار، وتحديث اختيار المستخدم بناءً على أحدث طابع زمني لـ poll_vote.
  • التعامل مع الإجابات المتعددة: في وضع multipleAnswers، تذكر معالجة مصفوفات الخيارات. في كل مرة يقوم فيها المستخدم بتحديد أو إلغاء تحديد مربع، يتم إطلاق حدث جديد يعكس الحالة الحالية الكاملة لاختيارات ذلك المستخدم.

3. المتابعات السياقية

لا تجعل التصويت نهاية المحادثة.

  • سير العمل: عندما يتلقى مشروع الـ Webhook الخاص بك تصويتاً للخيار (أ)، اجعل نظامك يطلق تلقائياً رسالة نصية عبر /v2/send/text أو صورة عبر /v2/send/image تتناول هذا الاختيار تحديداً. هذا النوع من "شجرة القرار" المؤتمتة يجعل البوت يبدو ذكياً ومتجاوباً.

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

جدولة الأحداث في الوقت الفعلي

أرسل استطلاعاً بفتحات زمنية لاجتماع: "متى وقتكم المفضل؟ 1) 10 صباحاً، 2) 2 ظهراً، 3) 4 عصراً". مع تصويت المستخدمين، يمكن لنظامك رؤية الفتحة التي حصلت على أكبر عدد من الأصوات في الوقت الفعلي وإرسال تأكيد بمجرد التوصل إلى إجماع.

استطلاعات رضا العملاء (CSAT)

بدلاً من السؤال "قيمنا من 1 إلى 5"، أرسل استطلاعاً برؤوس وصفية أو نجوم: "⭐ ضعيف" إلى "⭐⭐⭐⭐⭐ ممتاز". توفر الملاحظات المرئية لمؤشر "تم التصويت" على شاشة المستخدم شعوراً بالإغلاق لا يمكن للرد النصي مضاهاته.

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

  • خيار مكرر: إرسال استطلاع رأي بخيارين متطابقين سيؤدي لرفض الرسالة من قبل شبكة واتساب. تأكد دائماً من فرادة خياراتك في منطق نظامك الخلفي.
  • فخ "التصويت المفقود": على عكس الرسائل النصية، التصويتات هي تحديثات ثنائية. إذا قام المستخدم بالتصويت بينما كان خادم الـ Webhook الخاص بك معطلاً، فقد تفقد الحدث. نوصي باستخدام سجلات استطلاعات الرأي الخاصة بنا أو طابور رسائل قوي لمعالجة عمليات تسليم الـ Webhook المتأخرة.
  • طول السؤال: قد يتم اقتطاع السؤال الطويل جداً في معاينة الدردشة. ابقِ name موجزاً وضع السياق التفصيلي في رسالة نصية سابقة.

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

  • تقديم استطلاعات رأي واتساب أصلية وتفاعلية مع ما يصل إلى 12 خياراً مخصصاً.
  • دعم وضع الخيار الواحد (راديو) والخيارات المتعددة (مربعات اختيار).
  • تتبع التصويت في الوقت الفعلي عبر أحداث poll_vote المتسقة في Webhook.
  • دعم متقدم للخيوط والردود باستخدام معلمة reply_to.
  • مزامنة عالية الدقة بين سؤال الاستطلاع وفهارس الخيارات القابلة للتحديد.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

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

مثال:
string

رمز وصول API الخاص بك

مثال:
string

رقم الهاتف المستهدف أو معرف المجموعة

مثال:
object

هيكل استطلاع الرأي الذي يحتوي على الاسم والخيارات.

مثال:
string—

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

مثال:

أمثلة الكود

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

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/send/poll";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "123456789"
6}).toString();
7const body = {
8  "chatId": "201234567890@c.us",
9  "poll": {
10    "name": "How are you?",
11    "options": [
12      "Awesome!",
13      "Good!",
14      "Not bad!"
15    ],
16    "multipleAnswers": true
17  },
18  "reply_to": "null"
19};
20
21fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
22  method: "POST",
23  headers: { "Content-Type": "application/json" },
24  body: JSON.stringify(body)
25})
26  .then(async (response) => {
27    if (response.ok) {
28      const data = await response.json();
29      console.log("Success:", data);
30      return data;
31    }
32    
33    // Error Handling
34    if (response.status === 400) {
35      console.error("Error 400: طلب غير صالح - معاملات مطلوبة مفقودة");
36    }
37    if (response.status === 400) {
38      console.error("Error 400: Bad Request - Invalid Number (Egypt)");
39    }
40    if (response.status === 400) {
41      console.error("Error 400: Bad Request - Invalid Number (Saudi Arabia)");
42    }
43    if (response.status === 400) {
44      console.error("Error 400: Bad Request - Invalid Number (Unknown)");
45    }
46    if (response.status === 400) {
47      console.error("Error 400: طلب غير صالح (تنسيق XML)");
48    }
49    if (response.status === 400) {
50      console.error("Error 400: طلب غير صالح (نص عادي)");
51    }
52    if (response.status === 401) {
53      console.error("Error 401: غير مصرح - مفتاح الوصول غير صالح أو مفقود");
54    }
55    if (response.status === 401) {
56      console.error("Error 401: غير مصرح (تنسيق XML)");
57    }
58    if (response.status === 404) {
59      console.error("Error 404: غير موجود - الجلسة غير موجودة");
60    }
61    if (response.status === 404) {
62      console.error("Error 404: غير موجود (تنسيق XML)");
63    }
64    if (response.status === 429) {
65      console.error("Error 429: طلبات كثيرة جداً - تم تجاوز حد المعدل");
66    }
67    if (response.status === 500) {
68      console.error("Error 500: خطأ في الخادم الداخلي - فشل غير متوقع");
69    }
70    if (response.status === 500) {
71      console.error("Error 500: خطأ في الخادم الداخلي (HTML)");
72    }
73    if (response.status === 502) {
74      console.error("Error 502: بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي");
75    }
76    if (response.status === 502) {
77      console.error("Error 502: بوابة غير صالحة (تنسيق XML)");
78    }
79
80    const errorText = await response.text();
81    console.error(`Error ${response.status}: ${errorText}`);
82  })
83  .catch((error) => console.error("Network Error:", error));
عينات تفاعلية
Ln 83, 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": {
  }
}
طلب غير صالح - معاملات مطلوبة مفقودة
غير مصرح - مفتاح الوصول غير صالح أو مفقود
غير موجود - الجلسة غير موجودة
طلبات كثيرة جداً - تم تجاوز حد المعدل
خطأ في الخادم الداخلي - فشل غير متوقع
بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي
الموضوع السابقإرسال الموقع
الموضوع التاليإرسال تصويت (Poll Vote)

Command Palette

Search for a command to run...