إرسال حدث (Event)

يرسل رسالة حدث (تقويم) إلى الدردشة. يمكن للمستخدمين النقر فوق الحدث لعرض التفاصيل، أو إضافته إلى تقويمهم، أو الانضمام إلى مكالمة.

POST

https://api.wawp.net/v2/send/event?access_token=YOUR_ACCESS_TOKEN&chatId=201234567890&event.description=Discussing+Q1+Roadmap&event.endTime=1735923600&event.extraGuestsAllowed=true&event.location.name=Meeting+Room+A&event.name=Team+Meeting+%F0%9F%93%85&event.startTime=1735920000&instance_id=YOUR_INSTANCE_ID&reply_to=false_111...AAAA

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

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

تسجيل الدخول

اختبار /v2/send/event

يدعم

POST

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

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

طوابع Unix الزمنية

تحقق مرتين من منطق الطوابع الزمنية الخاصة بك. تأكد من إرسال الثواني (مثل 1735920000) وليس الملي ثانية.

توصيات

Use "reply_to" to maintain conversation context.
Handle distinct message types (text, image, video) appropriately.
Implement a robust retry mechanism for failed sends.

إدارة الوقت: إتقان محرك أحداث واتساب

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

إرسال حدث

🏗️ دورة حياة الحدث وهيكله

رسالة الحدث هي أكثر من مجرد إشعار؛ إنها كائن حالة مستمر داخل الدردشة:

دقة الطوابع الزمنية: يستخدم المحرك طوابع Unix الزمنية (بالثواني) لتعريف startTime و endTime. يتحقق Wawp من أن وقت الانتهاء يأتي بعد وقت البدء، ويتولى تحويل هذه الطوابع الزمنية إلى المنطقة الزمنية المحلية لهاتف المستلم تلقائياً.
تجميع البيانات الوصفية: يتم تجميع event.name و event.description و event.location.name في حزمة حدث واتساب أصلية. هذه الحزمة تفاعلية—يمكن للمستخدمين النقر عليها لتوسيع عرض "التفاصيل الكاملة" الذي يظل متاحاً حتى بعد تحرك الدردشة للأمام.
إدارة الضيوف: تعد علامة extraGuestsAllowed إشارة هيكلية. إذا كانت صحيحة، فإنها تشير للمستخدم بأن الحدث مفتوح لمشاركة أوسع، وغالباً ما تُستخدم في الندوات عبر الإنترنت أو التجمعات المجتمعية.

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

1. الوصف كـ "نداء للعمل" (Call-to-Action)

حقل event.description هو أثمن حقل نصي لديك.

الروابط العميقة: إذا كان الحدث اجتماعاً افتراضياً (Zoom، Google Meet، مكالمة WhatsApp)، فقم بتضمين رابط الانضمام مباشرة في الوصف. ستتعرف أنظمة تشغيل الهواتف المحمولة على الرابط وتجعله قابلاً للنقر داخل عرض تفاصيل الحدث.
المشاركة: استخدم الوصف لتقديم جدول أعمال رفيع المستوى. بما أن الحدث يستمر في الجزء العلوي من الدردشة أو في قسم "الوسائط/الروابط/المستندات"، فإنه يعمل كنقطة مرجعية دائمة للمستخدم.

2. نزاهة المنطقة الزمنية

أحد أكبر أسباب فوات المواعيد هو الارتباك في المناطق الزمنية.

المعيار العالمي: يتوقع Wawp طوابع Unix الزمنية بصيغة UTC. لا ترسل أبداً طوابع زمنية بتنسيق محلي دون تطبيعها أولاً إلى عهد UTC.
تجربة المستخدم: لأن Wawp يسلم طابع UTC لشبكة واتساب، فإن هاتف المستلم سيعرض الوقت تلقائياً بوقته المحلي (مثلاً ، إذا أرسلت حدثاً للساعة 3 مساءً UTC، سيرى مستخدم في لندن الساعة 3 مساءً، بينما يرى مستخدم في نيويورك الساعة 10 صباحاً).

3. وضوح الموقع (مادي مقابل افتراضي)

الأحداث المادية: استخدم event.location.name لرقم الغرفة أو اسم المبنى.
الأحداث الافتراضية: اضبط اسم الموقع على "💻 اجتماع افتراضي" أو "🎥 بث مباشر". يوفر هذا سياقاً بصرياً فورياً قبل أن يفتح المستخدم التفاصيل.

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

التسجيل المؤتمت في الندوات (Webinars)

عندما يسجل مستخدم في ندوة عبر بوت، أطلق /v2/send/event فوراً. يتيح ذلك للمستخدم النقر على "إضافة إلى التقويم" بينما لا يزال اهتمامه في ذروته. ادمج هذا مع معلمة reply_to لربط بطاقة الحدث برسالة "تم التسجيل بنجاح".

حجز مواعيد الخدمة

لصالونات الحلاقة، الأطباء، أو خدمات الإصلاح، أرسل بطاقة حدث بمجرد تأكيد الموعد. المظهر الاحترافي لبطاقة الحدث يزيد بشكل كبير من "الجودة المدركة" للخدمة ويقلل من معدل "عدم الحضور" من خلال التكامل مع أداة التخطيط الأساسية للمستخدم (تقويمه الشخصي).

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

الثواني مقابل الملي ثانية: خطأ تقني شائع هو إرسال Date.now() الخاص بـ JS (وهو بالملي ثانية) بدلاً من ثواني Unix المطلوبة. سيؤدي هذا إلى جدولة حدث بعد آلاف السنين في المستقبل. اقسم دائماً القيمة على 1000.
المدد القصيرة: بينما يسمح واتساب بأحداث قصيرة جداً، نوصي بمدة أدناها 15 دقيقة لضمان أن تكون كتلة التقويم بارزة بصرياً بما يكفي ليلاحظها المستخدم.
تضارب التداخل: لا يمنعك واتساب من إرسال أحداث متداخلة، لكن يجب على نظامك فعل ذلك. إذا كانت الجلسة مشغولة بالفعل، ففكر في استخدام استطلاع أولاً للعثور على فتحة متاحة قبل إرسال بطاقة الحدث النهائية.

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

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

البارامترات

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

محتوى الطلب

يرسل كـ JSON

`string`		المعرف الفريد لجلسة واتساب مثال:
`string`		رمز وصول API مثال:
`string`		رقم واتساب للمستلم مثال:
`string`		اسم الحدث (مثل اجتماع الفريق 📅) مثال:
`string`		وصف الحدث مثال:
`number`		وقت البدء (طابع Unix الزمني بالثواني) مثال:
`number`		وقت الانتهاء (طابع Unix الزمني بالثواني) مثال:
`string`		اسم الموقع (مثل غرفة الاجتماعات أ) مثال:
`boolean`		ما إذا كان يسمح بضيوف إضافيين مثال:
`string`	—	معرف الرسالة التي تقوم بالرد عليها مثال:

أمثلة الكود

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

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/send/event";
3const params = new URLSearchParams({
4  "instance_id": "YOUR_INSTANCE_ID",
5  "access_token": "YOUR_ACCESS_TOKEN"
6}).toString();
7const body = {
8  "chatId": "201234567890",
9  "event.name": "Team Meeting 📅",
10  "event.description": "Discussing Q1 Roadmap",
11  "event.startTime": "1735920000",
12  "event.endTime": "1735923600",
13  "event.location.name": "Meeting Room A",
14  "event.extraGuestsAllowed": "true",
15  "reply_to": "false_111...AAAA"
16};
17
18fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
19  method: "POST",
20  headers: { "Content-Type": "application/json" },
21  body: JSON.stringify(body)
22})
23  .then(async (response) => {
24    if (response.ok) {
25      const data = await response.json();
26      console.log("Success:", data);
27      return data;
28    }
29    
30    // Error Handling
31    if (response.status === 400) {
32      console.error("Error 400: طلب غير صالح - معاملات مطلوبة مفقودة");
33    }
34    if (response.status === 400) {
35      console.error("Error 400: Bad Request - Invalid Number (Egypt)");
36    }
37    if (response.status === 400) {
38      console.error("Error 400: Bad Request - Invalid Number (Saudi Arabia)");
39    }
40    if (response.status === 400) {
41      console.error("Error 400: Bad Request - Invalid Number (Unknown)");
42    }
43    if (response.status === 400) {
44      console.error("Error 400: طلب غير صالح (تنسيق XML)");
45    }
46    if (response.status === 400) {
47      console.error("Error 400: طلب غير صالح (نص عادي)");
48    }
49    if (response.status === 401) {
50      console.error("Error 401: غير مصرح - مفتاح الوصول غير صالح أو مفقود");
51    }
52    if (response.status === 401) {
53      console.error("Error 401: غير مصرح (تنسيق XML)");
54    }
55    if (response.status === 404) {
56      console.error("Error 404: غير موجود - الجلسة غير موجودة");
57    }
58    if (response.status === 404) {
59      console.error("Error 404: غير موجود (تنسيق XML)");
60    }
61    if (response.status === 429) {
62      console.error("Error 429: طلبات كثيرة جداً - تم تجاوز حد المعدل");
63    }
64    if (response.status === 500) {
65      console.error("Error 500: خطأ في الخادم الداخلي - فشل غير متوقع");
66    }
67    if (response.status === 500) {
68      console.error("Error 500: خطأ في الخادم الداخلي (HTML)");
69    }
70    if (response.status === 502) {
71      console.error("Error 502: بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي");
72    }
73    if (response.status === 502) {
74      console.error("Error 502: بوابة غير صالحة (تنسيق XML)");
75    }
76
77    const errorText = await response.text();
78    console.error(`Error ${response.status}: ${errorText}`);
79  })
80  .catch((error) => console.error("Network Error:", error));

عينات تفاعليةUTF-8

Ln 80, Col 1javascript

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

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

تم إرسال الرسالة بنجاح

3 نسخ

النوع:

application/json

object *

string *

object *

number *

boolean *

string *

number *

string *

boolean *

number *

boolean *

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": {
  }
}

طلب غير صالح - معاملات مطلوبة مفقودة

6 نسخ

غير مصرح - مفتاح الوصول غير صالح أو مفقود

2 نسخ

Command Palette

Search for a command to run...