WPP.chat — Send messages and manage WhatsApp chats

The WPP.chat module is the primary interface for all messaging operations in WA-JS. It exposes functions for sending every WhatsApp message type — text, files, locations, polls, reactions, vCards, and group invites — alongside utilities for reading message history, managing chat state (mute, archive, pin), and handling delivery receipts. All functions are async and return promises that resolve once the operation is confirmed by WhatsApp’s internal signal layer.

Sending messages

`sendTextMessage`

Send a plain text message, optionally with interactive buttons or a link preview.

// Simple text
WPP.chat.sendTextMessage('[number]@c.us', 'Hello!');

// With a quoted reply
WPP.chat.sendTextMessage('[number]@c.us', 'Replying here', {
  quotedMsg: 'true_[number]@c.us_ABCDEF'
});

// With interactive buttons
WPP.chat.sendTextMessage('[number]@c.us', 'Choose an option', {
  useInteractiveMessage: true,
  buttons: [
    { id: 'opt1', text: 'Option 1' },
    { id: 'opt2', text: 'Option 2' },
    { url: 'https://example.com', text: 'Visit site' },
    { phoneNumber: '+55 11 99999-9999', text: 'Call us' }
  ],
  title: 'Menu',
  footer: 'Pick one'
});

chatId

string

required

The target chat JID. Use [number]@c.us for individual chats or [id]@g.us for groups.

content

string

required

The message body text. Supports WhatsApp markdown (*bold*, _italic_, ~strike~, `mono`).

options

object

Show TextMessageOptions

options.quotedMsg

string

Message ID to quote (reply to).

options.mentionedList

string[]

Array of JIDs to mention (['123@c.us']).

options.buttons

object[]

Interactive button definitions. Each button is one of { id, text }, { url, text }, { phoneNumber, text }, or { code, text }.

options.title

string

Title shown above the button list.

options.footer

string

Footer text shown below the button list.

options.useInteractiveMessage

boolean

default:"false"

Use the interactive message format for buttons. Set false for the legacy button format.

options.linkPreview

boolean

default:"true"

Generate a link preview when the text contains a URL.

options.markIsRead

boolean

default:"true"

Mark the chat as read before sending.

options.waitForAck

boolean

default:"true"

Wait until the message ACK reaches SENT(1) before resolving.

options.delay

number

default:"0"

Delay in milliseconds before sending. While waiting the typing indicator is shown.

Returns Promise<SendMessageReturn> — { id: string, ack: number, sendMsgResult: Promise<...> }

`sendFileMessage`

Send a media file as an audio, document, image, sticker, or video message. The content parameter accepts a base64 data URI, a publicly accessible URL, a Blob, or a File object.

// Image with caption
WPP.chat.sendFileMessage('[number]@c.us', 'data:image/jpeg;base64,<base64...>', {
  type: 'image',
  caption: 'Look at this!'
});

// View-once image
WPP.chat.sendFileMessage('[number]@c.us', 'data:image/jpeg;base64,<base64...>', {
  type: 'image',
  isViewOnce: true
});

// Voice message (PTT) with waveform
WPP.chat.sendFileMessage('[number]@c.us', 'data:audio/ogg;base64,<base64...>', {
  type: 'audio',
  isPtt: true,
  waveform: true
});

// Document with custom filename
WPP.chat.sendFileMessage('[number]@c.us', 'data:application/pdf;base64,<base64...>', {
  type: 'document',
  filename: 'report.pdf',
  caption: 'Q3 Report'
});

// Animated GIF
WPP.chat.sendFileMessage('[number]@c.us', 'data:video/mp4;base64,<base64...>', {
  type: 'video',
  isGif: true
});

// Round video (PTV / micro-video)
WPP.chat.sendFileMessage('[number]@c.us', 'data:video/mp4;base64,<base64...>', {
  type: 'video',
  isPtv: true
});

// From a public URL (CORS must be open)
WPP.chat.sendFileMessage('[number]@c.us', 'https://example.com/photo.jpg', {
  type: 'image',
  caption: 'Remote image'
});

chatId

string

required

Target chat JID or 'status@broadcast' to post to your Status story.

content

string | Blob | File

required

File data as a base64 data URI (data:<mime>;base64,<data>), a public URL, a Blob, or a File object.

options

object

required

Hide File type options

options.type

string

required

Media type. One of 'audio', 'document', 'image', 'sticker', 'video', or 'auto-detect'.

options.caption

string

Caption text shown beneath the media.

options.filename

string

Custom filename (primarily for document type).

options.mimetype

string

Override the detected MIME type.

options.isPtt

boolean

audio only — send as a push-to-talk voice message.

options.waveform

boolean

default:"true"

audio + isPtt only — include waveform data in the message.

options.isViewOnce

boolean

image and audio (PTT) — message can only be viewed once.

options.isHD

boolean

image and video — send in HD quality (up to 2560 px max dimension instead of 1600 px).

options.isGif

boolean

video only — send as an animated GIF (looping, no sound).

options.isPtv

boolean

video only — send as a round micro-video (PTV format).

WhatsApp enforces file size limits per media type. sendFileMessage validates the file size before upload and throws a WPPError with code file_too_large if the limit is exceeded.

Returns Promise<SendMessageReturn>

`sendLocationMessage`

Send a location pin with optional place name, address, and an external URL.

// Minimal — coordinates only
WPP.chat.sendLocationMessage('[number]@c.us', {
  lat: -22.95201,
  lng: -43.2102601
});

// With place details
WPP.chat.sendLocationMessage('[number]@c.us', {
  lat: -22.95201,
  lng: -43.2102601,
  name: 'Cristo Redentor',
  address: 'Parque Nacional da Tijuca, Rio de Janeiro',
  url: 'https://example.com/map'
});

chatId

string

required

Target chat JID.

options

object

required

Hide LocationMessageOptions

options.lat

number | string

required

Latitude in decimal degrees.

options.lng

number | string

required

Longitude in decimal degrees.

options.name

string

Display name of the place.

options.address

string

Full address shown below the name.

options.url

string

URL opened when the recipient taps the location.

Returns Promise<SendMessageReturn>

`sendListMessage`

Send an interactive list message with up to 10 sections. Each section contains selectable rows.

WPP.chat.sendListMessage('[number]@c.us', {
  buttonText: 'View options',
  description: 'Choose a category below',
  title: 'Our menu',           // optional
  footer: 'Tap to select',     // optional
  sections: [
    {
      title: 'Drinks',
      rows: [
        { rowId: 'coffee', title: 'Coffee', description: 'Hot espresso' },
        { rowId: 'tea',    title: 'Tea',    description: 'Green tea' }
      ]
    },
    {
      title: 'Food',
      rows: [
        { rowId: 'pizza',  title: 'Pizza',  description: 'Margherita' }
      ]
    }
  ]
});

chatId

string

required

Target chat JID.

options

object

required

Hide ListMessageOptions

options.buttonText

string

required

Label on the button that opens the list.

options.description

string

required

Body text of the message.

options.title

string

Optional title shown above the description.

options.footer

string

Optional footer shown below the list.

options.sections

object[]

required

Array of 1–10 sections. Each section has a title string and a rows array. Each row has rowId (string), title (string), and description (string).

Returns Promise<SendMessageReturn>

`sendCreatePollMessage`

Send a poll to a group chat. Poll answers are end-to-end encrypted.

// Basic poll
WPP.chat.sendCreatePollMessage(
  '[groupId]@g.us',
  'Favourite colour?',
  ['Red', 'Green', 'Blue']
);

// Single-answer poll (selectableCount: 1)
WPP.chat.sendCreatePollMessage(
  '[groupId]@g.us',
  'Which day works?',
  ['Monday', 'Tuesday', 'Wednesday'],
  { selectableCount: 1 }
);

Polls only work in group chats (@g.us JIDs).

chatId

string

required

Group chat JID ending in @g.us.

name

string

required

The poll question.

choices

string[]

required

Array of answer option strings.

options

object

Show PoolMessageOptions

options.selectableCount

number

default:"0"

Maximum number of choices a participant can select. 0 means unlimited.

Returns Promise<SendMessageReturn>

`sendReactionToMessage`

Add or remove an emoji reaction on any message.

// React with an emoji
WPP.chat.sendReactionToMessage('true_[number]@c.us_ABCDEF', '🔥');

// Remove a reaction (pass false or empty string)
WPP.chat.sendReactionToMessage('true_[number]@c.us_ABCDEF', false);

messageId

string

required

Full message ID string (e.g. 'true_[number]@c.us_ABCDEF').

reaction

string | false | null

required

An emoji character to set the reaction, or false / null to remove the existing reaction.

Returns Promise<{ sendMsgResult: any }>

`sendVCardContactMessage`

Share one or more contacts as vCard messages.

// Single contact
WPP.chat.sendVCardContactMessage('[number]@c.us', {
  id: '123456789@c.us',
  name: 'Alice Smith'
});

// Multiple contacts at once
WPP.chat.sendVCardContactMessage('[number]@c.us', [
  { id: '111@c.us', name: 'Alice' },
  { id: '222@c.us', name: 'Bob' }
]);

chatId

string

required

Target chat JID.

contacts

object | object[]

required

A single contact object { id: string, name: string } or an array of contact objects. The id must be a valid WhatsApp JID.

Returns Promise<SendMessageReturn>

`sendGroupInviteMessage`

Send a group invite link as a rich message card.

WPP.chat.sendGroupInviteMessage('[number]@c.us', {
  inviteCode: 'AbCdEfGhIjKlMnOp',
  groupId: '123456789@g.us',
  groupName: 'My Group',  // optional — fetched automatically if omitted
  caption: 'Join us!'     // optional
});

chatId

string

required

The recipient’s chat JID.

options

object

required

Show GroupInviteMessage

options.inviteCode

string

required

The invite code portion of the group link (not the full URL).

options.groupId

string

required

The JID of the group being shared ([id]@g.us).

options.groupName

string

Display name of the group. Fetched automatically from group metadata if omitted.

options.inviteCodeExpiration

number

Unix timestamp (seconds) when the invite code expires. If provided, the message is sent as a structured groups_v4_invite type.

options.caption

string

Optional accompanying text.

options.jpegThumbnail

string

Base64-encoded JPEG thumbnail. Fetched from the group’s profile picture if omitted.

Returns Promise<SendMessageReturn>

Message operations

`deleteMessage`

Delete one or more messages locally or for everyone (revoke).

// Delete locally (device only)
WPP.chat.deleteMessage('[number]@c.us', 'msgId');

// Delete multiple messages locally
WPP.chat.deleteMessage('[number]@c.us', ['msgId1', 'msgId2']);

// Delete for everyone (revoke) and clear media
WPP.chat.deleteMessage('[number]@c.us', 'msgId', true, true);

chatId

string

required

The chat JID that contains the message(s).

ids

string | string[]

required

A single message ID or an array of message IDs to delete.

deleteMediaInDevice

boolean

default:"false"

Whether to also delete locally cached media files.

revoke

boolean

default:"false"

Set to true to delete for everyone (“revoke”). Only works for messages you sent, or when you are a group admin.

Returns Promise<DeleteMessageReturn | DeleteMessageReturn[]> where each entry is { id, sendMsgResult, isRevoked, isDeleted, isSentByMe }.

`editMessage`

Edit the text of a previously sent message. Only messages sent by the current user can be edited.

WPP.chat.editMessage(
  'true_[number]@c.us_ABCDEF',
  'Corrected message text',
  { linkPreview: true }
);

msgId

string

required

Full message ID of the message to edit.

newText

string

required

The replacement text content.

options

object

Accepts the same SendMessageOptions fields as sendTextMessage, plus linkPreview and mentionedJidList.

Returns Promise<SendMessageReturn>

`forwardMessage`

Forward an existing message to another chat.

WPP.chat.forwardMessage('[number]@c.us', 'true_[sender]@c.us_ABCDEF');

// Keep the original caption visible
WPP.chat.forwardMessage('[number]@c.us', 'true_[sender]@c.us_ABCDEF', {
  displayCaptionText: true
});

toChatId

string

required

The destination chat JID.

msgId

string

required

The message ID to forward.

options

object

Show ForwardMessageOptions

options.displayCaptionText

boolean

Show the original caption in the forwarded message.

options.multicast

boolean

Internal multicast flag.

Returns Promise<boolean>

`starMessage`

Star or unstar one or more messages.

// Star a single message
WPP.chat.starMessage('true_[number]@c.us_ABCDEF');

// Unstar a single message
WPP.chat.starMessage('true_[number]@c.us_ABCDEF', false);

// Star multiple messages
WPP.chat.starMessage(['msgId1', 'msgId2']);

// Unstar multiple messages
WPP.chat.starMessage(['msgId1', 'msgId2'], false);

ids

string | string[]

required

A single message ID or an array of message IDs.

star

boolean

default:"true"

true to star, false to unstar.

Returns Promise<StarMessageReturn | StarMessageReturn[]> where each entry is { id: string, star: boolean }.

`pinMsg`

Pin a message in a chat. An alias unpinMsg is available to unpin.

// Pin with default 7-day duration
WPP.chat.pinMsg('true_[number]@c.us_ABCDEF');

// Pin for 30 days
WPP.chat.pinMsg(
  'true_[number]@c.us_ABCDEF',
  true,
  WPP.whatsapp.PinExpiryDurationOption.ThirtyDays
);

// Pin for 1 day
WPP.chat.pinMsg(
  'true_[number]@c.us_ABCDEF',
  true,
  WPP.whatsapp.PinExpiryDurationOption.OneDay
);

// Unpin
WPP.chat.pinMsg('true_[number]@c.us_ABCDEF', false);
// or
WPP.chat.unpinMsg('true_[number]@c.us_ABCDEF');

msgId

string

required

Full message ID string.

boolean

default:"true"

true to pin, false to unpin.

duration

PinExpiryDurationOption

default:"SevenDays"

Pin expiry duration. Use WPP.whatsapp.PinExpiryDurationOption enum values: OneDay, SevenDays, ThirtyDays. Passing a raw number is deprecated and will always result in a 7-day pin.

Returns Promise<{ message: MsgModel, pinned: boolean, result: SendMsgResult }>

Pinning is not supported in newsletter chats. In groups with restricted settings, only admins can pin messages.

`downloadMedia`

Download the raw media Blob from a media message. Checks internal caches before triggering a network download.

// Get a Blob
const blob = await WPP.chat.downloadMedia('true_[number]@c.us_ABCDEF');

// Convert to base64
const base64 = await WPP.chat.downloadMedia('true_[number]@c.us_ABCDEF')
  .then(WPP.util.blobToBase64);

string

required

Full message ID of the media message.

Returns Promise<Blob> — throws a WPPError with code message_not_contains_media if the message has no media.

Chat management

`get`

Look up a ChatModel synchronously from the local store. Returns undefined if the chat does not exist locally.

const chat = WPP.chat.get('[number]@c.us');

chatId

string

required

Chat JID to look up.

Returns ChatModel | undefined

`find`

Find an existing chat or create one if it does not exist. Unlike get, this is async and always returns a ChatModel.

const chat = await WPP.chat.find('[number]@c.us');

chatId

string

required

Chat JID.

Returns Promise<ChatModel>

`list`

Return a filtered, paginated list of chats.

// All chats
const all = await WPP.chat.list();

// First 20 user chats only
const users = await WPP.chat.list({ count: 20, onlyUsers: true });

// All groups
const groups = await WPP.chat.list({ onlyGroups: true });

// Chats with unread messages
const unread = await WPP.chat.list({ onlyWithUnreadMessage: true });

// Archived chats
const archived = await WPP.chat.list({ onlyArchived: true });

// Chats tagged with a label
const labelled = await WPP.chat.list({ withLabels: ['Support'] });

options

object

Show ChatListOptions

options.count

number

Maximum number of chats to return. Defaults to all.

options.direction

string

default:"after"

Pagination direction: 'after' or 'before' relative to id.

options.id

string

Cursor chat JID for pagination.

options.onlyUsers

boolean

Return only individual (non-group) chats.

options.onlyGroups

boolean

Return only group chats.

options.onlyCommunities

boolean

Return only community group chats.

Return only newsletter chats.

options.onlyWithUnreadMessage

boolean

Return only chats that have unread messages.

options.onlyArchived

boolean

Return only archived chats.

options.withLabels

string[]

Filter chats that have at least one of the specified label names or IDs.

options.ignoreGroupMetadata

boolean

Skip fetching group metadata for group chats (faster, but group fields may be empty).

Returns Promise<ChatModel[]>

`getMessages`

Fetch messages from a chat’s history with pagination, media filtering, and unread-only modes.

// Last 20 messages
WPP.chat.getMessages('[number]@c.us', { count: 20 });

// All messages
WPP.chat.getMessages('[number]@c.us', { count: -1 });

// All unread messages
WPP.chat.getMessages('[number]@c.us', { count: -1, onlyUnread: true });

// 20 messages before a specific message
WPP.chat.getMessages('[number]@c.us', {
  count: 20,
  direction: 'before',
  id: 'true_[number]@c.us_ABCDEF'
});

// Only image messages
WPP.chat.getMessages('[number]@c.us', { count: 20, media: 'image' });

// Include call log messages
WPP.chat.getMessages('[number]@c.us', { count: 20, includeCallMessages: true });

chatId

string

required

Chat JID.

options

object

Show GetMessagesOptions

options.count

number

default:"20"

Number of messages to fetch. Pass -1 for all messages.

options.direction

string

default:"before"

'before' or 'after' relative to the anchor message ID.

options.id

string

Anchor message ID for pagination. Defaults to the last received message.

options.onlyUnread

boolean

Return only messages that are marked as unread.

options.media

string

Filter by media type: 'image', 'document', 'url', or 'all'.

options.includeCallMessages

boolean

Include call log messages, which are excluded by default.

Returns Promise<RawMessage[]>

`getMessageById`

Fetch one or more messages by their full ID strings.

// Single message
const msg = await WPP.chat.getMessageById('true_[number]@c.us_ABCDEF');

// Multiple messages
const msgs = await WPP.chat.getMessageById([
  'true_[number]@c.us_ABCDEF',
  'false_[number]@c.us_789456'
]);

ids

string | string[]

required

A single message ID string or an array of ID strings.

Returns Promise<MsgModel> or Promise<MsgModel[]> depending on input type. Throws a WPPError with code msg_not_found if any ID cannot be resolved.

`markIsRead`

Mark a chat as read and dispatch the SEEN event to the sender.

const result = await WPP.chat.markIsRead('[number]@c.us');
// result: { wid, unreadCount }

chatId

string

required

Chat JID to mark as read.

Returns Promise<{ wid: Wid, unreadCount: number }>

`markIsUnread`

Mark a chat as unread (the blue dot).

await WPP.chat.markIsUnread('[number]@c.us');

chatId

string

required

Chat JID to mark as unread.

Returns Promise<{ wid: Wid }>

`mute` / `unmute`

Mute notifications for a chat for a duration or until a specific time, then unmute.

// Mute for 1 hour
WPP.chat.mute('[number]@c.us', { duration: 3600 });

// Mute until a specific date
WPP.chat.mute('[number]@c.us', { expiration: new Date('2026-01-01') });

// Mute using a Unix timestamp
WPP.chat.mute('[number]@c.us', { expiration: 1767225600 });

// Unmute
WPP.chat.unmute('[number]@c.us');

chatId

string

required

Chat JID.

time

object

required

Either { duration: number } (seconds from now) or { expiration: number | Date } (Unix timestamp or Date object).

Returns Promise<{ wid, expiration, isMuted }>

`archive` / `unarchive`

Move a chat to or from the archive.

// Archive
WPP.chat.archive('[number]@c.us');

// Unarchive
WPP.chat.unarchive('[number]@c.us');
// equivalent to:
WPP.chat.archive('[number]@c.us', false);

chatId

string

required

Chat JID.

`pin` / `unpin`

Pin or unpin a chat in the chat list.

WPP.chat.pin('[number]@c.us');
WPP.chat.unpin('[number]@c.us');

chatId

string

required

Chat JID.

boolean

default:"true"

true to pin, false to unpin.

Returns Promise<{ wid, pin }>

`clear`

Clear all messages from a chat’s local history without deleting the chat.

// Clear and keep starred messages
WPP.chat.clear('[number]@c.us');

// Clear including starred messages
WPP.chat.clear('[number]@c.us', false);

chatId

string

required

Chat JID.

keepStarred

boolean

default:"true"

When true, starred messages are preserved.

Returns Promise<{ wid, status, keepStarred }>

`delete`

Delete a chat entirely from the chat list. This is distinct from clear, which only removes messages.

await WPP.chat.delete('[number]@c.us');

chatId

string

required

Chat JID to delete.

Returns Promise<{ wid, status }>

`getUnreadChats`

Get all chats that have unread messages.

// All chats currently showing as unread
const chats = await WPP.chat.getUnreadChats(false);

// Only chats that received new messages since the last WPP.chat load
const newOnly = await WPP.chat.getUnreadChats(true);

onlyNewUnreads

boolean

required

When true, returns only chats that received new unread messages during the current session. When false, returns all chats with any unread count.

Returns Promise<ChatModel[]>

Events

`chat.new_message`

Fired whenever a new message arrives in any chat.

WPP.on('chat.new_message', (msg) => {
  console.log('New message in', msg.chatId, ':', msg.body);
});

Event payload fields

Field	Type	Description
`id`	`string`	Full message ID
`body`	`string`	Text content or media caption
`type`	`string`	Message type (`chat`, `image`, `audio`, `video`, `document`, etc.)
`from`	`string`	Sender JID
`to`	`string`	Recipient JID
`fromMe`	`boolean`	`true` if the message was sent by the current user
`t`	`number`	Message Unix timestamp

Connection

Messaging

Contacts & Groups

Channels & Organization

Business

Account

WPP.chat — Send messages and manage WhatsApp chats

Sending messages

`sendTextMessage`

`sendFileMessage`

`sendLocationMessage`

`sendListMessage`

`sendCreatePollMessage`

`sendReactionToMessage`

`sendVCardContactMessage`

`sendGroupInviteMessage`

Message operations

`deleteMessage`

`editMessage`

`forwardMessage`

`starMessage`

`pinMsg`

`downloadMedia`

Chat management

`get`

`find`

`list`

`getMessages`

`getMessageById`

`markIsRead`

`markIsUnread`

`mute` / `unmute`

`archive` / `unarchive`

`pin` / `unpin`

`clear`

`delete`

`getUnreadChats`

Events

`chat.new_message`

Build docs developers (and LLMs) love

Connection

Messaging

Contacts & Groups

Channels & Organization

Business

Account

Documentation Index

​Sending messages

​sendTextMessage

​sendFileMessage

​sendLocationMessage

​sendListMessage

​sendCreatePollMessage

​sendReactionToMessage

​sendVCardContactMessage

​sendGroupInviteMessage

​Message operations

​deleteMessage

​editMessage

​forwardMessage

​starMessage

​pinMsg

​downloadMedia

​Chat management

​get

​find

​list

​getMessages

​getMessageById

​markIsRead

​markIsUnread

​mute / unmute

​archive / unarchive

​pin / unpin

​clear

​delete

​getUnreadChats

​Events

​chat.new_message

Build docs developers (and LLMs) love

Sending messages

`sendTextMessage`

`sendFileMessage`

`sendLocationMessage`

`sendListMessage`

`sendCreatePollMessage`

`sendReactionToMessage`

`sendVCardContactMessage`

`sendGroupInviteMessage`

Message operations

`deleteMessage`

`editMessage`

`forwardMessage`

`starMessage`

`pinMsg`

`downloadMedia`

Chat management

`get`

`find`

`list`

`getMessages`

`getMessageById`

`markIsRead`

`markIsUnread`

`mute` / `unmute`

`archive` / `unarchive`

`pin` / `unpin`

`clear`

`delete`

`getUnreadChats`

Events

`chat.new_message`