ChatBreez Docs

Appearance

Send Audio Message ​

Send an audio file or a native voice note to a WhatsApp recipient. ChatBreez fetches the audio from a public HTTPS URL you provide and delivers it to that recipient.

Endpoint ​

http
POST /whatsapp/send-audio/:instance
  • :instance: The name of your WhatsApp instance (e.g., my-bot).

Request Body ​

ParameterTypeRequiredDescription
recipientstringYesThe recipient's WhatsApp number with country code (e.g., 254123456789) or the full sender address from a webhook (e.g., 123456789012345@lid or [email protected]). Send @lid addresses exactly as received; do not format them or remove the suffix.
audiostringYesA public HTTPS URL to the audio file.
voiceNotebooleanNoSet to true to send a native voice note. Defaults to false (audio file attachment).
mimetypestringNoThe MIME type of the audio (e.g., audio/ogg). Used for audio attachments. Providing it speeds up sending.

Voice Note vs Audio Attachment ​

ModevoiceNoteHow it appears in WhatsApp
Voice notetrueA push-to-play voice message bubble.
Audio attachmentfalse (default)A regular audio file the recipient can download and forward.

OGG/Opus (audio/ogg) is recommended for voice notes. MP3 and M4A are also supported.

Example Payload — Voice Note ​

json
{
  "recipient": "254123456789",
  "audio": "https://example.com/voice-note.ogg",
  "voiceNote": true
}

Example Payload — Audio Attachment ​

json
{
  "recipient": "254123456789",
  "audio": "https://example.com/podcast.mp3",
  "mimetype": "audio/mpeg",
  "voiceNote": false
}

Examples ​

bash
curl -X POST https://api.chatbreez.com/whatsapp/send-audio/{instance} \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "254123456789",
    "audio": "https://example.com/voice-note.ogg",
    "voiceNote": true
  }'
javascript
const axios = require('axios');

const sendAudio = async () => {
  try {
    const response = await axios.post('https://api.chatbreez.com/whatsapp/send-audio/{instance}', {
      recipient: '254123456789',
      audio: 'https://example.com/voice-note.ogg',
      voiceNote: true
    }, {
      headers: {
        'X-API-Key': 'your_api_key'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

sendAudio();
python
import requests

url = "https://api.chatbreez.com/whatsapp/send-audio/{instance}"

payload = {
    "recipient": "254123456789",
    "audio": "https://example.com/voice-note.ogg",
    "voiceNote": True
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.chatbreez.com/whatsapp/send-audio/{instance}"

	payload := map[string]interface{}{
		"recipient":  "254123456789",
		"audio":      "https://example.com/voice-note.ogg",
		"voiceNote":  true,
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", "your_api_key")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}
java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.chatbreez.com/whatsapp/send-audio/{instance}";
        String json = """
            {
              "recipient": "254123456789",
              "audio": "https://example.com/voice-note.ogg",
              "voiceNote": true
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("X-API-Key", "your_api_key")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
php
<?php

$url = 'https://api.chatbreez.com/whatsapp/send-audio/{instance}';

$payload = json_encode([
    'recipient' => '254123456789',
    'audio' => 'https://example.com/voice-note.ogg',
    'voiceNote' => true,
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key',
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Response ​

json
{
  "message": "Audio message queued for delivery.",
  "messageId": "3EB0C767D097B7C7C030"
}

Keep the messageId if you need to reference the message later when investigating a delivery.

Common Errors ​

Errors are returned as JSON in this shape:

json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "audio: Audio URL must use HTTPS",
    "correlationId": "abc123-def456-ghi789"
  }
}
StatusCodeMeaning
400VALIDATION_ERRORThe request body is invalid, the audio URL is not HTTPS, or the recipient is not registered on WhatsApp.
401UNAUTHORIZEDMissing or invalid API key.
403FORBIDDENYour account is deactivated. Contact support to reactivate it.
404NOT_FOUNDThe instance does not exist.
409CONFLICTThe instance is not connected to WhatsApp. Reconnect it and try again.
502UPSTREAM_ERRORWhatsApp did not acknowledge the message. Try again shortly.
500INTERNAL_SERVER_ERRORAn unexpected error occurred on our side. Try again shortly.

Next Steps ​