🟢 Status

You can send statuses (aka stories) using HTTP API!

WhatsApp Status

Features

Here’s the list of features that are available by 🏭 Engines:

🟢 Status - API
APIWEBJSNOWEBGOWS
Send Text Status
POST /api/{session}/status/text
✔️✔️✔️
Send Image Status
POST /api/{session}/status/image
✔️✔️✔️
Send Voice Status
POST /api/{session}/status/voice
✔️✔️✔️
Send Video Status
POST /api/{session}/status/video
✔️✔️✔️
Delete Status
POST /api/{session}/status/delete
✔️✔️
Get New Status Message ID
GET /api/{session}/status/new-message-id
✔️✔️

If you see the feature is not available in the above list, please create a feature request or leave “+1” comment on the existing one.

API

About contacts field

When you send status you can provide optional contacts field - list of contacts to send status to.

You can fetch your contacts using 👤 Contacts API.

Body
{
  "text": "Have a look! https://waha.devlike.pro/",
  "contacts": ["123123@c.us", "3333@c.us"],
  "backgroundColor": "#38b42f",
  "font": 1
}

Send text status

Send status to all your contacts:

POST /api/{session}/status/text
Body
{
  "text": "Have a look! https://waha.devlike.pro/",
  "backgroundColor": "#38b42f",
  "font": 1
}
  • text - text to send as status.
  • font - font type, experiment with values here to get different fonts.
  • backgroundColor - background color of the status.
  • contacts - array of contacts to send status to.

Send status to specific contacts:

Body
{
  "text": "Have a look! https://waha.devlike.pro/",
  "backgroundColor": "#38b42f",
  "font": 1,
  "contacts": [
    "55xxxxxxxxxxx@c.us",
    "55xxxxxxxxxxx@c.us"
  ]
}

Send image status

POST /api/{session}/status/image

Send video status

POST /api/{session}/status/video

Convert file before sending

Make sure your file has mp4 using libx264 format.

ffmpeg -i input_video.mp4 -c:v libx264 -map 0 -movflags +faststart output_video.mp4

-map 0 -movflags +faststart options required for thumbnail generation.

WEBJS - use :chrome image

If you’re using WEBJS (default engine) - make sure to use devlikeapro/waha-plus:chrome docker image.

Read more about Docker images and engines →.

Send voice status

POST /api/{session}/status/voice

Convert file before sending

Make sure your file has OPUS encoding and packed in OGG container. You can convert to this using ffmpeg ( there’s many libs for that in popular languages).

ffmpeg -i input.mp3 -c:a libopus -b:a 32k -ar 48000 -ac 1 output.opus

Delete status

Here’s how you can delete status message you previously sent.

POST /api/{session}/status/delete

When you send status - you’ll get the response like below, save key.id (it’s message id).

Response
{
  "key": {
    "remoteJid": "status@broadcast",
    "fromMe": true,
    "id": "AAAAAAAAAAAAAAAAAAAAAA" // <===== key.id
  },
  "message": {
    ...
  }
}
Body
{
  "id": "AAAAAAAAAAAAAAAAAAAAAA"
}

It removes status from all contacts in the list.

Get New Status Message ID

Generates new message ID for status message. You can use it in Send Status to 10K contacts flow for manually sending status messages to big amount of contacts.

GET /api/{session}/status/new-message-id
Response
{
  "id": "AAAAAAAAAAAAAAAAAAAAAA"
}

After that you can set it when you send status messages:

Body

{
  "id": "AAAAAAAAAAAAAAAAAAAAAA",
  "text": "Have a look! https://waha.devlike.pro/",
  "contacts": ["first-chunk-of-contacts-here"],
  ...
}

How-to

Get status messages

You can use regular GET /api/{session}/chats/{chatId}/messages to fetch status messages. Set chatId to status@broadcast for that

GET /api/default/chats/status%40broadcast/messages?downloadMedia=true&limit=100

Receive status messages

If you wish to receive status messages in real-time - you can subscribe to the following 🔄 Events :

  • message event for a message (send by someone else)
  • message.any event for a message (including your messages)
message
{
  "event": "message",
  "session": "default",
  "payload": {
    "id": "false_status@broadcast_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_123123@c.us",
    "timestamp": 1667561485,
    "body": "Check this out!",
    "hasMedia": true,
    "media": {
      "url": "http://localhost:3000/api/files/false_status@broadcast_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_123123@c.us.jpg",
      "mimetype": "image/jpeg",
      "filename": null
    }
  }
}

Send Status to 10K Contacts Manually

If you have a large contact list (e.g., 10,000 contacts or more), different engines handle status messages differently.

How Engines Send Status to Many Contacts

  • WEBJS: Handles the process internally, following the official WhatsApp Web behavior. It automatically chunks the contact list.
  • NOWEB: Splits the contact list into chunks of 5,000 contacts and sends status messages sequentially.
    • When sending image, voice, or video status messages, NOWEB re-uploads the media for each chunk.
  • GOWS: Also splits the contact list into chunks of 5,000 contacts, sending them sequentially.
    • For image, voice, or video status messages, GOWS reuses the uploaded media for each chunk (no re-uploads).

Both NOWEB and GOWS use the same message.id for each chunk, allowing you to track “views” for status messages just like regular messages.

You might encounter errors when sending status messages to 10K contacts.

If that happens, or if you’d like more control over the process, you can use the following manual flow to send the status message to your contacts in smaller chunks.

1. Generate a New Message ID

First, generate a new message ID. You’ll use this ID for all status messages in this batch.

GET /api/{SESSION}/status/new-message-id
Response
{
  "id": "AAAAAAAAAAAAAAAAAAAAAA"
}

2. Get Your Own ID

To view your own status message on your device, retrieve your user ID:

GET /api/{SESSION}/me
Response
{
  "id": "11111111111@c.us",
  ...
}

3. Get Your Contacts List

You can either use your existing contact list from a CRM or database, or fetch all contacts from WhatsApp:

GET /api/{SESSION}/contacts/all
Response
[
  {
    "id": "88888888888@c.us",
    ...
  },
  {
    "id": "99999999999@c.us",
    ...
  }
]

4. Send the Status Message to Contacts

Once you have your Message ID, your own ID, and the contacts list, you can start sending status messages in chunks.

We recommend using smaller chunks (256–512 contacts) to make retries and error handling easier.

If you set contacts: null, the system uses the default chunk size of 5,000 contacts, which works well for most cases.

  • Always use the same Message ID for all chunks. This allows you to track views consistently across all recipients.
  • Include your own ID in the first chunk, so you can immediately view the status and receive the message.ack event.
POST /api/{session}/status/text
Body
{
  "id": "AAAAAAAAA",
  "contacts": ["11111111111@c.us", "88888888888@c.us", "..."],
  "text": "Check this out!"
}

Continue sending the status message to the next chunk until you’ve sent it to all contacts.

If you encounter any errors, you can retry sending the message to the same chunk.