# Enviar audio

> Envía un archivo de audio o un mensaje de voz por WhatsApp, Instagram o Messenger.

Envía un audio con `POST /v1/messages` y `type: "audio"`. Los campos comunes a todos los tipos (`to`, `reply_to`, `typing`, `delay_ms`, ventana de 24 h) están en [Campos comunes](/es/send/text/#campos-comunes).

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

La respuesta es `201` con `id` (`msg_…`), `status: "queued"` y `conversation_id`. El estado final llega por webhook. El audio no lleva leyenda.

## Enlace o carga

Indica **exactamente uno** entre `link` y `media_id`. Enviar los dos, o ninguno, devuelve `400 validation_failed` con `exactly one of media_id or link is required`.

- `link`: URL del audio.
- `media_id` (`med_…`): viene de `POST /v1/media`, un `multipart/form-data` con `file` (y `connection_id`, salvo con clave de conexión `mjc_…`). Requiere el permiso `send`. El tipo se lee de los bytes del archivo, no de la extensión.

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

La carga devuelve el `id` del medio (`med_…`), que usas en `audio.media_id`.

## WhatsApp

Carga de hasta **16 MiB**. La carga reconoce `audio/ogg` (solo Opus: OGG con Vorbis se rechaza), `audio/mpeg`, `audio/amr`, `audio/aac` y `audio/mp4`.

### Mensaje de voz

Con `voice: true` el audio llega como mensaje de voz (el que muestra la onda sonora). Debe ser OGG con Opus, y Messajo convierte el archivo cuando es de otro formato:

- Con `media_id` o `link` y `voice: true`, Messajo convierte a OGG/Opus si el archivo aún no lo es. Con `link`, primero descarga el archivo (URL pública `https`, hasta 16 MiB).
- También puedes convertir al cargar, con `convert=voice`, y enviar el `media_id` que vuelve ya en OGG/Opus.

La entrada de la conversión tiene un máximo de 16 MiB y debe ser un archivo de audio. Si la conversión falla, la respuesta es `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 y Messenger

El cuerpo es el mismo, sin `voice`:

- `link` debe ser `https`.
- No hay conversión: el archivo debe estar ya en un formato que acepte el canal.

| Canal | Tamaño 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` |

## Errores

| Código | Estado | Cuándo |
| --- | --- | --- |
| `validation_failed` | 400 | `link` y `media_id` juntos, o ninguno |
| `media_too_large` | 413 | Archivo por encima del límite |
| `media_type_not_supported` | 415 | Formato que el canal no acepta |
| `media_error` | 422 | Meta no pudo procesar el medio |
| `voice_conversion_failed` | 422 | Falló la conversión a mensaje de voz |
| `outside_service_window` | 422 | Mensaje libre fuera de la ventana de 24 h |

El detalle de cada código está en el [catálogo de errores](/es/errors/).
