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

إرسال ملف PDF

عامل ملفات PDF كعمليات تسليم ملفات عامة عبر نقطة نهاية الملف. تتطلب file.url وشرح مطلوب.

POST
https://api.wawp.net/v2/send/pdf?access_token=YOUR_ACCESS_TOKEN&caption=Here%27s+your+requested+document.&chatId=201234567890%40c.us&file%5Bfilename%5D=document.pdf&file%5Bmimetype%5D=application%2Fpdf&file%5Burl%5D=https%3A%2F%2Fwawp.net%2Fsamples%2Ffile-sample.pdf&instance_id=123456789&reply_to=false_111...AAAA

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

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

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

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

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

توصيات

  • قم بضغط ملفات PDF الكبيرة قبل الإرسال لضمان التسليم.

  • استخدم أسماء ملفات وصفية؛ يرى المستخدمون هذا عند التنزيل.

سلامة المستندات: تمكين محرك رسائل PDF

في عالم أتمتة الأعمال، تعد ملفات PDF الوسيلة الأساسية للبيانات عالية القيمة - الفواتير، العقود، التقارير الطبية، والأدلة التقنية. تم تصميم نقطة نهاية /v2/send/pdf لسد الفجوة بين التخزين السحابي الخاص بك ومحادثة واتساب الخاصة بمستخدمك، مما يضمن وصول المستندات المهمة مع الحفاظ على سلامتها وتنسيقها. على عكس رسائل الوسائط التي يتم ضغطها غالبًا، يتعامل Wawp مع ملفات PDF كمستندات موثوقة، مع الحفاظ على بنيتها الثنائية للاستخدام المهني.

إرسال PDF

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

عندما تبدأ عملية نقل PDF، يتبع محرك مستندات Wawp بروتوكولاً متخصصًا:

  1. فحص الرؤوس (Header Inspection): قبل تنزيل الملف كاملاً، يفحص Wawp رأس Content-Type للتأكد من توافقه مع application/pdf. هذا يمنع خطأ "الملف المشوه" الذي يحدث إذا قدم الخادم بالخطأ صفحة HTML بدلاً من PDF أثناء خطأ عابر.
  2. التسمية الموثوقة: معلمة file[filename] بالغة الأهمية. يقوم Wawp بحقن هذا الاسم في بيانات واتساب الوصفية، مما يضمن أنه عندما يحفظ المستخدم المستند، فإنه يحتفظ بالاسم المهني الذي عينته له (مثل Inv_2025_001.pdf) بدلاً من معرف فريد عشوائي.
  3. ارتباط الشرح: يتيح لك Wawp إرفاق شرح غني بتنسيق Markdown بالمستند. هذا مثالي لتقديم التعليمات (مثلاً "يرجى التوقيع وإعادته لهذه الدردشة") دون إرسال رسالة نصية منفصلة غير متصلة.

🛡️ أفضل الممارسات الاستراتيجية لتدفق مستندات الشركات

1. نهج الأمان أولاً

بما أن ملفات PDF غالبًا ما تحتوي على معلومات شخصية حساسة (PII):

  • روابط قصيرة الأجل: استضف ملفات PDF الخاصة بك على عناوين URL تنتهي صلاحيتها بعد وقت قصير من اكتمال النقل. يحتاج Wawp فقط إلى الوصول لبضع ثوانٍ لجلب الملف وتسليمه لشبكة واتساب.
  • سياسة عدم التسجيل: يلتزم Wawp بـ سياسة عدم الاحتفاظ بالأسرار. نحن لا نقوم بأرشفة محتويات ملفات PDF الخاصة بك. بمجرد استلامنا لتأكيد "تم الإرسال" من WhatsApp WebSocket للواتساب، يتم مسح المخزن المؤقت الثنائي من ذاكرة المحرك المتطايرة.

2. استراتيجية حجم الملف والتحسين

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

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

3. معالجة الأخطاء والتحقق

  • مهلات المصدر: بالنسبة لملفات PDF الكبيرة جداً، تأكد من أن خادم الملفات لديه نطاق ترددي كافٍ لخدمة الملف بالكامل لـ Wawp في غضون 15-20 ثانية.
  • مراقبة Webhook: استمع لأحداث message.ack. بالنسبة لملف PDF، تعد حالة "تم التسليم" تأكيدك على أن المستند بأمان على جهاز المستخدم المشفر.

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

الفوترة والتحصيل المؤتمت

قم بدمج هذه النقطة مع نظام الفوترة الخاص بك. بمجرد معالجة الدفعة، قم بتوليد ملف PDF وأرسله عبر Wawp. يمكن استخدام معلمة reply_to لربط الفاتورة برسالة "تأكيد الدفع" السابقة للعميل، مما يخلق مسار تدقيق مهني للمستخدم.

سير العمل القانوني والتعاقدي

أرسل العقود للمراجعة الرقمية. استخدم حقل caption لشرح الشروط باختصار. نظرًا لأن Wawp يدعم مجموعات الأحرف الدولية، يمكن أن تدعم شروحاتك المصطلحات القانونية بأي لغة مع الحفاظ على السلامة الهيكلية لمرفق PDF.

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

  • نوع MIME غير صالح: إذا أرسل خادمك text/html (غالبًا بسبب صفحة 404) ولكنك حددت application/pdf، فسينهي Wawp الطلب لمنع إرسال ملفات تالفة لمستخدميك.
  • أسماء ملفات معقدة: تجنب استخدام رموز تعبيرية أو أحرف غير ASCII في سلسلة file[filename]. بينما يدعمها Wawp، قد تفشل بعض قارئات PDF القديمة على Android في فتح ملفات بأسماء معقدة.
  • واجهة "المرفق فقط": ذكر مطوري الواجهة الأمامية لديك بأن ملفات PDF لا تظهر معاينة مرئية في فقاعة الدردشة (على عكس الصور). استخدم شرحًا وصفيًا لإخبار المستخدم بماهية الملف قبل تنزيله.

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

  • تقديم مستندات PDF احترافية مع أسماء ملفات وشروحات مخصصة.
  • دعم للملفات الكبيرة (حتى 100 ميجابايت) مع جلب موثوق من مصادر HTTPS.
  • دعم كامل لـ Markdown في شروحات وتوجيهات المستندات.
  • تكامل سلس مع خيوط المحادثة عبر reply_to.
  • تتبع تسليم متسق من خلال توليد معرف message_id فريد ودعم Webhook.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

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

مثال:
string

رمز وصول API

مثال:
string

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

مثال:
string

عنوان URL متاح للعامة عبر HTTPS لملف PDF

مثال:
string

اسم الملف للمستند

مثال:
string

نوع MIME (مثلاً application/pdf)

مثال:
string

الشرح التوضيحي للمستند

مثال:
string—

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

مثال:

أمثلة الكود

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

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/send/pdf";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "YOUR_ACCESS_TOKEN"
6}).toString();
7const body = {
8  "chatId": "201234567890@c.us",
9  "file[url]": "https://wawp.net/samples/file-sample.pdf",
10  "file[filename]": "document.pdf",
11  "file[mimetype]": "application/pdf",
12  "caption": "Here's your requested document.",
13  "reply_to": "false_111...AAAA"
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": {
  }
}
طلب غير صالح - معاملات مطلوبة مفقودة
غير مصرح - مفتاح الوصول غير صالح أو مفقود
غير موجود - الجلسة غير موجودة
طلبات كثيرة جداً - تم تجاوز حد المعدل
خطأ في الخادم الداخلي - فشل غير متوقع
بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي
الموضوع السابقإرسال صورة
الموضوع التاليإرسال رسالة قائمة (Menu)

Command Palette

Search for a command to run...