# Send audio

> Send an audio file or a voice message over WhatsApp, Instagram or Messenger.

Send audio with `POST /v1/messages` and `type: "audio"`. Fields shared by every type (`to`, `reply_to`, `typing`, `delay_ms`, the 24 h window) are in [Common fields](/en/send/text/#common-fields).

  **cURL**

```bash
curl -X POST https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connection_id": "con_123",
  "to": "5511999990000",
  "type": "audio",
  "audio": {
    "link": "https://cdn.exemplo.com/audio.mp3"
  }
}'
```

  **TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const message = await messajo.messages.send({
  connection_id: "con_123",
  to: "5511999990000",
  type: "audio",
  audio: {
    link: "https://cdn.exemplo.com/audio.mp3"
  },
});
console.log(message.id, message.status);
```

  **n8n**
n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "con_123",
  "to": "5511999990000",
  "type": "audio",
  "audio": {
    "link": "https://cdn.exemplo.com/audio.mp3"
  }
}
```

The response is `201` with `id` (`msg_…`), `status: "queued"` and `conversation_id`. The final state arrives by webhook. Audio has no caption.

## Link or upload

Provide **exactly one** of `link` and `media_id`. Sending both, or neither, returns `400 validation_failed` with `exactly one of media_id or link is required`.

- `link`: URL of the audio.
- `media_id` (`med_…`): comes from `POST /v1/media`, a `multipart/form-data` request with `file` (and `connection_id`, unless the key is a `mjc_…` connection key). Requires the `send` permission. The type is read from the file bytes, not from the extension.

  **cURL**

```bash
curl -X POST https://api.messajo.com/v1/media \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -F connection_id=con_123 \
  -F file=@audio.mp3
```

  **TypeScript**

```ts
import { readFile } from "node:fs/promises";

const media = await messajo.media.upload({
  file: new Blob([await readFile("audio.mp3")]),
  connection_id: "con_123",
});

await messajo.messages.send({
  connection_id: "con_123",
  to: "5511999990000",
  type: "audio",
  audio: { media_id: media.id },
});
```

The upload returns the media `id` (`med_…`), which you pass as `audio.media_id`.

## WhatsApp

Upload up to **16 MiB**. The upload recognises `audio/ogg` (Opus only: OGG with Vorbis is refused), `audio/mpeg`, `audio/amr`, `audio/aac` and `audio/mp4`.

### Voice message

With `voice: true` the audio arrives as a voice message (the one that shows a waveform). It must be OGG with Opus, and Messajo converts the file when it is another format:

- With `media_id` or `link` plus `voice: true`, Messajo converts to OGG/Opus if the file is not already. With `link`, it downloads the file first (public `https` URL, up to 16 MiB).
- You can also convert at upload time with `convert=voice` and send the returned `media_id`, which is already OGG/Opus.

The conversion input is at most 16 MiB and must be an audio file. If the conversion fails, the response is `422 voice_conversion_failed`.

  **cURL**

```bash
curl -X POST https://api.messajo.com/v1/media \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -F connection_id=con_123 \
  -F convert=voice \
  -F file=@audio.mp3
```

  **TypeScript**

```ts
import { readFile } from "node:fs/promises";

const media = await messajo.media.upload({
  file: new Blob([await readFile("audio.mp3")]),
  connection_id: "con_123",
  convert: "voice",
});

await messajo.messages.send({
  connection_id: "con_123",
  to: "5511999990000",
  type: "audio",
  audio: { media_id: media.id, voice: true },
});
```

## Instagram and Messenger

The body is the same, without `voice`:

- `link` must be `https`.
- There is no conversion: the file must already be in a format the channel accepts.

| Channel | Max size | Formats |
| --- | --- | --- |
| Instagram | 25 MiB | `audio/aac`, `audio/mp4`, `audio/x-m4a`, `audio/wav` |
| Messenger | 25 MiB | `audio/mpeg`, `audio/mp4`, `audio/aac`, `audio/wav` |

## Errors

| Code | Status | When |
| --- | --- | --- |
| `validation_failed` | 400 | `link` and `media_id` together, or neither |
| `media_too_large` | 413 | File above the limit |
| `media_type_not_supported` | 415 | Format the channel does not accept |
| `media_error` | 422 | Meta could not process the media |
| `voice_conversion_failed` | 422 | Conversion to a voice message failed |
| `outside_service_window` | 422 | Free-form message outside the 24 h window |

Details for each code are in the [error catalog](/en/errors/).
