Manage chats: archive, mute, pin, and delete

Use chatModify to archive, mute, mark read, pin, star, or delete WhatsApp chats and messages. Reference for all supported chat modification operations.

sock.chatModify(modification, jid) lets you send encrypted app-state updates to WhatsApp for a specific chat. Each modification is a plain object describing the operation — archive, mute, read status, delete, pin, or star.

If you send a malformed or inconsistent chatModify update, WhatsApp may log you out of all your devices and require you to log in again. Always pass the correct lastMessages array when the API requires it.

Archive a chat

Pass the most recent message in the chat as lastMessages so WhatsApp can reconcile state. Set archive: false to unarchive.

const lastMsgInChat = await getLastMessageInChat(jid) // implement this on your end
await sock.chatModify({ archive: true, lastMessages: [lastMsgInChat] }, jid)

Mute / unmute a chat

Mute durations are expressed in milliseconds. Pass null to unmute immediately.

Duration	Milliseconds
Unmute	null
8 hours	28800000
7 days	604800000

// mute for 8 hours
await sock.chatModify({ mute: 8 * 60 * 60 * 1000 }, jid)
// unmute
await sock.chatModify({ mute: null }, jid)

Mark a chat read or unread

const lastMsgInChat = await getLastMessageInChat(jid) // implement this on your end
// mark it unread
await sock.chatModify({ markRead: false, lastMessages: [lastMsgInChat] }, jid)

Delete a message for me

This removes the message from your view only. Other participants are unaffected. Provide the message id, whether it was sent by you (fromMe), and its timestamp.

await sock.chatModify(
    {
        clear: {
            messages: [
                {
                    id: 'ATWYHDNNWU81732J',
                    fromMe: true,
                    timestamp: '1654823909'
                }
            ]
        }
    },
    jid
)

Delete a chat

Deleting a chat removes it from your chat list. Pass the last message so WhatsApp can sync the deletion correctly.

const lastMsgInChat = await getLastMessageInChat(jid) // implement this on your end
await sock.chatModify({
        delete: true,
        lastMessages: [
            {
                key: lastMsgInChat.key,
                messageTimestamp: lastMsgInChat.messageTimestamp
            }
        ]
    },
    jid
)

Pin / unpin a chat

await sock.chatModify({
        pin: true // or `false` to unpin
    },
    jid
)

Star / unstar a message

Set star: true to star messages and star: false to unstar them. You can batch multiple messages in the same call.

await sock.chatModify({
        star: {
            messages: [
                {
                    id: 'messageID',
                    fromMe: true // or `false`
                }
            ],
            star: true // - true: Star Message; false: Unstar Message
        }
    },
    jid
)

---

User queries

Check if a JID exists on WhatsApp

const [result] = await sock.onWhatsApp(jid)
if (result.exists) console.log (`${jid} exists on WhatsApp, as jid: ${result.jid}`)

Query chat history

You need the oldest message currently in the chat to paginate backwards. History arrives in the messaging-history.set event — not as a return value.

const msg = await getOldestMessageInChat(jid) // implement this on your end
await sock.fetchMessageHistory(
    50, //quantity (max: 50 per query)
    msg.key,
    msg.messageTimestamp
)

Messages are delivered via the messaging-history.set event, not returned directly from fetchMessageHistory.

Fetch a user’s status text

const status = await sock.fetchStatus(jid)
console.log('status: ' + status)

Fetch a profile picture

Pass 'image' as the second argument to get the full-resolution photo instead of the thumbnail.

// for low res picture
const ppUrl = await sock.profilePictureUrl(jid)
console.log(ppUrl)

// for high res picture
const ppUrl = await sock.profilePictureUrl(jid, 'image')

Fetch a business profile

const profile = await sock.getBusinessProfile(jid)
console.log('business description: ' + profile.description + ', category: ' + profile.category)

---

Update your profile

Change profile status

await sock.updateProfileStatus('Hello World!')

Change profile name

await sock.updateProfileName('My name')

Change your profile picture

Accepts the same WAMediaUpload types as media messages (Buffer, { url }, or { stream }).

await sock.updateProfilePicture(jid, { url: './new-profile-picture.jpeg' })

Remove your profile picture

await sock.removeProfilePicture(jid)