Skip to main content

Chat Management

Manage WhatsApp chats including deletion, archiving, and message operations.

Delete Chat​

Permanently delete a chat conversation.

DELETE /sessions/{id}/chats/{chatId}

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
chatIdstringChat ID (phone number or full JID)

Example Request​

curl -X DELETE \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats/919988066776@s.whatsapp.net

Response​

{
  "success": true,
  "jid": "919988066776@s.whatsapp.net",
  "message": "Chat deleted successfully"
}
Warning

This action is irreversible. All messages in the chat will be permanently deleted from your device.

Archive Chat​

Archive a chat to hide it from the main chat list.

POST /sessions/{id}/chats/{chatId}/archive

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
chatIdstringChat ID (phone number or full JID)

Example Request​

curl -X POST \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats/919988066776@s.whatsapp.net/archive

Response​

{
  "success": true,
  "jid": "919988066776@s.whatsapp.net",
  "message": "Chat archived successfully"
}

Unarchive Chat​

Restore an archived chat to the main chat list.

POST /sessions/{id}/chats/{chatId}/unarchive

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
chatIdstringChat ID (phone number or full JID)

Example Request​

curl -X POST \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats/919988066776@s.whatsapp.net/unarchive

Response​

{
  "success": true,
  "jid": "919988066776@s.whatsapp.net",
  "message": "Chat unarchived successfully"
}

Mark Chat as Unread​

Mark a chat as unread (adds unread indicator).

POST /sessions/{id}/chats/{chatId}/unread

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
chatIdstringChat ID (phone number or full JID)

Example Request​

curl -X POST \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats/919988066776@s.whatsapp.net/unread

Response​

{
  "success": true,
  "jid": "919988066776@s.whatsapp.net",
  "message": "Chat marked as unread"
}
info

This is a cosmetic change. It doesn't affect message delivery or read receipts.

Delete Message​

Delete a message you sent (for everyone).

DELETE /sessions/{id}/chats/{chatId}/messages/{messageId}

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
chatIdstringChat ID where the message is
messageIdstringMessage ID to delete

Example Request​

curl -X DELETE \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats/919988066776@s.whatsapp.net/messages/MESSAGE_ID

Response​

{
  "success": true,
  "message": "Message deleted successfully"
}
Limitations
  • You can only delete messages you sent
  • Messages can only be deleted within ~48 hours of sending
  • Deleted messages show "This message was deleted" to recipients

Edit Message​

Edit a message you sent.

PUT /sessions/{id}/chats/{chatId}/messages/{messageId}

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
chatIdstringChat ID where the message is
messageIdstringMessage ID to edit

Request Body​

ParameterTypeRequiredDescription
textstringYesNew message text

Example Request​

curl -X PUT http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats/919988066776@s.whatsapp.net/messages/MESSAGE_ID \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Updated message text"
  }'

Response​

{
  "success": true,
  "message": "Message edited successfully"
}
Limitations
  • You can only edit messages you sent
  • Messages can only be edited within ~15 minutes of sending
  • Edited messages show "edited" indicator to recipients
  • Only text messages can be edited (not media)

Pin Message​

Pin a message in a chat (visible at top for 24 hours).

POST /sessions/{id}/chats/{chatId}/messages/{messageId}/pin

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
chatIdstringChat ID where the message is
messageIdstringMessage ID to pin

Example Request​

curl -X POST \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats/919988066776@s.whatsapp.net/messages/MESSAGE_ID/pin

Response​

{
  "success": true,
  "message": "Message pinned successfully"
}
Pin Duration

Messages are automatically pinned for 24 hours by default.

Unpin Message​

Unpin a previously pinned message.

POST /sessions/{id}/chats/{chatId}/messages/{messageId}/unpin

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
chatIdstringChat ID where the message is
messageIdstringMessage ID to unpin

Example Request​

curl -X POST \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats/919988066776@s.whatsapp.net/messages/MESSAGE_ID/unpin

Response​

{
  "success": true,
  "message": "Message unpinned successfully"
}

React to Message​

React to a message with an emoji.

PUT /sessions/{id}/messages/{messageId}/reaction

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
messageIdstringMessage ID to react to

Request Body​

ParameterTypeRequiredDescription
chatIdstringYesChat ID where the message is
emojistringNoEmoji to react with (empty string to remove)

Example Request (Add Reaction)​

curl -X PUT http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/messages/MESSAGE_ID/reaction \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "919988066776@s.whatsapp.net",
    "emoji": "👍"
  }'

Example Request (Remove Reaction)​

curl -X PUT http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/messages/MESSAGE_ID/reaction \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "919988066776@s.whatsapp.net",
    "emoji": ""
  }'

Response​

{
  "success": true,
  "message": "Reaction sent successfully"
}

Supported Emojis​

You can use any standard emoji:

  • 👍 👎 ❤️ 😂 😮 😢 🙏
  • 🎉 🔥 💯 ✅ ❌ ⭐
  • And many more...
Remove Reaction

Send an empty string "" as the emoji to remove your reaction.

Star Message​

Star or unstar a message (adds to starred messages).

POST /sessions/{id}/chats/{chatId}/messages/{messageId}/star

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
chatIdstringChat ID where the message is
messageIdstringMessage ID to star/unstar

Request Body​

ParameterTypeRequiredDescription
starbooleanNotrue to star, false to unstar (default: true)

Example Request (Star)​

curl -X POST http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats/919988066776@s.whatsapp.net/messages/MESSAGE_ID/star \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{
    "star": true
  }'

Example Request (Unstar)​

curl -X POST http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats/919988066776@s.whatsapp.net/messages/MESSAGE_ID/star \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{
    "star": false
  }'

Response​

{
  "success": true,
  "message": "Message starred successfully"
}

Error Responses​

Message Not Found​

{
  "success": false,
  "error": "Message not found"
}

Solution: Verify the message ID is correct and the message still exists.

Cannot Edit Message​

{
  "success": false,
  "error": "Message cannot be edited (too old or not sent by you)"
}

Solution: Messages can only be edited within 15 minutes and must be sent by you.

Cannot Delete Message​

{
  "success": false,
  "error": "Message cannot be deleted (too old or not sent by you)"
}

Solution: Messages can only be deleted within 48 hours and must be sent by you.

Code Examples​

JavaScript (Node.js)​

const axios = require('axios');

const API_KEY = 'wask_your_session_key';
const SESSION_ID = 'e67a00be-ed45-4356-9488-049cabb9895d';
const BASE_URL = 'http://localhost:3000';

// Delete chat
async function deleteChat(chatId) {
  const response = await axios.delete(
    `${BASE_URL}/sessions/${SESSION_ID}/chats/${chatId}`,
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.data;
}

// Archive chat
async function archiveChat(chatId) {
  const response = await axios.post(
    `${BASE_URL}/sessions/${SESSION_ID}/chats/${chatId}/archive`,
    {},
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.data;
}

// React to message
async function reactToMessage(messageId, chatId, emoji) {
  const response = await axios.put(
    `${BASE_URL}/sessions/${SESSION_ID}/messages/${messageId}/reaction`,
    { chatId, emoji },
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.data;
}

// Edit message
async function editMessage(chatId, messageId, newText) {
  const response = await axios.put(
    `${BASE_URL}/sessions/${SESSION_ID}/chats/${chatId}/messages/${messageId}`,
    { text: newText },
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.data;
}

// Usage
archiveChat('919988066776@s.whatsapp.net');
reactToMessage('MSG_ID', '919988066776@s.whatsapp.net', '👍');
editMessage('919988066776@s.whatsapp.net', 'MSG_ID', 'Updated text');

Python​

import requests

API_KEY = "wask_your_session_key"
SESSION_ID = "e67a00be-ed45-4356-9488-049cabb9895d"
BASE_URL = "http://localhost:3000"

headers = {"X-API-Key": API_KEY}

# Delete chat
def delete_chat(chat_id):
    url = f"{BASE_URL}/sessions/{SESSION_ID}/chats/{chat_id}"
    response = requests.delete(url, headers=headers)
    return response.json()

# Archive chat
def archive_chat(chat_id):
    url = f"{BASE_URL}/sessions/{SESSION_ID}/chats/{chat_id}/archive"
    response = requests.post(url, headers=headers)
    return response.json()

# React to message
def react_to_message(message_id, chat_id, emoji):
    url = f"{BASE_URL}/sessions/{SESSION_ID}/messages/{message_id}/reaction"
    data = {"chatId": chat_id, "emoji": emoji}
    response = requests.put(url, json=data, headers=headers)
    return response.json()

# Usage
archive_chat("919988066776@s.whatsapp.net")
react_to_message("MSG_ID", "919988066776@s.whatsapp.net", "👍")

Best Practices​

  1. Message Operations

    • Check message age before attempting edit/delete
    • Handle errors gracefully when operations fail
    • Verify you own the message before operations

  2. Chat Management

    • Confirm before deleting chats (irreversible)
    • Use archive instead of delete when possible
    • Batch archive operations for better performance

  3. Reactions

    • Use standard emojis for better compatibility
    • Remove reactions by sending empty string
    • Don't spam reactions (rate limiting applies)

  4. Error Handling

    • Always check operation success
    • Implement retry logic for network errors
    • Log failed operations for debugging