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

إرسال بطاقة جهة اتصال

إرسال بطاقات اتصال احترافية (vCards) إلى الدردشة. يدعم جهات اتصال فردية أو متعددة في فقاعة واحدة.

POST
https://api.wawp.net/v2/send/contact?access_token=YOUR_ACCESS_TOKEN&chatId=201234567890&contacts=%5B%0A++%7B%0A++++%22fullName%22%3A+%22Wawp+Support%22%2C%0A++++%22organization%22%3A+%22Wawp+HQ%22%2C%0A++++%22phoneNumber%22%3A+%22%2B201111111111%22%2C%0A++++%22whatsappId%22%3A+%22201111111111%22%0A++%7D%0A%5D&instance_id=123456789&reply_to=false_111...AAAA

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

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

تسجيل الدخول
اختبار /v2/send/contact
POST
POST

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

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

توصيات

  • قم بتضمين اسم منسق بشكل صحيح (خصائص N, FN) للحصول على أفضل توافق.

  • استخدم هذا لمشاركة أرقام خطوط الدعم بكفاءة.

الهوية المهنية: إتقان محرك بطاقة الاتصال (vCard)

في المنظومة المهنية، لا ينبغي أن تتعلق مشاركة معلومات الاتصال بكتابة أرقام الهواتف. تتيح لك نقطة النهاية /v2/send/contact مشاركة بطاقات العمل الرقمية (vCards) التفاعلية وسهلة الحفظ وعالية الدقة. من خلال أتمتة مشاركة بطاقات الاتصال، يمكنك تبسيط عملية "تسليم الوكيل"، أو توفير وصول فوري لخطوط المساعدة في حالات الطوارئ، أو مشاركة تفاصيل الفنيين المتخصصين باستدعاء API واحد.

إرسال بطاقة اتصال

🏗️ مسار تسلسل VCard

مشاركة جهة اتصال عبر Wawp هي أكثر من مجرد إرسال اسم. يدير محركنا عملية تسلسل متطورة لضمان التوافق مع مديري جهات الاتصال في كل من Android و iOS:

  1. ترميز مواصفات vCard: يأخذ Wawp مصفوفة JSON لجهات الاتصال الخاصة بك وينسخها إلى تنسيق vCard (VCF) v3.0 القياسي. هذا التنسيق معترف به عالميًا من قبل أنظمة تشغيل الأجهزة المحمولة، مما يضمن أنه عندما ينقر المستخدم على "حفظ"، يتم تعيين الحقول بشكل صحيح في دفتر عناوينهم المحلي.
  2. التحقق من الهوية: حقل whatsappId بالغ الأهمية. يستخدم محركنا هذا لربط vCard مباشرة بملف تعريف واتساب. يتيح ذلك للمستلم رؤية صورة الملف الشخصي لجهة الاتصال فورًا وبدء خيط رسائل بنقرة واحدة حتى دون حفظ الرقم أولاً.
  3. تجميع جهات اتصال متعددة: يدعم Wawp إرسال عدة جهات اتصال في "فقاعة رسالة" واحدة. يتم ذلك عن طريق ربط كتل VCF المتسلسلة في حمولة واحدة، مما يوفر عرض "فريق" أو "دليل" نظيف للمستخدم.

🛡️ أفضل الممارسات الاستراتيجية للهوية الرقمية

1. استراتيجية "الملف الشخصي المتكامل"

بطاقة الاتصال المختصرة للغاية تبدو مشبوهة للمستخدمين. لبناء سلطة العلامة التجارية:

  • بيانات وصفية غنية: قدم دائمًا organization (المنظمة) و fullName (الاسم الكامل).
  • الاحترافية: إذا كانت جهة الاتصال وكيلاً، فقم بتضمين قسمه (مثلاً "سارة - استشاري أول").
  • التنسيق: تأكد من أن phoneNumber يتضمن البادئة الدولية +. هذا يختلف عن whatsappId الذي هو مجرد الأرقام الرقمية المستخدمة لتوجيه الشبكة.

2. تبسيط تسليم الوكيل

في الانتقال من البوت إلى البشر:

  • التنفيذ: بدلاً من أن يقول البوت "تتحدث الآن مع مارك، رقمه هو 123"، اجعل النظام يستدعي تلقائياً /v2/send/contact لبطاقة اتصال مارك.
  • تأثير تجربة المستخدم: يعطي هذا العميل فقاعة "نقطة اتصال مهنية" واضحة يمكنه الرجوع إليها لاحقاً، مما يزيد من شفافية تدفق الدعم الخاص بك.

3. التحقق وسلامة أسماء الملفات

  • حدود الأحرف: ابقِ fullName أقل من 40 حرفاً. الأسماء الأطول قد تقتطع في معاينة الدردشة أو تؤدي إلى إدخالات غير مرتبة في دفتر العناوين.
  • استخدام الرموز التعبيرية: بينما الرموز التعبيرية مدعومة في حقل الاسم، استخدمها باعتدال. الرموز التعبيرية المفرطة في اسم vCard يمكن أن تتداخل أحياناً مع أرشفة البحث في تطبيق جهات الاتصال المحلي للمستخدم.

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

أدلة الموظفين في الشركات

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

برامج الإحالة والولاء

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

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

  • معرفات واتساب مشوهة: إذا كان whatsappId لا يتطابق مع حساب حقيقي، فسيتم تعطيل زر "رسالة" في vCard على هاتف المستلم. تحقق دائمًا من معرفات وكلائك قبل المشاركة.
  • تضارب الرؤوس: إذا قدمت سلسلة vcard مباشرة (عبر الحقول القديمة)، فتأكد من أنها تبدأ بـ BEGIN:VCARD وتنتهي بـ END:VCARD. سيعيد Wawp خطأ Serialization Error إذا كانت الكتلة مشوهة.
  • ارتباك رقم الهاتف: ينسى المستخدمون غالباً + في حقل phoneNumber. بينما يحاول Wawp تطبيع ذلك، قدمه صراحة لضمان أن هاتف المستخدم يتعرف عليه كرابط اتصال قابل للنقر.

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

  • تقديم بطاقات اتصال واتساب (vCards) أصلية وتفاعلية.
  • دعم لتجميع جهات اتصال متعددة (موظفين/دليل) في رسالة واحدة.
  • وظيفة "حفظ جهة الاتصال" و "رسالة" بنقرة واحدة للمستخدم النهائي.
  • تسلسل تلقائي لـ VCF v3.0 للتوافق العالمي مع iOS/Android.
  • تكامل سلس مع الخيوط/الردود عبر معلمة reply_to.
  • مشاركة هوية عالية الدقة مع دعم كامل لحقول المنظمة والمسمى الوظيفي.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

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

مثال:
string

رمز وصول API

مثال:
string

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

مثال:
array

مصفوفة من كائنات جهات الاتصال التي تحتوي على معلومات الاسم والهاتف.

مثال:
string—

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

مثال:

أمثلة الكود

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

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

Command Palette

Search for a command to run...