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

إرسال تصويت (Poll Vote)

التصويت برمجياً على استطلاع رأي في واتساب.

POST
https://api.wawp.net/v2/send/poll/vote?access_token=123456789&chatId=201234567890%40c.us&instance_id=123456789&messageId=ABC123456789&votes=%5B%22Awesome%21%22%5D

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

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

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

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

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

توصيات

  • تحقق من معرف رسالة الاستطلاع قبل محاولة التصويت.

  • استخدم هذا للاختبار الآلي لتدفقات عمل الاستطلاع.

المشاركة البرمجية: إتقان محرك تصويت الاستطلاعات

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

🏗️ بنية التصويت البرمجي

يتطلب التصويت الديناميكي عبر API فهماً دقيقاً لنظام حالة الاستطلاع:

  1. ارتباط الهدف: يتطلب المحرك messageId صالحاً لاستطلاع تم إرساله مسبقاً. يضمن ذلك تثبيت التصويت في السياق التفاعلي الصحيح.
  2. فهرسة الخيارات: يتيح لك Wawp التصويت باستخدام إما الاسم النصي الصريح للخيار (مثلاً "رائع!") أو موقعه المفهرس (بدءاً من 0) داخل الاستطلاع. يقوم محركنا تلقائياً بتحويل هذه الخيارات إلى المعرفات الثنائية الداخلية التي تتطلبها شبكة واتساب، مما يمنع أخطاء "التصويت الشبح".
  3. تجاوز الحالة: يتبع واتساب نموذج "التجاوز" (Overwrite) للتصويت. عندما تستدعي نقطة النهاية هذه، فإن مصفوفة votes الجديدة الخاصة بك تحل تماماً محل اختيارك السابق لهذا الاستطلاع. إذا أرسلت مصفوفة فارغة []، يتم سحب تصويتك السابق بالكامل.

🛡️ أفضل الممارسات الاستراتيجية لمشاركة البوت

1. التحقق قبل التصويت

لضمان موثوقية عالية، يجب على نظامك التحقق من وجود الاستطلاع وأنه لا يزال "نشطاً".

  • التنفيذ: قبل التصويت، تحقق من قاعدة بياناتك المحلية أو استخدم مستمعاً (Listener) للتأكد من عدم حذف الاستطلاع. سيؤدي التصويت البرمجي على استطلاع غير موجود أو منتهي الصلاحية إلى إرجاع خطأ Message Not Found.
  • التوقيت: تجنب التصويت فوراً (في غضون أجزاء من الثانية) بعد إنشاء استطلاع بواسطة مستخدم آخر. إضافة تأخير بسيط (1-2 ثانية) يحاكي وقت المعالجة الطبيعي ويضمن انتشار الاستطلاع بالكامل عبر شبكة واتساب.

2. إدارة منطق الإجابات المتعددة

معلمة votes هي مصفوفة لسبب وجيه.

  • مربعات الاختيار مقابل أزرار الاختيار: إذا تم إنشاء الاستطلاع الأصلي مع multipleAnswers: true، يمكن أن تحتوي مصفوفتك على عدة فهارس (مثلاً [0, 2]). أما إذا كان استطلاعاً بخيار واحد، فإن المصفوفات التي تحتوي على أكثر من عنصر ستؤدي عادةً إلى احتساب العنصر الأخير فقط من قبل واجهة واتساب.
  • اتساق تجربة المستخدم: تأكد من أن تصويتات البوت الخاصة بك تتماشى مع أي تصريحات نصية سابقة أدلى بها لتجنب الخلط لدى المشاركين البشريين.

3. قوة السحب الانتقائي

يسمح التصويت البرمجي بـ "الإجماع المؤقت".

  • سيناريو: يمكن للبوت الخاص بك التصويت لخيار ما أثناء "تحقيقه" في مشكلة، ثم سحب تصويته أو التبديل إلى خيار "النجاح" بمجرد انتهاء التحقيق. يوفر هذا مؤشراً مرئياً للتقدم يكون أكثر دقة واحترافية من إغراق الدردشة برسائل الحالة المتكررة.

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

بناء الإجماع المؤتمت

قم ببناء "بوت مدير" (Moderator Bot) يراقب استطلاعاً جماعياً. بمجرد وصول خيار محدد إلى حد معين (مثلاً 5 أصوات)، يمكن للبوت الإدلاء بتصويته لهذا الخيار لـ "إتمام الصفقة" ثم إطلاق رسالة تنسيق أو دعوة تقويم تلقائياً.

إعادة محاذاة المشاعر

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

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

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

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

  • الإدلاء بالأصوات أو تحديثها أو سحبها برمجياً في استطلاعات واتساب الأصلية.
  • دعم التصويت عبر سلاسل الخيارات الحرفية أو الفهارس الرقمية.
  • حصري للأتمتة المتقدمة وتكامل الذكاء الاصطناعي.
  • دعم كامل لبنيات استطلاعات الرأي متعددة الخيارات (checkbox) والخيارات الفردية (radio).
  • مزامنة في الوقت الفعلي مع شبكة واتساب لتحديثات واجهة المستخدم الفورية على أجهزة المستلمين.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

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

مثال:
string

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

مثال:
string

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

مثال:
string

المعرف الفريد لرسالة الاستطلاع

مثال:
array

مصفوفة من أسماء الخيارات المختارة أو فهارسها

مثال:

أمثلة الكود

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

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

Command Palette

Search for a command to run...