How to generate a waveform for a voice message

We will talk about additional features of Send media-voice message endpoint: https://whapi.readme.io/reference/sendmessagevoice

When sending voice messages via WhatsApp, you can add a waveform parameter. This is a visual representation of the audio track - what you see as waves in the WhatsApp interface.

What is a waveform

waveform is a base64-formatted string that represents an array of 64 bytes. Each byte is a number from 0 to 127 representing the audio volume at different points in time.

For example: AAAAFiQ0Ng0IKC0eDzIsJCglHSYZIhwmIQwoEAkMCC0eEB0yLA8VGxgbGh0dAxgIERciHyAjKicjIRwfKzU6AA==

How to send an audio file via WhatsApp API

You will need an endpoint: POST https://gate.whapi.cloud/messages/voice

This method is responsible for sending a voice message for chats. Make sure the audio file has the extension .ogg and the opus codec.

curl --request POST \
     --url https://gate.whapi.cloud/messages/voice \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {YOUR_TOKEN}' \
     --header 'content-type: application/json' \
     --data '
{
  "waveform": "P0RKUFZbYGVpbXF0dnh6enp6eXd1cm9rZ2NeWVNNR0E8NjAqJB8aFhIOCwgGBAMDAwMFBwkMEBQYHSInLTM5Pg==",
  "to": "919984351847",
  "media": "https://file-examples.com/storage/fe3e7fc7fe68462a19ac6ae/2017/11/file_example_OOG_1MG.ogg"
}
'

How to generate custom waveform

So, as we have already said, waveform is an array of 64 integers from 0 to 127 - these are essentially 64 amplitudes, which are visualized as vertical bands. You get a sort of graph or “equalizer” where each bar is one of these values, and the height is limited to 127.

Knowing the desired “pattern” (i.e. the general shape of this graph), it is possible to select an array of such 64 values that would reproduce it.

But we need to understand the limitations:

  • Horizontally we have only 64 pixels - that's sort of the “width of the screen”.

  • Vertically, we have 127 pixels maximum per strip.

  • Each stripe is one vertical line, the height of which is given by a single number.

You can pick up such an array by hand or using AI-tools. Below we will give some examples.

Important: When testing, always preview the audio message in the WhatsApp mobile app — the Web version may cache the waveform image if the same audio file is reused.

Symmetrical wavy pattern:

Symmetrical wavy pattern
arr = [
    10, 20, 30, 40, 50, 60, 70, 75,
    80, 83, 85, 86, 87, 88, 89, 90,
    90, 89, 88, 87, 86, 85, 83, 80,
    75, 70, 60, 50, 40, 30, 20, 10,
    10, 20, 30, 40, 50, 60, 70, 75,
    80, 83, 85, 86, 87, 88, 89, 90,
    90, 89, 88, 87, 86, 85, 83, 80,
    75, 70, 60, 50, 40, 30, 20, 10,
]

Here's its base64 string:

ChQeKDI8RktQU1VWV1hZWlpZWFdWVVNQS0Y8MigeFAoKFB4oMjxGS1BTVVZXWFlaWllYV1ZVU1BLRjwyKB4UCg==

Wave (sine wave), a soft, smooth shape:

Wave (sine wave)
[63, 68, 74, 80, 86, 91, 96, 101, 105, 109, 113, 116, 118, 120, 122, 122,
 122, 122, 121, 119, 117, 114, 111, 107, 103, 99, 94, 89, 83, 77, 71, 65,
 60, 54, 48, 42, 36, 31, 26, 22, 18, 14, 11, 8, 6, 4, 3, 3,
 3, 3, 5, 7, 9, 12, 16, 20, 24, 29, 34, 39, 45, 51, 57, 62]

Here's its base64 string:

P0RKUFZbYGVpbXF0dnh6enp6eXd1cm9rZ2NeWVNNR0E8NjAqJB8aFhIOCwgGBAMDAwMFBwkMEBQYHSInLTM5Pg==

Peak in the center. Center maximum and uniform decrease towards the edges:

Peak in the center
[1, 5, 9, 13, 17, 21, 25, 29, 33, 37, 41, 45, 49, 53, 57, 61,
 65, 69, 73, 77, 81, 85, 89, 93, 97, 101, 105, 109, 113, 117, 121, 125,
 125, 121, 117, 113, 109, 105, 101, 97, 93, 89, 85, 81, 77, 73, 69, 65,
 61, 57, 53, 49, 45, 41, 37, 33, 29, 25, 21, 17, 13, 9, 5, 1]

Here's its base64 string:

AQUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVpbXF1eX19eXVxbWllYV1ZVVFNSUVBPTk1MS0pJSEdGRURDQkFAQ==

Here are more options that look interesting:

Staircase. Smooth step increase - visually like climbing:

AAAAAAAAAAASEhISEhISEiQkJCQkJCQkNjY2NjY2NjZISEhISEhISFpaWlpaWlpabGxsbGxsbGx/f39/f39/fw==

Saw (triangular waves). Repetitive shape with linear rise and fall - imitates a “saw”:

AAgQGSEqMjtDTFRdZW52fwAIEBkhKjI7Q0xUXWVudn8ACBAZISoyO0NMVF1lbnZ/AAgQGSEqMjtDTFRdZW52fw==

Pulses (uniform peaks). Single sharp peaks on a flat background - similar to a “pulse”:

fwAAAAAAAAB/AAAAAAAAAH8AAAAAAAAAfwAAAAAAAAB/AAAAAAAAAH8AAAAAAAAAfwAAAAAAAAB/AAAAAAAAAA==

How to generate original waveform

To generate a custom visual waveform for your audio file, you’ll need to take a few additional steps on your side.

First, convert the audio to mono (single channel). Then extract the amplitude values, normalized to the range of -1.0 to 1.0 — this is your raw waveform data. Divide the entire array into 64 equal segments and calculate the average absolute amplitude for each segment.

Multiply each average by 127, round the result, and convert it to an integer. Once you have 64 integer values (each between 0 and 127), convert them into a byte array and encode the result in base64.

Need help? Contact support anytime.

PreviousSend Voice messageNextSend contact (vCard)

Last updated

Was this helpful?