إرسال رابط معاينة (Link Preview)

إرسال رسالة مع بطاقة معاينة رابط غنية ومخصصة.

POST

https://api.wawp.net/v2/send/link-preview?access_token=123456789&chatId=201234567890&description=The+ultimate+platform+for+WhatsApp+automation.&instance_id=123456789&linkPreviewHighQuality=true&reply_to=null&text=Check+out+our+new+website%21&thumbnail=https%3A%2F%2Fwawp.net%2Fsamples%2Fcat.jpg&title=Wawp+-+Advanced+WhatsApp+API&url=https%3A%2F%2Fwawp.net

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

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

تسجيل الدخول

اختبار /v2/send/link-preview

يدعم

POSTGET

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

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

محتوى غني

يولد بطاقة معاينة بالعنوان والوصف والصورة.

زمن الوصول

يستغرق إنشاء الرابط وقتًا إضافيًا؛ ترسل الرسالة بشكل أبطأ قليلاً.

توصيات

تأكد من أن الرابط المستهدف يحتوي على علامات Open Graph (OG) صالحة.
ارجع إلى رسالة نصية قياسية إذا فشل إنشاء المعاينة.

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

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

🏗️ محرك إنشاء بطاقات الروابط

محرك الروابط في Wawp لا يكتفي "بكشط" الوجهة؛ بل يقوم بنشاط بتركيب بطاقة OpenGraph اصطناعية:

تجاوز البيانات الوصفية: على عكس مشاركة الروابط العادية، يتيح لك Wawp تجاوز title و description و thumbnail حتى لو لم يكن لموقع الوجهة بيانات وصفية أو كان يحظر برامج الزحف. يضمن ذلك أن يظهر رابطك دائماً باحترافية.
جلب الصور الثنائية: يقوم المحرك بجلب صورتك المصغرة المخصصة (thumbnail) وتحسينها لتطبيق واتساب للهاتف المحمول. يدعم صيغ JPEG و PNG، مما يضمن تحميل الصورة المصغرة فوراً حتى في الاتصالات الضعيفة.
المعاينة عالية الجودة: يؤدي تفعيل linkPreviewHighQuality: true إلى تشغيل وضع عرض متخصص. إذا كان هاتف المستلم يدعم ذلك، فسيقوم واتساب بعرض بطاقة صورة أكبر بكثير (تشبه رسالة صور أصلية) بدلاً من الأيقونة المربعة الصغيرة. هذا يزيد بشكل كبير من "المساحة البصرية" التي تشغلها رسالتك في واجهة المستخدم.

🛡️ أفضل الممارسات الاستراتيجية لمعدلات النقر (CTR)

1. العنوان كـ "توجيه للعمل"

يجب أن يكون العنوان (title) موجهاً وليس مجرد تسمية.

مثال: بدلاً من "مدونتنا"، استخدم "🔥 اقرأ الآن: 5 طرق لتوسيع API الخاص بك".
تأثير تجربة المستخدم: يمكن للعناوين المليئة بالحركة جنباً إلى جنب مع بطاقة معاينة عالية الجودة زيادة معدل النقر بنسبة تصل إلى 400% مقارنة برابط نصي خام.

2. تكوين الصورة المصغرة

الصورة المصغرة هي المرساة البصرية للبطاقة.

النسبة: استخدم صوراً بنسبة 1:1 (مربعة) للمعاينة القياسية أو 1.91:1 (عريضة) إذا كنت تستخدم علامة linkPreviewHighQuality.
الوضوح: تجنب وضع نصوص صغيرة في الصورة المصغرة. نظراً لأن الصور المصغرة يتم ضغطها وعرضها بحجم صغير على شاشات الجوال، استخدم أيقونات بارزة أو صوراً واضحة تمثل وجهة الرابط.

3. شفافية الروابط ونظافتها

تضمين النص: يتيح لك حقل text تقديم رسالة سابقة (مثلاً "اطلع على هذا:"). نوصي بتكرار الرابط في نهاية حقل النص كبديل احتياطي في الحالات النادرة التي يكون فيها جوال المستخدم معطلاً لمعاينة الروابط.
التتبع: استخدم معلمات UTM في رابطك (url) (مثلاً ?utm_source=whatsapp&utm_medium=wawp). يتيح لك ذلك قياس مدى فعالية حملات API الخاصة بك في لوحة تحليلاتك.

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

معاينات الدفع الديناميكية

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

تقارير مخصصة ومحتوى محمي

إذا كنت تقدم تقارير PDF مخصصة أو روابط آمنة للوحة التحكم، استخدم /v2/send/link-preview لإنشاء "بطاقة لوحة تحكم". استخدم الوصف لإظهار مقتطف من بيانات المستخدم (مثلاً "توفيراتك للربع الأول: 1,250 دولاراً")، مما يشجعهم على النقر للوصول للموقع الكامل.

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

برامج الزحف المحظورة: إذا كنت تعتمد على المعاينة التلقائية (عدم توفير صورة مصغرة مخصصة)، فقد تفشل شبكة واتساب في كشط المواقع المحمية بـ Cloudflare أو شاشات تسجيل الدخول. دائماً قدم رابط صورة مصغرة مخصصة لضمان موثوقية 100%.
أخطاء نوع الصورة: استخدام رابط صورة مصغرة يشير لملف WebP أو SVG سيؤدي غالباً لظهور أيقونة "رابط" عامة بدون صورة. التزم بصيغة JPEG القياسية لأعلى توافق.
متطلبات البروتوكول: يجب أن يستخدم كل من url و thumbnail بروتوكول HTTPS. الروابط غير الآمنة (HTTP) غالباً ما يتم رفضها أو تظهر تحذيرات أمنية للمستلم.

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

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

البارامترات

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

محتوى الطلب

يرسل كـ JSON

`string`		المعرف الفريد لجلسة واتساب مثال:
`string`		رمز وصول API الخاص بك مثال:
`string`		رقم الهاتف المستهدف مع كود الدولة مثال:
`string`		الرابط المراد معاينته مثال:
`string`		نص اختياري مرافق للرابط. مثال:
`string`		رابط لصورة مصغرة مخصصة (JPEG/PNG) مثال:
`string`		عنوان مخصص لبطاقة المعاينة مثال:
`string`		وصف مخصص لبطاقة المعاينة مثال:
`boolean`		محاولة إنشاء معاينة كبيرة عالية الجودة مثال:
`string`	—	معرف الرسالة التي تقوم بالرد عليها مثال:

أمثلة الكود

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

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/send/link-preview";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "123456789"
6}).toString();
7const body = {
8  "chatId": "201234567890",
9  "url": "https://wawp.net",
10  "text": "Check out our new website!",
11  "thumbnail": "https://wawp.net/samples/cat.jpg",
12  "title": "Wawp - Advanced WhatsApp API",
13  "description": "The ultimate platform for WhatsApp automation.",
14  "linkPreviewHighQuality": "true",
15  "reply_to": "null"
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...