Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wppconnect-team/wa-js/llms.txt

Use this file to discover all available pages before exploring further.

The WPP.status module lets you interact with WhatsApp’s Status (Stories) feature from WA-JS. You can post new text, image, and video statuses to status@broadcast, mark a contact’s status as seen, fetch your own status feed or a contact’s feed, remove statuses you have posted, and control which contacts can view your stories. Status delivery is handled internally by routing messages through WhatsApp’s status@broadcast channel using the same encrypted transport as regular messages.

​
Posting statuses

​
sendTextStatus

Post a text status story with an optional background colour and font style. 
// Default black background
WPP.status.sendTextStatus('Good morning! ☀️');

// With a custom background colour and font
WPP.status.sendTextStatus('Bootstrap blue text', {
  backgroundColor: '#0275d8',
  font: 2
});

// Using a numeric ARGB colour
WPP.status.sendTextStatus('Dark mode text', {
  backgroundColor: 0xff1a1a2e
});
​
content
string
required
The text to display on the status card. Supports basic WhatsApp markdown formatting.
​
options
object
Returns Promise<SendMessageReturn> — { id, ack, sendMsgResult }
Font index values correspond to the seven font options shown in the WhatsApp status composer. Experiment with values 0 through 5 to select the style you need.

​
sendImageStatus

Post an image as a status story. Accepts the same content formats as WPP.chat.sendFileMessage. 
// From a base64 data URI
WPP.status.sendImageStatus('data:image/jpeg;base64,<base64...>');

// With a caption
WPP.status.sendImageStatus('data:image/png;base64,<base64...>', {
  caption: 'From the mountains 🏔️'
});

// From a public URL (CORS must be enabled on the server)
WPP.status.sendImageStatus('https://example.com/photo.jpg', {
  caption: 'Shared from the web'
});
​
content
string | Blob | File
required
Image data as a base64 data URI (data:image/<type>;base64,<data>), a publicly accessible URL with CORS headers, a Blob, or a File object.
​
options
object
Returns Promise<SendMessageReturn>
WhatsApp enforces file size limits for status media. Images must not exceed the platform’s image upload limit. sendImageStatus delegates to WPP.chat.sendFileMessage internally and will throw a WPPError with code file_too_large if the limit is exceeded.

​
sendVideoStatus

Post a video as a status story. 
// From a base64 data URI
WPP.status.sendVideoStatus('data:video/mp4;base64,<base64...>');

// With a caption
WPP.status.sendVideoStatus('data:video/mp4;base64,<base64...>', {
  caption: 'Highlights reel'
});
​
content
string | Blob | File
required
Video data as a base64 data URI, a public URL, a Blob, or a File object.
​
options
object
Returns Promise<SendMessageReturn>

​
Reading statuses

​
get

Retrieve the StatusV3Model for a specific contact from the local store. Returns undefined if the contact’s statuses have not been loaded into memory yet. 
const statusFeed = WPP.status.get('[number]@c.us');

if (statusFeed) {
  console.log('Status messages:', statusFeed.msgs.length);
}
​
chatId
string
required
The JID of the contact whose status feed you want to retrieve.
Returns StatusV3Model | undefined

​
getMyStatus

Fetch your own status feed, resolving from the server if it is not already in the local store. 
const myFeed = await WPP.status.getMyStatus();

// Iterate your own posted statuses
myFeed.msgs.forEach((msg) => {
  console.log(msg.id.toString(), msg.type);
});
Returns Promise<StatusV3Model>

​
sendReadStatus

Mark a specific status message as seen on behalf of the current user. 
await WPP.status.sendReadStatus(
  '[number]@c.us',
  'false_status@broadcast_3A169E0FD4BC6E92212F_5521526232927@c.us'
);
​
chatId
string
required
The JID of the contact who posted the status.
​
statusId
string
required
The full ID of the individual status message to mark as seen.
Returns Promise<any> — returns the serialized status entry, or an empty array if the status was not found.
The status ID format is false_status@broadcast_<msgId>_<contactJid>, which you can obtain from the msgs collection of a StatusV3Model.

​
Managing your statuses

​
remove

Delete a status you have previously posted. Only works on statuses posted by the current user. 
// Remove a status by its full message ID
await WPP.status.remove('true_status@broadcast_ABCDEF_me@c.us');
​
msgId
string
required
The full message ID of the status to remove.
Returns Promise<boolean> — resolves true on success. Throws a WPPError with code error_on_remove_status if the revocation fails.

​
updateParticipants

Set the list of contacts that can see your status stories. Pass null or an empty array to reset to your full contacts list. 
// Restrict visibility to specific contacts
await WPP.status.updateParticipants([
  '123456789@c.us',
  '987654321@c.us'
]);

// Reset to all contacts (default behaviour)
await WPP.status.updateParticipants(null);

// Same as passing null
await WPP.status.updateParticipants([]);
​
ids
string[] | null
An array of contact JIDs that can see your status, or null / an empty array to use all contacts in your address book. Your own JID is excluded automatically and re-added only if WPP.config.sendStatusToDevice is enabled.
Returns Promise<void>
The selected participant type ('custom' vs 'contacts') is saved to localStorage under the key 'wpp-status-participants' so the selection persists across page reloads.

​
Usage patterns

const result = await WPP.status.sendTextStatus('Hello world!', {
  backgroundColor: '#128C7E'
});

console.log('Status posted with ID:', result.id);

// Wait for server acknowledgement
const ackResult = await result.sendMsgResult;
console.log('Server ACK:', ackResult);

const myFeed = await WPP.status.getMyStatus();

for (const msg of myFeed.msgs.models) {
  console.log({
    id: msg.id.toString(),
    type: msg.type,
    timestamp: new Date(msg.t * 1000).toISOString()
  });
}

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

if (feed) {
  for (const msg of feed.msgs.models) {
    await WPP.status.sendReadStatus('[number]@c.us', msg.id.toString());
  }
}

// The server hosting the image must send CORS headers
// (Access-Control-Allow-Origin: *)
await WPP.status.sendImageStatus('https://example.com/banner.jpg', {
  caption: 'New product launch 🚀'
});

Build docs developers (and LLMs) love

Get started for freeTalk to us