Mark chat as unread

Explicitly mark a chat as having unread messages.

POST

https://api.wawp.net/v2/chats/unread?access_token=YOUR_ACCESS_TOKEN&chatId=201234567890%40c.us&instance_id=123456789

Authentication Required

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

Log In

Test /v2/chats/unread endpoint

Supports

POST

No query parameters required

This endpoint doesn't expect data in the URL.

Internal Workflow

Use 'Mark as Unread' as a lightweight ticketing system inside WhatsApp without needing external software.

Best practices

Include an 'Unread' filter in your dashboard to help agents find flagged conversations instantly.
Combined with Archiving, this can help create a 'Snooze' feature for support tickets.
Use this endpoint to restore visibility to conversations that were accidentally opened.

The Reminder Flag: Mastering the "Unread" State

The /v2/chats/unread endpoint is an essential tool for inbox organization and workflow management. Unlike marking as read, which sends a network-wide signal to the other party, marking as unread is a Local Identity Action. It places a visual "Unread" dot next to a conversation in your Wawp instance and linked devices, serving as a powerful "To-Do" flag for agents who need to return to a conversation later.

🏗️ Technical Impact of "Marking as Unread"

When you invoke this endpoint, the Wawp engine performs a state mutation within the session's internal database:

State Toggle: The unreadCount for the specified chatId is set to an "indicated" state (usually representing at least 1 unread item).
Display Leveling: On WhatsApp Web and Mobile, a green/blue dot appears next to the conversation.
Does NOT Affect Ticks: It is crucial to understand that this action does not turn the sender's blue ticks back to grey. The sender still sees the message as read if it was previously acknowledged.

🚀 Strategic Implementation Patterns

1. The "Escalation Flag"

In a helpdesk scenario, an agent might open a chat, realize it belongs to a different department, and need to hand it off.

Workflow: The agent clicks "Transfer," and your system automatically calls /v2/chats/unread. This ensures the heart of the new department sees the chat as a "New/Urgent" item in their filtered inbox.

2. The "Reminder" Loop

If a bot handles a request but requires a human to verify the final data:

Best Practice: After the bot finishes its work, have it call /v2/chats/unread. This keeps the conversation at the top of the "To-Read" queue for the human supervisor.

🛡️ Best Practices for Inbox Triage

Filter-Ready Architecture: When fetching your chat list via /v2/chats/overview, use the unread state to drive your "Pending Action" tab. Any chat marked as unread should be treated as an open ticket.
Clear Before Unread: If you want to use the unread dot as a clean "Reminder," it's often best to call /v2/chats/read first to clear any real unread counts, and then immediately call /v2/chats/unread to set the single "Reminder Dot."
JID Precision: Ensure you are targeting the correct conversation. Marking a group as unread is a common way for moderators to flag messages that need a policy review later.

🧩 Advanced Use Case: Multi-Agent Synchronization

Build a "Bookmark" feature in your CRM.

Logic: When an agent clicks "Follow Up Later," the CRM calls the unread endpoint. Because this state syncs via the WhatsApp WebSocket, every other agent on that same Wawp instance will also see the unread indicator, preventing the conversation from being forgotten during shift changes.

⚠️ Important Considerations

Local UI Only: This is a non-destructive, non-broadcast action. It is the only "Chat Action" that doesn't significantly impact the customer's view of the conversation.
Engine State: Requires the session to be in the WORKING state to synchronize the indicator with linked devices.
Overwrite Behavior: If the chat already has real unread messages (e.g., 5 unread), calling this endpoint might not change the visual state significantly, as it's already "Unread." It is most effective when moving a conversation from a "Read/Processed" state back to "Attention Required."

Summary of Capabilities:

Explicitly setting of the "Unread" visual indicator for any chat.
Synchronized bookmarking across all linked devices.
Powerful tool for agent handoffs and "Follow Up" reminders.
Non-impactful to the customer experience (does not change blue ticks).

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`		WhatsApp Instance ID Example:
	`string`		API Access Token Example:
	`string`		Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter). 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/chats/unread";
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: Bad Request - Missing Required Parameter(s)");
26    }
27    if (response.status === 400) {
28      console.error("Error 400: Bad Request (XML Format)");
29    }
30    if (response.status === 400) {
31      console.error("Error 400: Bad Request (Plain Text)");
32    }
33    if (response.status === 401) {
34      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
35    }
36    if (response.status === 401) {
37      console.error("Error 401: Unauthorized (XML Format)");
38    }
39    if (response.status === 404) {
40      console.error("Error 404: Not Found - Session Does Not Exist");
41    }
42    if (response.status === 404) {
43      console.error("Error 404: Not Found (XML Format)");
44    }
45    if (response.status === 500) {
46      console.error("Error 500: Internal Server Error - Unexpected Failure");
47    }
48    if (response.status === 500) {
49      console.error("Error 500: Internal Server Error (HTML)");
50    }
51    if (response.status === 502) {
52      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
53    }
54    if (response.status === 502) {
55      console.error("Error 502: Bad Gateway (XML Format)");
56    }
57
58    const errorText = await response.text();
59    console.error(`Error ${response.status}: ${errorText}`);
60  })
61  .catch((error) => console.error("Network Error:", error));

Interactive SamplesUTF-8

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

Success - Request completed successfully

3 Variants

Type:

application/json

boolean *

string *

Example

{
"success": true,
"message": "Operation completed successfully"
}

Bad Request - Missing Required Parameter(s)

3 Variants

Unauthorized - Invalid or Missing Access Token

2 Variants

Command Palette

Search for a command to run...