بدء الكتابة (Start Typing)

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

POST

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

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

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

تسجيل الدخول

اختبار /v2/send/start-typing

يدعم

POST

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

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

استراتيجية البوت

استخدام حالة الكتابة يزيد من الثقة لأنها تحاكي وكيلاً بشرياً يحضر الرد.

توصيات

Call this 2-3 seconds before sending the actual text message.
Use webhooks to detect when a user starts typing to your bot as well.

التواجد العضوي: إتقان محرك "بدء الكتابة"

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

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

عندما تقوم بتشغيل نقطة النهاية /start-typing، يبدأ Wawp "بث تواجد" عبر شبكة واتساب:

بدء الإشارة: يرسل المحرك حزمة COMPOSE متخصصة إلى الدردشة المحددة بواسطة chatId. توجه هذه الحزمة هاتف المستلم لعرض نص "يكتب الآن..." في الشريط العلوي لنافذة الدردشة والفقاعة المتحركة في خيط الرسائل.
الاستمرارية المؤقتة: على عكس الرسالة، هذه الحالة مؤقتة بطبيعتها. يقوم واتساب بمسحها تلقائياً بعد حوالي 10-20 ثانية إذا لم يتم اكتشاف أي نشاط إضافي. ومع ذلك، يتيح لك Wawp الحفاظ على هذه الحالة لفترات أطول من خلال استدعاء نقطة النهاية بشكل دوري.
المزامنة متعددة المنصات: يتم مزامنة مؤشر "يكتب الآن..." عبر حساب المستلم بالكامل—فيظهر على هاتفه المحمول، WhatsApp Web، وتطبيقات سطح المكتب في وقت واحد.

🛡️ أفضل الممارسات الاستراتيجية للمحاكاة العضوية

1. استراتيجية "وقت التفكير"

الردود النصية الفورية من البوت هي دليل واضح على عدم وجود إنسان.

التنفيذ: عندما يتلقى نظامك الخلفي Webhook لـ message.received، استدعِ /v2/send/start-typing فوراً. ثم، احسب رد الذكاء الاصطناعي أو قم بإجراء استعلام قاعدة البيانات، وانتظر ما لا يقل عن 2-3 ثوانٍ قبل إرسال الرسالة النهائية عبر /v2/send/text.
تأثير تجربة المستخدم: هذا التوقف القصير مع حالة "يكتب الآن..." يجعل التفاعل يبدو وكأنه رد مدروس من وكيل مهتم، مما يزيد بشكل كبير من رضا المستخدم وثقته.

2. إدارة المستخدمين المندفعين

غالباً ما يرسل المستخدمون عدة رسائل متتالية ("مرحباً؟"، "هل أنت هناك؟"، "لدي سؤال").

أفضل ممارسة: بمجرد اكتشاف أي نشاط، قم بتشغيل /start-typing. هذه الملاحظة المرئية غالباً ما توقف المستخدم عن إرسال رسائل متابعة، حيث يمكنه رؤية أن الرد يتم صياغته بالفعل.

3. التنسيق مع تحضير الوسائط

يمكن أن تستغرق ملفات الفيديو الكبيرة أو ملفات PDF بضع ثوانٍ للمعالجة والرفع.

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

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

المحاكاة البشرية عالية الدقة

قم ببناء "ذكاء اصطناعي مؤنس" من خلال تنويع مدة حالة الكتابة بناءً على طول الرد المتوقع. إذا كان الذكاء الاصطناعي على وشك إرسال شرح من 500 كلمة، أظهر حالة "يكتب الآن..." لمدة 4 ثوانٍ. إذا كان مجرد رد "نعم" بسيط، أظهرها لمدة ثانية واحدة فقط. هذا المستوى من التفاصيل يجعل البوت غير قابل للتمييز تقريباً عن الوكيل البشري للوهلة الأولى.

تحضير الصوت التفاعلي

إذا كان البوت الخاص بك على وشك إرسال ملاحظة صوتية (/v2/send/voice)، يمكنك بالفعل الإشارة إلى أنك "يسجل مقطعاً صوتياً..." (في إصدارات المحرك المدعومة). ينبه هذا المستخدم لرفع مستوى الصوت والاستعداد لتفاعل غير نصي، مما يسهل الانتقال بين أنواع الوسائط.

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

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

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

تشغيل مؤشرات واتساب الأصلية لـ "يكتب الآن..." أو "يسجل مقطعاً صوتياً..." صراحة.
محاكاة عضوية عالية الدقة لتدفقات البوت والوكيل البشري.
بث التواجد في الوقت الفعلي للمستلمين الأفراد، المجموعات، والقنوات.
إدارة حالة مؤقتة مع مهلات تلقائية على مستوى الشبكة.
أداة أساسية لإدارة توقعات المستخدم وتقليل الاحتكاك الحواري.
تنسيق سلس مع نقاط نهاية تسليم النصوص والوسائط والمستندات.

البارامترات

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

محتوى الطلب

يرسل كـ JSON

	`string`		المعرف الفريد لجلسة واتساب مثال:
	`string`		رمز وصول API الخاص بك مثال:
	`string`		رقم الهاتف المستهدف أو معرف المجموعة مثال:

أمثلة الكود

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

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/send/start-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));

عينات تفاعليةUTF-8

Ln 73, 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...