24 Hour Status

Voice status

Post a voice status (story) to WhatsApp.

POST
https://api.wawp.net/v2/status/voice?access_token=YOUR_ACCESS_TOKEN&caption=Listen+to+this%21&convert=true&file%5Bfilename%5D=note.ogg&file%5Bmimetype%5D=audio%2Fogg%3B+codecs%3Dopus&file%5Burl%5D=https%3A%2F%2Fwawp.net%2Fsamples%2Ffile_example_OOG_1MG.ogg&instance_id=123456789

Authentication Required

Login to swap the placeholders with your real Instance ID and Access Token.

Log In
Test /v2/status/voice endpoint
POST
POST

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Use clear audio; background noise can be distracting.

  • Add a background color that matches your brand.

The Personal Touch: Voice Status

The /v2/status/voice endpoint allows you to post audio recordings directly to your Status feed. Users see an audio player with a waveform visualization, making it distinct from standard video or music files.

🎙️ Why Voice?

1. Intimacy at Scale

Voice notes are the most personal form of digital communication. Hearing a founder's voice explaining a delay or wishing a "Happy New Year" creates a connection that text cannot replicate.

  • Trust: It proves there is a human behind the automation.
  • Nuance: Tone, excitement, and empathy are lost in text but preserved in voice.

2. High Accessibility

  • Passive Consumption: Users can listen while driving or walking.
  • Literacy: Great for markets where oral communication is preferred over reading long text blocks.

🎧 Technical Requirements

WhatsApp is extremely strict about audio formats for Voice Status.

The "Opus in OGG" Rule

To get the authentic "Voice Note" look (with the waveform), you cannot just upload an MP3.

  • Container: OGG.
  • Codec: Opus.
  • Channels: Mono (1 channel). Stereo often causes the waveform to look flat.
  • Sample Rate: 16000 Hz or 48000 Hz.

How to Convert using FFmpeg

If you have an MP3 file, use this command before uploading:

ffmpeg -i input.mp3 -c:a libopus -b:a 64k -vbr on -compression_level 10 output.ogg

The convert Solution

If you don't want to handle FFmpeg, set convert: true in your API call.

  • Mechanism: The API will take your MP3/WAV/AAC and transcode it to OGG/Opus.
  • Trade-off: Adds latency.

🎨 Visual Customization

Unlike Video (which fills the screen with pixels), a Voice Status is essentially an audio player on top of a colored background.

Background Colors

Just like Text Status, you can (and should) strictly define a backgroundColor.

  • Default: If you don't specify one, WhatsApp picks a random color (often a garish purple or green).
  • Branding: Use your brand's hex code to maintain visual consistency.
    • Example: A Red background (#FF0000) for urgent alerts.
    • Example: A Blue background (#0000FF) for calm updates.

🚀 Use Case Ideas

1. The "Morning Briefing"

  • Concept: A 30-second summary of the stock market or daily news.
  • Execution:
    1. Text-to-Speech (TTS) engine generates audio.
    2. FFmpeg converts to OGG.
    3. API Call: Upload with backgroundColor: #000000.
  • User Value: Users get a mini-podcast in their Status feed.

2. The "Pronunciation Guide"

  • Concept: An educational bot teaching languages.
  • Execution:
    1. Image Status: Shows the word "Bonjour".
    2. Voice Status (Immediately after): Plays the correct pronunciation.
  • Result: A multi-modal verified lesson.

3. Music Teasers

  • Concept: An artist dropping a new track.
  • Execution: Upload the 30-second "hook" of the song.
  • Note: Ensure convert: true is on if uploading MP3 snippets.

⚠️ Limitations

The 30-Second Limit (Again)

Just like video, Voice Statuses are capped at 30 seconds.

  • Truncation: If you upload a 5-minute podcast, only the first 30 seconds will play. The rest is discarded silently.
  • Splitting: You generally cannot split audio as elegantly as video because the pause between statuses breaks the flow of speech. Keep it succinct.

No "Seek" Bar

Voice Statuses do not always have a seek bar (scrubber) depending on the user's OS version. Users expect to listen from start to finish.

Privacy

Voice Statuses obey the same privacy rules (My Contacts, etc.) as the rest of the ecosystem.

Request Parameters

Configure the parameters required to interact with this endpoint. All query and body arguments are listed below with their details.

Request Body

Sent as a JSON object
string

WhatsApp Instance ID

Example:
string

API Access Token

Example:
string

URL to the audio file (ogg/opus recommended)

Example:
string

Name of the file

Example:
string

MIME type

Example:
boolean

Enable auto-conversion

Example:
string

Caption for the voice status

Example:

Request Samples

Use these ready-to-go code snippets to integrate our API into your project quickly and efficiently. Choose your preferred language and library.

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/status/voice";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "YOUR_ACCESS_TOKEN"
6}).toString();
7const body = {
8  "file[url]": "https://wawp.net/samples/file_example_OOG_1MG.ogg",
9  "file[filename]": "note.ogg",
10  "file[mimetype]": "audio/ogg; codecs=opus",
11  "convert": "true",
12  "caption": "Listen to this!"
13};
14
15fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
16  method: "POST",
17  headers: { "Content-Type": "application/json" },
18  body: JSON.stringify(body)
19})
20  .then(async (response) => {
21    if (response.ok) {
22      const data = await response.json();
23      console.log("Success:", data);
24      return data;
25    }
26    
27    // Error Handling
28    if (response.status === 400) {
29      console.error("Error 400: Bad Request - Missing Required Parameter(s)");
30    }
31    if (response.status === 400) {
32      console.error("Error 400: Bad Request (XML Format)");
33    }
34    if (response.status === 400) {
35      console.error("Error 400: Bad Request (Plain Text)");
36    }
37    if (response.status === 401) {
38      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
39    }
40    if (response.status === 401) {
41      console.error("Error 401: Unauthorized (XML Format)");
42    }
43    if (response.status === 404) {
44      console.error("Error 404: Not Found - Session Does Not Exist");
45    }
46    if (response.status === 404) {
47      console.error("Error 404: Not Found (XML Format)");
48    }
49    if (response.status === 500) {
50      console.error("Error 500: Internal Server Error - Unexpected Failure");
51    }
52    if (response.status === 500) {
53      console.error("Error 500: Internal Server Error (HTML)");
54    }
55    if (response.status === 502) {
56      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
57    }
58    if (response.status === 502) {
59      console.error("Error 502: Bad Gateway (XML Format)");
60    }
61
62    const errorText = await response.text();
63    console.error(`Error ${response.status}: ${errorText}`);
64  })
65  .catch((error) => console.error("Network Error:", error));
Interactive Samples
Ln 65, Col 1javascript

Expected Responses

Explore all possible responses and outcomes from the server. We have documented each status code with data examples to make success and error handling easier.

Success - Request completed successfully
Type:
application/json
boolean *
string *

Example

{
"success": true,
"message": "Operation completed successfully"
}
Bad Request - Missing Required Parameter(s)
Unauthorized - Invalid or Missing Access Token
Not Found - Session Does Not Exist
Internal Server Error - Unexpected Failure
Bad Gateway - Connection Failed to Upstream
Previous TopicImage status
Next TopicVideo status

Command Palette

Search for a command to run...