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

إرسال علامة القراءة (Mark as Read)

تأكيد قراءة الرسالة وتفعيل العلامة الزرقاء.

POST
https://api.wawp.net/v2/send/seen?access_token=YOUR_ACCESS_TOKEN&chatId=201234567890%40c.us&instance_id=123456789&messageIds=%5B%22false_201234567890%40c.us_AAAAAAAAAAAAAAAAAAAA%22%5D&participant=null

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

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

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

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

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

توصيات

  • Use this when a human agent opens a conversation to keep your CRM in sync with WhatsApp.

  • Batch multiple message IDs in a single call to save API resources.

State Synchronization: Mastering the Read Receipt Engine

The /v2/send/seen endpoint is the primary mechanism for managing "Presence and Attention" within a WhatsApp conversation. In the WhatsApp ecosystem, the transition from grey ticks (delivered) to blue ticks (read) is a high-signal event that dictates user expectation. By programmatically marking messages as seen, you can synchronize your custom CRM, dashboard, or bot state with the native WhatsApp interface, ensuring the customer feels heard and the agent's workspace remains organized.

🏗️ The Read-Receipt Pipeline

Marking a message as "Seen" is a two-way synchronization event handled by Wawp:

  1. Target Identification: The engine accepts an array of messageIds. These IDs are the unique cryptographic hashes generated when the message was first sent or received. Wawp locates these specific entries within the session's local message store.
  2. The Blue-Tick Broadcast: Once identified, Wawp sends a specialized "Read Acknowledgment" packet over the WhatsApp WebSocket. This packet is then propagated to the original sender's device, where the delivery ticks instantly turn blue.
  3. Internal Unread Clearing: Simultaneously, Wawp instructs the WhatsApp network to clear the "Unread Count" badge for that specific chat on all linked devices (e.g., if you have WhatsApp Web or Desktop open alongside your API instance).

🛡️ Strategic Best Practices for Read Management

1. The "Human-in-the-Loop" Sync

Automating seen receipts requires careful alignment with actual agent activity.

  • Workflow: Only trigger /v2/send/seen when an agent actually opens the chat in your custom dashboard.
  • UX Impact: If you mark everything as seen automatically, the customer expects an immediate reply. If an agent isn't actually there, you create a "Response Gap" that leads to customer frustration.

2. High-Efficiency Batching

Wawp supports batching multiple messages in a single API call for a reason.

  • Implementation: If a user sends five messages (Text, Image, then more Text) while your agent is away, do not call the seen endpoint five times. Instead, collect all five messageIds and send them in a single array.
  • Performance: Batching reduces the number of WebSocket transmissions, preserving your instance's bandwidth and reducing the load on the WhatsApp network.

3. Simulating Natural Reading (The Delay Strategy)

Bots that respond instantly and mark messages as seen in milliseconds can often feel "Robotic" and inhuman.

  • Recommendation: For automated bot flows, implement a small, random delay (e.g., 800ms to 2s) between receiving the message and marking it as seen. This mimics the human process of picking up a phone and reading a message, making the interaction feel more organic.

🧩 Advanced Use Cases

Native CRM "Open" Tracking

If you are building a custom CRM on top of Wawp, use the seen endpoint to track agent performance. By measuring the time between a message.received webhook and your system's /v2/send/seen call, you can calculate the "Average Time to View," a critical KPI for support teams.

Bot Flow "Triage"

In a complex multi-stage bot, you can use read receipts to signal milestones. For example, mark the user's initial inquiry as seen only after the bot has successfully categorized the intent. This provides the user with a visual confirmation that the system has "Understood" the input and is now processing the result.

🛠️ Common Pitfalls and Solutions

  • The Participant ID (Groups): In group chats, marking a message as seen requires the chatId of the group AND optionally the participant ID of the original sender. If you omit the participant ID in high-concurrency group environments, some engine versions may fail to identify the specific message hash, resulting in a Receipt Error.
  • Already-Read Loops: Avoid calling the seen endpoint for messages that you yourself sent. While harmless, it's a wasted API call. Most CRM logic should focus exclusively on incoming (unread) messages.
  • Security Key Resync: In rare cases, if a session is under heavy load, a "Seen" packet might time out. Wawp provides an acknowledged: true flag in the response to confirm the proxy has forwarded the request to the network. If you receive a failure, verify the session status via /v2/session/status.

Summary of Capabilities:

  • Programmatically trigger the native WhatsApp "Blue Ticks" (Read Receipts).
  • Support for batch-marking multiple messages as seen in a single API call.
  • Synchronization of unread counters across all linked WhatsApp devices.
  • Native support for individual, group, and channel read receipting.
  • High-fidelity integration with CRM dashboards for agent activity tracking.
  • Reliable delivery confirmation via the Wawp proxy acknowledged delivery mesh.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

Your unique WhatsApp Instance ID

مثال:
string

Your API Access Token

مثال:
string

Target phone number or group ID

مثال:
array

Array of message IDs to mark as seen.

مثال:
string—

The participant who sent the message (for groups).

مثال:

برمج بالذكاء الاصطناعي باستخدام Wawp MCP

MCP READY

قم بربط الـ API مباشرة مع Cursor أو Windsurf أو Claude Desktop، ودع الذكاء الاصطناعي يكتب لك كود الربط وينفذه تلقائياً!

طريقة الربط والإعداد

أمثلة الكود

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

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

Command Palette

Search for a command to run...