API Reference

makeWASocket(config)

Creates a WhatsApp socket instance with the given configuration.

Parameters

sock.requestPairingCode(phoneNumber)

Request a pairing code for authentication.

Parameters

Returns

Promise<string> - 8-character pairing code

sock.logout()

Logout from WhatsApp and clear session.

Returns

Promise<void>

sock.end(error?)

End the socket connection.

Parameters

sock.onWhatsApp(...jids)

Check if phone numbers are registered on WhatsApp.

Returns

Promise<Array<{exists: boolean, jid: string}>>

sock.sendMessage(jid, content, options?)

Send a message to a chat.

Parameters

Content Types

// Text
await sock.sendMessage(jid, { text: 'Hello!' });

// Image
await sock.sendMessage(jid, { 
    image: { url: './image.jpg' },
    caption: 'Image caption'
});

// Video
await sock.sendMessage(jid, { 
    video: { url: './video.mp4' },
    caption: 'Video caption'
});

// Audio
await sock.sendMessage(jid, { 
    audio: { url: './audio.mp3' },
    mimetype: 'audio/mp4'
});

// Document
await sock.sendMessage(jid, { 
    document: { url: './file.pdf' },
    mimetype: 'application/pdf',
    fileName: 'document.pdf'
});

// Sticker
await sock.sendMessage(jid, { 
    sticker: fs.readFileSync('./sticker.webp')
});

// Location
await sock.sendMessage(jid, { 
    location: { 
        degreesLatitude: -6.200000,
        degreesLongitude: 106.816666,
        name: 'Jakarta'
    }
});

// Contact
await sock.sendMessage(jid, { 
    contacts: { 
        displayName: 'Contact',
        contacts: [{ vcard: 'BEGIN:VCARD...' }]
    }
});

// Reaction
await sock.sendMessage(jid, { 
    react: { 
        key: message.key,
        text: '👍'
    }
});

// Reply
await sock.sendMessage(jid, { 
    text: 'Reply message'
}, { quoted: message });

sock.readMessages(keys)

Mark messages as read.

Parameters

sock.sendPresenceUpdate(type, toJid?)

Send presence update (typing, recording, etc.).

Parameters

sock.groupMetadata(jid)

Get group metadata.

Returns

Promise<GroupMetadata>

sock.groupCreate(subject, participants)

Create a new group.

Parameters

Returns

Promise<GroupMetadata>

sock.groupParticipantsUpdate(jid, participants, action)

Update group participants.

Parameters

sock.groupUpdateSubject(jid, subject)

Update group subject/name.

sock.groupUpdateDescription(jid, description)

Update group description.

sock.groupInviteCode(jid)

Get group invite code.

Returns

Promise<string>

sock.groupRevokeInvite(jid)

Revoke group invite code and generate new one.

sock.groupAcceptInvite(code)

Join a group via invite code.

Returns

Promise<string> - Group JID

sock.groupLeave(jid)

Leave a group.

sock.groupSettingUpdate(jid, setting)

Update group settings.

Parameters

sock.newsletterCreate(name, description, reaction_codes)

Create a new newsletter.

Returns

Promise<NewsletterMetadata>

sock.newsletterMetadata(type, key, role?)

Get newsletter metadata.

Parameters

sock.newsletterFollow(jid)

Follow a newsletter.

sock.newsletterUnfollow(jid)

Unfollow a newsletter.

sock.newsletterUpdateName(jid, name)

Update newsletter name.

sock.newsletterUpdateDescription(jid, description)

Update newsletter description.

sock.newsletterUpdatePicture(jid, content)

Update newsletter picture.

sock.newsletterRemovePicture(jid)

Remove newsletter picture.

sock.newsletterReactMessage(jid, serverId, code?)

React to a newsletter message.

sock.newsletterFetchMessages(type, key, count, after?)

Fetch newsletter messages.

sock.newsletterDelete(jid)

Delete a newsletter.

sock.updateProfileName(name)

Update profile name.

sock.updateProfileStatus(status)

Update profile about/status.

sock.updateProfilePicture(jid, content)

Update profile picture.

sock.removeProfilePicture(jid)

Remove profile picture.

sock.profilePictureUrl(jid, type?, timeoutMs?)

Get profile picture URL.

Returns

Promise<string>

sock.fetchStatus(jid)

Get user's about/status.

sock.updateBlockStatus(jid, action)

Block or unblock a contact.

Parameters

sock.fetchBlocklist()

Get list of blocked contacts.

Returns

Promise<string[]>

sock.chatModify(modification, jid)

Modify chat (archive, pin, mute, etc.).

// Archive chat
await sock.chatModify({ archive: true }, jid);

// Pin chat
await sock.chatModify({ pin: true }, jid);

// Mute chat (8 hours)
await sock.chatModify({ mute: 8 * 60 * 60 }, jid);

// Unmute chat
await sock.chatModify({ mute: null }, jid);

// Clear messages
await sock.chatModify({ clear: true }, jid);

// Delete chat
await sock.chatModify({ delete: true }, jid);

sock.star(jid, messages, star)

Star or unstar messages.

downloadMediaMessage(message, type, options)

Download media from a message.

const { downloadMediaMessage } = require('socketon');

const buffer = await downloadMediaMessage(message, 'buffer', {});
fs.writeFileSync('./download.jpg', buffer);

connection.update

Fired when connection state changes.

sock.ev.on('connection.update', (update) => {
    const { connection, lastDisconnect, qr, pairingCode } = update;
    
    if (qr) {
        // Show QR code
    }
    
    if (pairingCode) {
        // Show pairing code
    }
    
    if (connection === 'close') {
        // Handle disconnect
    } else if (connection === 'open') {
        // Connected
    }
});

messages.upsert

Fired when messages are received or sent.

sock.ev.on('messages.upsert', ({ messages, type }) => {
    // type: 'notify' (new message) | 'append' | 'prepend'
    console.log('New message:', messages[0]);
});

presence.update

Fired when contact presence changes.

sock.ev.on('presence.update', ({ id, presences }) => {
    // id: chat JID
    // presences: { participantJid: { lastKnownPresence, lastSeen } }
});

creds.update

Fired when credentials are updated (save your auth state).

sock.ev.on('creds.update', saveCreds);

DisconnectReason