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

إيقاف الكتابة (Stop Typing)

إزالة حالة 'يكتب الآن...' أو 'يسجل مقطعاً صوتياً...' من الدردشة.

POST
https://api.wawp.net/v2/send/stop-typing?access_token=YOUR_ACCESS_TOKEN&chatId=201234567890%40c.us&instance_id=123456789

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

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

تسجيل الدخول
اختبار /v2/send/stop-typing
POST
POST

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

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

توصيات

  • Consult the official documentation for detailed parameter descriptions.

  • Test endpoints in a sandbox environment before production.

  • Keep your API client library up to date.

تنظيف الحالة: إتقان محرك "إيقاف الكتابة"

تعد نقطة النهاية /v2/send/stop-typing "فريق التنظيف" الأساسي في نظام تواجد Wawp. برغم بساطة هدفها—وهو إزالة مؤشرات "يكتب الآن..." أو "يسجل مقطعاً صوتياً..."—إلا أنها تلعب دوراً حاسماً في الحفاظ على الاحترافية في تكاملك مع واتساب. في بيئة دعم عملاء أو مبيعات عالية المخاطر، يعد مؤشر "يكتب الآن..." الذي يستمر لفترة طويلة دون رسالة ناتجة فشلاً كبيراً في تجربة المستخدم يشير إلى تعطل النظام أو تردد الوكيل.

🏗️ مسار إنهاء التواجد

عندما تستدعي /stop-typing صراحة، يقوم Wawp بتنفيذ عملية تنظيف منسقة:

  1. إشارة الإيقاف (PAUSE): يرسل المحرك حزمة PAUSE متخصصة إلى المستهدف chatId. توجه هذه الحزمة عميل واتساب الخاص بالمستلم لإخفاء جميع مؤشرات التواجد فوراً.
  2. تجاوز المهلات التلقائية: بينما تمتلك واتساب مهلة تلقائية (عادة من 10 إلى 20 ثانية)، توفر الاستدعاءات الصريحة لـ /stop-typing استجابة فورية. هذا أمر بالغ الأهمية للتدفقات الحوارية سريعة الوتيرة حيث تتغير الحالات بسرعة.
  3. مسح التخزين المؤقت الداخلي: يقوم Wawp بمسح مخزن تتبع التواجد للجلسة المحلية لضمان معاملة طلبات الكتابة اللاحقة كبدايات جديدة، مما يمنع "تأتأة التواجد" على واجهة مستخدم المستلم.

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

1. الإيقاف التلقائي عند إرسال رسالة

من المفاهيم الخاطئة الشائعة أنه يجب عليك استدعاء /stop-typing مباشرة قبل إرسال رسالة.

  • حقيقة: إرسال أي رسالة (نص، صورة، PDF، إلخ) إلى دردشة يؤدي تلقائياً إلى إطلاق سلوك "إيقاف الكتابة" على شبكة واتساب.
  • تحسين: لتوفير استدعاءات API وتقليل التأخير، لا تستدعِ /v2/send/stop-typing قبل أو بعد إرسال رسالتك النهائية. تسليم الرسالة نفسها هو الطريقة الأكثر كفاءة لمسح الحالة.

2. التعامل مع إلغاء سير العمل

هذه هي حالة الاستخدام الأكثر أهمية لنقطة النهاية الصريحة للإيقاف.

  • سيناريو: يبدأ الوكيل في كتابة رد في CRM الخاص بك ولكنه يقرر بعد ذلك أن الاستفسار ينتمي إلى قسم آخر. يغلق علامة تبويب الدردشة أو ينقل التذكرة.
  • أفضل ممارسة: يجب أن يقوم CRM الخاص بك تلقائياً بتشغيل /v2/send/stop-typing كلما غادر تركيز الوكيل دردشة كانت في حالة "كتابة" سابقاً. هذا يمنع تأثير "الوكيل الوهمي" حيث يرى العميل شخصاً يكتب لعدة دقائق دون نتيجة.

3. التعافي من فشل الذكاء الاصطناعي

إذا تعطل نظام الذكاء الاصطناعي الخلفي الخاص بك أو أرجع خطأً أثناء تفعيل مؤشر "يكتب الآن..."، يجب على نظامك التعامل مع التنظيف.

  • التنفيذ: غلف منطق توليد الذكاء الاصطناعي في كتلة try...catch...finally. في قسم finally، إذا لم يتم إرسال أي رسالة بنجاح، قم بتشغيل /v2/send/stop-typing. يضمن ذلك أنه حتى في حالة حدوث عطل، لن يظل العميل محدقاً في حالة كتابة أبدية.

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

تجربة مستخدم "ما بعد البحث"

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

مزامنة نقل الوكيل

عند نقل دردشة بين وكلاء بشريين، قد يرغب الوكيل الثاني في "استلام" الخيط بهدوء. يضمن تشغيل stop-typing أثناء التسليم أن يكون الانتقال سلساً بصرياً للعميل، دون وجود مؤشرات متداخلة أو متضاربة من جلستين مختلفتين.

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

  • تأخير العد المزدوج: إذا كانت شبكتك بطيئة، فإن استدعاء /stop-typing متبوعاً برسالة مباشرة قد يتسبب في وصول الرسالة قبل معالجة إشارة التوقف، مما يؤدي إلى ارتعاش بصري بسيط. الحل: اعتمد على خاصية "الإيقاف التلقائي" للرسائل كلما أمكن ذلك.
  • الحذر من حدود المعدل: بينما إشارات التواجد خفيفة الوزن، لا تزال واتساب تتبع وتيرة هذه الحزم المتخصصة. تجنب إرسال أكثر من 3 استدعاءات stop-typing في الثانية إلى نفس الدردشة لضمان محافظة مثيلك على درجة ثقة عالية.
  • الضوضاء في بيئة المجموعات: في المجموعات التي تضم أكثر من 200 مشارك، يمكن أن تكون مؤشرات التواجد مزعجة. استخدم /stop-typing فقط عندما كان الوكيل "نشطاً" بالتأكيد والآن هو "غير نشط" بالتأكيد.

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

  • إنهاء مؤشرات التواجد "يكتب الآن..." أو "يسجل مقطعاً صوتياً..." صراحة.
  • تكامل أصلي مع إشارات PAUSE في واتساب لردود فعل فورية للمستلم.
  • ضروري لتنظيف الحالات بعد نقل الوكلاء أو إلغاء سير العمل.
  • تجاوز فوري لمهلات الشبكة القياسية التي تبلغ 20 ثانية.
  • أساس للتعامل الموثوق مع الأخطاء (Try/Finally) في أنظمة بوت الذكاء الاصطناعي المؤتمتة.
  • يضمن جمالية حوارية مصقولة واحترافية من خلال منع "الكتابة الوهمية".

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

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

مثال:
string

رمز وصول API الخاص بك

مثال:
string

رقم الهاتف المستهدف أو معرف المجموعة

مثال:

أمثلة الكود

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

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

Command Palette

Search for a command to run...