Send Conversational WhatsApp Media Message (Audio)

The WhatsApp Marketing product provides conversational messages, allowing users to initiate conversations with businesses after the business has sent an initial message. One way to create a conversational flow is to integrate a bot to reply to users’ WhatsApp messages.

You can send audio files, or send an audio file as a voice note, using this message type.

You can send this message type if the user has sent a message to your number in the last 24 hours.

Endpoint and Headers

POST https://whatsapp.useinsider.com/v1/conversational/send

Header	Sample Value	Description
X-INS-AUTH-KEY	1a2b3c4d5e6f	This key is required to authorize your request. Refer to API Authentication Tokens to generate your token.
Content-Type	application/json	This header specifies the media type of the resource.

Body Parameters

Parameter	Description	Data Type	Required
messages	All messages are contained in the messages key. You can send multiple messages with a single request.	Array	Yes
from	Specifies the sender phone number ID. Only required when multiple phone numbers are configured for the account. If not specified, the default phone number is used. This applies to both Transactional and Conversational WhatsApp APIs.	String	Optional
phoneNumber	Phone number for the person you want to message. The value must follow the E.164 format (for example, +1234567). Each phone number must begin with a plus sign (+) followed by the country code.	String	Conditional. Required if recipient is not sent.
recipient	Specifies the recipient’s WhatsApp Business-Scoped User ID (BSUID). For example, TR.2124566744990207. Use this identifier to send messages without providing the recipient’s phone number. Pass the complete BSUID, including its country prefix.	String	Conditional. Required if phoneNumber is not provided.
message	Message object	Object	Yes
type	Must be “audio” for this message type.	String	Yes
audio	A media object of type audio.	Object	Yes
link	The protocol and URL of the audio file to be sent. Use only with HTTP/HTTPS URLs. Supported formats are AAC, M4A, AMR, MP3 and OGG OPUS. Max: 16 MB.	String	Yes, if there is no id.
id	The ID of the uploaded media object.	String	Yes, if there is no link.
voice	Set to `true` to send the audio as a voice note. The file must be OGG with the OPUS codec. If not specified, the audio is sent as a regular audio file.	Boolean	No

To send the audio as a voice note, use an OGG file with the OPUS codec and set voice to true.

To upload your audio file and get a media ID, refer to Conversational WhatsApp Message File Processes.

Sample Request

Below is a sample request to send a conversational WhatsApp audio message.

curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.1a2b3c4d5e6f' \
--data '{
    "messages": [
        {
            "phoneNumber": "+1**********",
            "message": {
                "type": "audio",
                "audio": {
                    "link": "{{AUDIO_URL}}"
                }
            }
        }
    ]
}'

Below is a sample request to send the audio as a voice note.

curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.1a2b3c4d5e6f' \
--data '{
    "messages": [
        {
            "phoneNumber": "+1**********",
            "message": {
                "type": "audio",
                "audio": {
                    "link": "https://example.com/media/voice-note.ogg",
                    "voice": true
                }
            }
        }
    ]
}'

Sample Responses

One key is returned for each message to be sent. This key is added to all events related to the message.

{
    "keys": [
        "whatsapp-*************************"
    ]
}

400 Bad Request - Invalid audio.voice Value

If the voice value is not a boolean, for example "voice": "yes", the API returns HTTP status 400 with error code 2001.

{
    "error": {
        "code": 2001,
        "message": "failed to validate request"
    },
    "errorCode": "2001",
    "errors": "M: query params decode error. | ErrorCode: 2001 | Parameters: map[] | Error: json: cannot unmarshal string into Go struct field Audio.messages.message.audio.voice of type bool",
    "message": "failed to validate request"
}

The response body structure differs between the V1 and V2 APIs. Rely on the HTTP status and the error code.

For more information about error responses, refer to Conversational API Error Messages.

Limitations

All functions must be executed with a simple HTTPS POST request.
Only new WhatsApp messages can be sent via this API. No data can be retrieved.
The API Key should be provided as the authorization key in the request header. If the key is incorrect, the operation will not be executed, and an authorization error will be returned in the response.
The rate limit is 1000 requests per second.

The default limit shown here is a standard baseline. If your use case requires higher capacity, feel free to reach out to the Insider One team. We can adjust it to fit your needs.