Send Messages

Mark message(s) as seen

Mark specific messages or an entire chat as seen/read (Blue Ticks).

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

Authentication Required

Login to swap the placeholders with your real Instance ID and Access Token.

Log In
Test /v2/send/seen endpoint
POST
POST

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • 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.

Request Parameters

Configure the parameters required to interact with this endpoint. All query and body arguments are listed below with their details.

Request Body

Sent as a JSON object
string

Your unique WhatsApp Instance ID

Example:
string

Your API Access Token

Example:
string

Target phone number or group ID

Example:
array

Array of message IDs to mark as seen.

Example:
string—

The participant who sent the message (for groups).

Example:

Request Samples

Use these ready-to-go code snippets to integrate our API into your project quickly and efficiently. Choose your preferred language and library.

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: Bad Request - Missing Required Parameter(s)");
30    }
31    if (response.status === 400) {
32      console.error("Error 400: Bad Request - Invalid Number (Egypt)");
33    }
34    if (response.status === 400) {
35      console.error("Error 400: Bad Request - Invalid Number (Saudi Arabia)");
36    }
37    if (response.status === 400) {
38      console.error("Error 400: Bad Request - Invalid Number (Unknown)");
39    }
40    if (response.status === 400) {
41      console.error("Error 400: Bad Request (XML Format)");
42    }
43    if (response.status === 400) {
44      console.error("Error 400: Bad Request (Plain Text)");
45    }
46    if (response.status === 401) {
47      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
48    }
49    if (response.status === 401) {
50      console.error("Error 401: Unauthorized (XML Format)");
51    }
52    if (response.status === 404) {
53      console.error("Error 404: Not Found - Session Does Not Exist");
54    }
55    if (response.status === 404) {
56      console.error("Error 404: Not Found (XML Format)");
57    }
58    if (response.status === 429) {
59      console.error("Error 429: Too Many Requests - Rate Limit Exceeded");
60    }
61    if (response.status === 500) {
62      console.error("Error 500: Internal Server Error - Unexpected Failure");
63    }
64    if (response.status === 500) {
65      console.error("Error 500: Internal Server Error (HTML)");
66    }
67    if (response.status === 502) {
68      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
69    }
70    if (response.status === 502) {
71      console.error("Error 502: Bad Gateway (XML Format)");
72    }
73
74    const errorText = await response.text();
75    console.error(`Error ${response.status}: ${errorText}`);
76  })
77  .catch((error) => console.error("Network Error:", error));
Interactive Samples
Ln 77, Col 1javascript

Expected Responses

Explore all possible responses and outcomes from the server. We have documented each status code with data examples to make success and error handling easier.

Message Sent Successfully
Type:
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": {
  }
}
Bad Request - Missing Required Parameter(s)
Unauthorized - Invalid or Missing Access Token
Not Found - Session Does Not Exist
Too Many Requests - Rate Limit Exceeded
Internal Server Error - Unexpected Failure
Bad Gateway - Connection Failed to Upstream
Previous TopicSend Contact Vcard
Next TopicStart Typing

Command Palette

Search for a command to run...