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

إرسال الموقع

إرسال موقع جغرافي ثابت إلى الدردشة.

POST
https://api.wawp.net/v2/send/location?access_token=123456789&chatId=201234567890&instance_id=123456789&latitude=38.8937255&longitude=-77.0969763&message=123+Main+St%2C+New+York&reply_to=null&title=Our+office

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

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

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

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

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

توصيات

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

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

تحديد المواقع بدقة: إتقان محرك الموقع الجغرافي

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

🏗️ مسار الموقع الجغرافي: من البيانات إلى الدبوس

عندما تستدعي نقطة النهاية /send/location، يقوم محرك Wawp بترجمة البيانات الجغرافية الخام إلى فقاعة تفاعلية غنية على هاتف المستلم:

  1. التحقق من الإحداثيات: يقبل المحرك خطوط العرض (latitude) وخطوط الطول (longitude) كسلاسل عشرية. ويتحقق من وقوع هذه الإحداثيات ضمن النطاقات الصالحة (-90 إلى 90 لخط العرض، و-180 إلى 180 لخط الطول).
  2. حقن البيانات الوصفية: يتم حقن حقلي title (العنوان) و message (الرسالة/العنوان المفصل) في البيانات الوصفية للرسالة. لا تظهر هذه الحقول على الفقاعة فحسب؛ بل تُستخدم غالبًا كـ "تسمية" عندما ينقر المستخدم على الدبوس ويفتحه في تطبيقات خارجية مثل خرائط جوجل أو Waze.
  3. العرض التفاعلي: يضمن Wawp عرض الرسالة الناتجة مع صورة مصغرة لخريطة قابلة للنقر. يتم إنشاء هذه الصورة المصغرة بواسطة شبكة واتساب بناءً على الإحداثيات المقدمة، مما يمنح المستخدم "سياقًا" بصريًا فوريًا للمنطقة المحيطة.

🛡️ أفضل الممارسات الاستراتيجية للبيانات الجغرافية

1. الدقة العشرية (قاعدة "سقف المبنى")

في بيانات الموقع، الدقة هي كل شيء.

  • إجراء المطور: استخدم 6 منازل عشرية على الأقل لإحداثياتك (مثل 38.893725). هذا المستوى من الدقة دقيق بما يصل إلى 0.1 متر تقريبًا - وهو الفرق بين سقوط الدبوس على سطح مبنى أو سقوطه في منتصف تقاطع مزدحم.
  • الأمان: تجنب تقريب الإحداثيات في خلفية تطبيقك، حيث أن التغييرات الطفيفة حتى في المنزلة العشرية الرابعة يمكن أن تزيح الموقع بعشرات الأمتار.

2. صياغة تسميات ذات معنى

حقلا title و message هما فرصتك لتوفير وضوح لهوية علامتك التجارية.

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

3. المواقع الثابتة مقابل الحية

  • الدبابيس الثابتة: ترسل نقطة النهاية هذه دبوسًا ثابتًا. إنه يمثل "لقطة" محددة في المكان.
  • الموقع الحي (Live Location): لاحظ أن Wawp يركز حاليًا على الدبابيس الثابتة لتدفقات الأعمال عالية التزامن. إذا كانت حالة الاستخدام الخاصة بك تتطلب نقطة متحركة في الوقت الفعلي (الموقع الحي)، نوصي بدمج الدبابيس الثابتة مع تحديثات نصية منتظمة أو روابط تتبع خارجية عبر /v2/send/link-preview.

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

دعم توصيل الميل الأخير

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

العروض الشخصية المعتمدة على الموقع (Geo-Fencing)

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

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

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

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

  • إرسال دبابيس خريطة ثابتة تفاعلية وقابلة للنقر مع عناوين وأسماء مخصصة.
  • دعم عالي الدقة للإحداثيات العشرية (خط العرض/خط الطول).
  • تكامل سلس مع خرائط جوجل، وخرائط آبل، و Waze للمستخدم النهائي.
  • دعم لتداخل الخيوط المعقدة عبر معلمة reply_to.
  • تقارير نجاح موثوقة مع توليد معرف message_id فريد لتتبع التسليم الكامل.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

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

مثال:
string

رمز وصول API

مثال:
string

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

مثال:
string

خط العرض الجغرافي (مثل 38.8937255)

مثال:
string

خط الطول الجغرافي (مثل -77.0969763)

مثال:
string

اسم المكان (مثل 'مكتبنا الرئيسي')

مثال:
string

العنوان أو نص وصفي إضافي

مثال:
string—

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

مثال:

أمثلة الكود

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

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

Command Palette

Search for a command to run...