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

إرسال رسالة نصية

استخدم للإرسال الأساسي للرسائل النصية. المعلمات المطلوبة: instance_id، access_token، chatId، message.

POST
https://api.wawp.net/v2/send/text?access_token=YOUR_ACCESS_TOKEN&chatId=201234567890%40c.us&instance_id=123456789&message=Hi+from+Wawp&reply_to=false_111...AAAA

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

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

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

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

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

توصيات

  • قم بتضمين طريقة واضحة للمستخدمين لإلغاء الاشتراك في الاتصالات.

  • استخدم Webhooks لتتبع حالة التسليم إذا كان تطبيقك يتطلب تأكيدًا.

  • قم بتنفيذ استراتيجية تكرار مع تراجع أسي لسيناريوهات 'wawp_upstream_error'.

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

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

إرسال نص

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

عندما يصل طلب POST إلى هذه النقطة، يبدأ Wawp سير عمل عديم الحالة:

  1. التطبيع (Normalization): يتم تنظيف chatId (إزالة رموز + أو المسافات الزائدة) والتحقق منه مقابل جدول توجيه شبكة واتساب.
  2. تخزين النصوص مؤقتًا (Text Buffering): يتم تخزين سلسلة message مؤقتًا لمنع تجاوز سعة الذاكرة. يدعم واتساب ما يصل إلى 4096 حرفًا، ويقوم البروكسي الخاص بنا بفرض هذا الحد لضمان بقاء التسليم ذريًا.
  3. المعالجة المسبقة لـ Markdown: يحافظ Wawp على تنسيق Markdown الخاص بواتساب (مثل *bold* للخط العريض، _italic_ للمائل، ~strikethrough~ للشطب، وكُتل الكود code blocks). يتيح لك ذلك إرسال نصوص غنية ومنظمة دون الحاجة إلى أغلفة HTML أو XML معقدة.

🛡️ أفضل الممارسات الاستراتيجية للمطورين

1. نمط واجهة المستخدم المتفائلة (Optimistic UI Pattern)

للحصول على تجارب مستخدم عالية الجودة، لا تجعل المستخدم ينتظر استجابة API قبل عرض الرسالة في واجهتك الأمامية.

  • التنفيذ: عندما ينقر المستخدم على "إرسال"، قم فورًا بعرض الرسالة في واجهة الدردشة مع مؤشر "جاري الإرسال...". اتصل بـ /v2/send/start-typing قبل بضع ثوانٍ من طلب POST الفعلي لمحاكاة السلوك البشري. بمجرد أن تعيد /send/text معرف message_id، قم بتحديث حالة واجهة المستخدم إلى "تم الإرسال".

2. التعامل مع تعقيد الأحرف

إذا كنت ترسل سجلات تقنية، أو قصاصات برمجية، أو مجموعات أحرف غير لاتينية (العربية، الماندرين، إلخ)، فلاحظ ما يلي:

  • الترميز: يستخدم Wawp ترميز UTF-8 افتراضيًا. تأكد من أن خادم تطبيقك يرسل رؤوس Content-Type: application/json الصحيحة لمنع تلف الأحرف.
  • سلامة الاقتطاع: إذا تجاوز نصك 4000 حرف، نوصي بتقسيمه إلى عدة رسائل منطقية أو استخدام استراتيجية CLIP لاستضافة محتوى أطول على صفحة ويب.

3. استعادة الأخطاء وموثوقية الاتصال

في بعض الأحيان، قد تواجه شبكة واتساب تأخيرًا عابرًا.

  • مغالطة "2xx مقابل التسليم": تعني استجابة 200 OK من Wawp أنه تم قبول الرسالة بنجاح ووضعها في زمام الأمور للتسليم. هذا لا يضمن أن هاتف المستلم قيد التشغيل.
  • المراقبة: استخدم دائمًا Webhooks (message.ack) لتتبع متى تنتقل الحالة من "مرسل" (علامة صح واحدة) إلى "تم التسليم" (علامتان) وأخيرًا "تمت القراءة" (علامتان زرقاوان).

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

حقن المتغيرات والقوالب

نظرًا لأن Wawp عديم الحالة، يمكنك بسهولة بناء محرك قوالب من جانبك.

  • مثال: "مرحبًا {{name}}، طلبك رقم #{{order_id}} جاهز!"
  • التقنية: قم بإجراء استبدال السلسلة في خلفية تطبيقك قبل إرسال السلسلة النهائية إلى Wawp. هذا يبقي المنطق محليًا لقواعد عملك بينما يتعامل Wawp مع عبء التسليم الثقيل.

المحادثات المتسلسلة (Reply-to)

من خلال تضمين معلمة reply_to (معرف message_id لرسالة سابقة)، يمكنك إنشاء خيوط محادثة منظمة. هذا أمر بالغ الأهمية لـ:

  • أنظمة الدعم حيث يحتاج الوكيل إلى توضيح سؤال محدد للعميل.
  • المجموعات حيث تتم مناقشة مواضيع متعددة في وقت واحد.

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

  • الأحرف المحظورة: في حين أن الرموز التعبيرية (Emoji) مدعومة بالكامل، ابتعد عن أحرف التحكم منخفضة المستوى (\x00-\x1F) التي يمكن أن تطلق تنبيهات أمنية أو تتسبب في تعطل المحرك.
  • الرسائل الفارغة: إرسال message فارغ أو يتكون من مسافات فقط سيعيد خطأ 400 Bad Request. قم دائمًا بالتحقق من صحة حقول الإدخال.
  • تجاوز معدل الإرسال: إرسال 1000 رسالة نصية لنفس المستخدم في 60 ثانية هو علامة "بريد عشوائي" مضمونة. استخدم تأخيرًا معقولًا لـ "حماية المستهلك" (بحد أدنى ثانية واحدة بين الرسائل لنفس المستلم).

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

  • إرسال نصوص منظمة وغنية بدعم كامل لـ Markdown الخاص بواتساب.
  • دعم عالي للتزامن لأنظمة الإشعارات والتنبيهات.
  • تكامل سلس مع الردود/الخيوط عبر reply_to.
  • تتبع الأحداث في الوقت الفعلي من خلال توليد متسق لـ message_id.
  • دعم لجميع اللغات العالمية ومجموعات الرموز التعبيرية عبر UTF-8.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

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

مثال:
string

رمز وصول API

مثال:
string

معرف واتساب للمستلم (JID). يدعم الأفراد (@c.us)، المجموعات (@g.us)، والقنوات (@newsletter).

مثال:
string

نص الرسالة المراد إرسالها

مثال:
string—

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

مثال:

أمثلة الكود

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

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

Command Palette

Search for a command to run...