# Enviar áudio

> Envie um arquivo de áudio ou uma mensagem de voz por WhatsApp, Instagram ou Messenger.

Envie um áudio em `POST /v1/messages` com `type: "audio"`. Os campos comuns a todos os tipos (`to`, `reply_to`, `typing`, `delay_ms`, janela de 24 h) estão em [Campos comuns](/send/text/#campos-comuns).

  **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"
  }
}
```

A resposta é `201` com `id` (`msg_…`), `status: "queued"` e `conversation_id`. O estado final chega por webhook. Áudio não tem legenda.

## Link ou upload

Informe **exatamente um** entre `link` e `media_id`. Mandar os dois, ou nenhum, devolve `400 validation_failed` com `exactly one of media_id or link is required`.

- `link`: URL do áudio.
- `media_id` (`med_…`): vem de `POST /v1/media`, um `multipart/form-data` com `file` (e `connection_id`, exceto com chave de conexão `mjc_…`). Exige a permissão `send`. O tipo é lido dos bytes do arquivo, não da extensão.

  **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 },
});
```

O upload devolve o `id` da mídia (`med_…`), que você usa em `audio.media_id`.

## WhatsApp

Upload de até **16 MiB**. O upload reconhece `audio/ogg` (somente Opus: OGG com Vorbis é recusado), `audio/mpeg`, `audio/amr`, `audio/aac` e `audio/mp4`.

### Mensagem de voz

Com `voice: true` o áudio chega como mensagem de voz (a que mostra a onda sonora). Ela precisa ser OGG com Opus, e o Messajo converte quando o arquivo é de outro formato:

- Com `media_id` ou `link` e `voice: true`, o Messajo converte para OGG/Opus se o arquivo ainda não for. Com `link`, ele baixa o arquivo antes (URL pública `https`, até 16 MiB).
- Você também pode converter no upload, com `convert=voice`, e enviar o `media_id` que volta já em OGG/Opus.

A entrada da conversão tem no máximo 16 MiB e precisa ser um arquivo de áudio. Se a conversão falhar, a resposta é `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 e Messenger

O corpo é o mesmo, sem `voice`:

- `link` precisa ser `https`.
- Não há conversão: o arquivo precisa estar em um formato aceito pelo canal.

| Canal | Tamanho máximo | Formatos |
| --- | --- | --- |
| Instagram | 25 MiB | `audio/aac`, `audio/mp4`, `audio/x-m4a`, `audio/wav` |
| Messenger | 25 MiB | `audio/mpeg`, `audio/mp4`, `audio/aac`, `audio/wav` |

## Erros

| Código | Status | Quando |
| --- | --- | --- |
| `validation_failed` | 400 | `link` e `media_id` juntos, ou nenhum dos dois |
| `media_too_large` | 413 | Arquivo acima do limite |
| `media_type_not_supported` | 415 | Formato que o canal não aceita |
| `media_error` | 422 | A Meta não conseguiu processar a mídia |
| `voice_conversion_failed` | 422 | Falha ao converter para mensagem de voz |
| `outside_service_window` | 422 | Mensagem livre fora da janela de 24 h |

Detalhes de cada código no [catálogo de erros](/errors/).
