Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/whiskeysockets/baileys/llms.txt

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

Baileys supports sending messages to broadcast lists and WhatsApp status updates (stories). This page covers both features in detail.

​
Understanding Broadcast JIDs

WhatsApp uses special JID formats for broadcasts:
  • Broadcast lists: {timestamp}@broadcast (e.g., 1234567890@broadcast)
  • Status/Stories: status@broadcast
import { STORIES_JID } from '@whiskeysockets/baileys'

console.log(STORIES_JID) // 'status@broadcast'

​
JID Helper Functions

import { isJidBroadcast, isJidStatusBroadcast } from '@whiskeysockets/baileys'

// Check if a JID is any broadcast
const isBroadcast = isJidBroadcast('status@broadcast') // true
const isBroadcast2 = isJidBroadcast('1234567890@broadcast') // true

// Check if a JID is specifically the status broadcast
const isStatus = isJidStatusBroadcast('status@broadcast') // true
const isStatus2 = isJidStatusBroadcast('1234567890@broadcast') // false

​
Sending to Broadcast Lists

Broadcast lists allow you to send a message to multiple people, but they receive it as an individual message (not a group).

​
Send to a Broadcast List

const broadcastJid = '1234567890@broadcast'

await sock.sendMessage(
    broadcastJid,
    { text: 'Hello everyone!' },
    { broadcast: true }
)
The broadcast: true option enables broadcast mode for the message.

​
Query Broadcast List Info

Get the name and recipients of a broadcast list: 
const bList = await sock.getBroadcastListInfo('1234567890@broadcast')

console.log('List name:', bList.name)
console.log('Recipients:', bList.recipients)
// recipients is an array of JIDs

​
Send Media to Broadcast

await sock.sendMessage(
    broadcastJid,
    {
        image: { url: './photo.jpg' },
        caption: 'Check this out!'
    },
    { broadcast: true }
)

​
Sending Status Updates (Stories)

Status messages (stories) are temporary posts that expire after 24 hours.

​
Basic Status Message

You must provide a statusJidList - an array of contact JIDs who will receive the status: 
const statusJidList = [
    '1234567890@s.whatsapp.net',
    '0987654321@s.whatsapp.net'
]

await sock.sendMessage(
    'status@broadcast',
    { text: 'Hello from my status!' },
    {
        broadcast: true,
        statusJidList: statusJidList
    }
)
The statusJidList parameter is required for status messages. Without it, no one will see your status.

​
Image Status

await sock.sendMessage(
    'status@broadcast',
    {
        image: { url: './photo.jpg' },
        caption: 'My photo status'
    },
    {
        broadcast: true,
        statusJidList: statusJidList
    }
)

​
Video Status

await sock.sendMessage(
    'status@broadcast',
    {
        video: { url: './video.mp4' },
        caption: 'Check out this video!'
    },
    {
        broadcast: true,
        statusJidList: statusJidList
    }
)

​
Status with Background Color

For text statuses, you can specify a background color: 
await sock.sendMessage(
    'status@broadcast',
    { text: 'Colorful status!' },
    {
        broadcast: true,
        backgroundColor: '#FF5733', // Hex color
        statusJidList: statusJidList
    }
)

​
Status with Custom Font

await sock.sendMessage(
    'status@broadcast',
    { text: 'Custom font status' },
    {
        broadcast: true,
        font: 3, // Font style number (0-3)
        statusJidList: statusJidList
    }
)

​
Complete Status Example

Here’s a full example combining multiple options: 
import makeWASocket from '@whiskeysockets/baileys'

const sock = makeWASocket({
    // ... your config
})

// Wait for connection
sock.ev.on('connection.update', async (update) => {
    if (update.connection === 'open') {
        // Get your contacts (you need to build this list)
        const statusJidList = [
            '1234567890@s.whatsapp.net',
            '0987654321@s.whatsapp.net'
        ]
        
        // Send image status
        await sock.sendMessage(
            'status@broadcast',
            {
                image: { url: 'https://example.com/image.jpg' },
                caption: 'Hello World!'
            },
            {
                backgroundColor: '#4A90E2',
                font: 2,
                statusJidList: statusJidList,
                broadcast: true
            }
        )
        
        console.log('Status sent!')
    }
})

​
Message Options Reference

From the Baileys TypeScript types: 
interface MiscMessageGenerationOptions {
    /** jid list of participants for status@broadcast */
    statusJidList?: string[]
    
    /** if it is broadcast */
    broadcast?: boolean
    
    /** Background color for text status (hex) */
    backgroundColor?: string
    
    /** Font style for text status (0-3) */
    font?: number
    
    // ... other options
}

​
Supported Content Types

You can send these message types to broadcasts and status:

​
Text Messages

{ text: 'Hello' }

​
Extended Text with Link Preview

{
    text: 'Check this out https://example.com',
    // Baileys will generate link preview if link-preview-js is installed
}

​
Images

{
    image: { url: './photo.jpg' },
    caption: 'Caption text'
}

​
Videos

{
    video: { url: './video.mp4' },
    caption: 'Video caption',
    ptv: false // Set to true for video note
}

​
Audio

{
    audio: { url: './audio.ogg' },
    mimetype: 'audio/ogg; codecs=opus'
}
For the full list of supported message content types, see the AnyRegularMessageContent TypeScript type.

​
Building statusJidList

You need to maintain a list of contacts who should see your status. Here are some approaches:

​
From Contacts Event

let myContacts: string[] = []

sock.ev.on('contacts.upsert', (contacts) => {
    myContacts = contacts.map(c => c.id)
})

// Later, use for status
await sock.sendMessage(
    'status@broadcast',
    { text: 'My status' },
    {
        broadcast: true,
        statusJidList: myContacts
    }
)

​
From Custom Store

If you’re using a custom store implementation: 
// Retrieve contacts from your database
const contacts = await db.contacts.findAll()
const statusJidList = contacts.map(c => c.id)

await sock.sendMessage(
    'status@broadcast',
    { text: 'Status for all contacts' },
    { broadcast: true, statusJidList }
)

​
Hardcoded List

For testing or specific contacts: 
const statusJidList = [
    '1234567890@s.whatsapp.net',
    '0987654321@s.whatsapp.net',
    '1122334455@s.whatsapp.net'
]

​
Broadcast Limitations

Broadcast List Limitations:
  • Recipients must have your number saved
  • WhatsApp Web does NOT support creating new broadcast lists (only deleting)
  • Maximum 256 recipients per broadcast list
Status Limitations:
  • Status messages expire after 24 hours
  • Recipients must have your number saved to see your status
  • Media files should be optimized (large files may fail)

​
Internal Implementation

From src/Socket/messages-send.ts, here’s how Baileys handles broadcast messages: 
const statusJid = 'status@broadcast'
const isStatus = jid === statusJid

if (isStatus && statusJidList) {
    // Add statusJidList contacts to participants
    participantsList.push(...statusJidList)
}

const destinationJid = !isStatus ? finalJid : statusJid

const meMsg: proto.IMessage = {
    deviceSentMessage: {
        destinationJid,
        message
    }
}
The message is sent as a deviceSentMessage to the broadcast JID, and WhatsApp’s servers handle distribution to the participants.

​
Best Practices

​
Keep statusJidList Updated

// Refresh contact list periodically
setInterval(async () => {
    // Update your contacts from store or contacts event
    statusJidList = await getLatestContacts()
}, 3600000) // Every hour

​
Handle Errors

try {
    await sock.sendMessage(
        'status@broadcast',
        { text: 'My status' },
        { broadcast: true, statusJidList }
    )
    console.log('Status sent successfully')
} catch (error) {
    console.error('Failed to send status:', error)
}

​
Validate JIDs

import { isJidUser } from '@whiskeysockets/baileys'

// Filter to only valid user JIDs
const validJids = statusJidList.filter(jid => isJidUser(jid))

await sock.sendMessage(
    'status@broadcast',
    { text: 'Status' },
    { broadcast: true, statusJidList: validJids }
)

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us