# Recibir audio de WhatsApp

El audio que envía un contacto llega como un mensaje entrante con `audio`. El brazo cubre tanto una nota de voz grabada en el chat como un archivo de audio adjunto, y `voice` es lo que distingue uno del otro.

## Qué contiene un audio entrante

```json
{
  "id": "wam_01kyb3q8ndvt6r2h5k9wxc4pfa",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "audio": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyb3q8ndvt6r2h5k9wxc4pfa/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "audio/ogg; codecs=opus",
    "voice": true
  },
  "created_at": "2026-08-25T09:07:32Z"
}
```

| Campo       | Qué contiene                                                                              |
| ----------- | ----------------------------------------------------------------------------------------- |
| `id`        | El archivo almacenado, para pasar como `media_id` al descargar los bytes                  |
| `url`       | Una URL Bird, que se consulta con tu clave API                                            |
| `mime_type` | El tipo de medio que reportó WhatsApp, como `audio/ogg; codecs=opus` para una nota de voz |
| `voice`     | `true` para una nota de voz grabada en el chat, en lugar de un archivo de audio adjunto   |

`caption` no existe en este brazo en ninguna dirección, así que un mensaje de audio nunca lleva texto junto a él. Un contacto que quiera añadir palabras envía un [mensaje de texto](/docs/guides/whatsapp/receiving-whatsapp/plain-text) aparte.

Una nota de voz se descarga automáticamente en el cliente de WhatsApp y puede transcribirse allí para el destinatario. Bird pasa el audio tal cual y no lo transcribe, así que la transcripción que tu contacto ve en su propia app no forma parte del mensaje que tú lees.

## Descargar los bytes

Pasa el ID del mensaje y el `id` del medio al método de medios del canal. La guía de [descarga de medios entrantes](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) del hub incluye esa llamada en todos los lenguajes, junto con las reglas de redirección y cabeceras que sigue.

`mime_type` indica el contenedor y el códec, y una nota de voz es Opus en un contenedor Ogg en lugar del MP3 o AAC que probablemente sea un adjunto. Lee el tipo del campo en lugar de la extensión de archivo en `url`, que no incluye ninguna, y compruébalo antes de pasar los bytes a un servicio de transcripción que solo acepta algunos formatos. El mensaje y su medio expiran juntos, 30 días después de que llega el mensaje; la guía de [descarga de medios entrantes](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) del hub define esa ventana y lo que devuelven las lecturas una vez que pasa.

## El payload del webhook

`whatsapp.received` lleva el brazo `audio` en el sobre del evento, con el flag `voice` incluido:

```json
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:07:32.451Z",
  "data": {
    "whatsapp_id": "wam_01kyb3q8ndvt6r2h5k9wxc4pfa",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "audio": {
      "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyb3q8ndvt6r2h5k9wxc4pfa/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
      "mime_type": "audio/ogg; codecs=opus",
      "voice": true
    },
    "tags": null,
    "metadata": null
  }
}
```

Un flujo automatizado que responde notas de voz lee `voice` aquí, antes de descargar nada: una cola de soporte que transcribe grabaciones pero reenvía archivos de música adjuntos puede ramificar solo con el flag.

## Aspectos a tener en cuenta

- **Lee `voice` como un flag que marca una nota de voz.** Cualquier otro valor, incluido un campo ausente, es un adjunto de audio normal.
- **No se reporta la duración.** El brazo no incluye la longitud, así que léela del archivo después de descargarlo si una cola la necesita.

## Próximos pasos

- [Cómo funciona la recepción](/docs/guides/whatsapp/receiving-whatsapp): el sobre entrante, la descarga de medios y el webhook `whatsapp.received`
- [Mensajes de audio de WhatsApp](/docs/guides/whatsapp/message-types/audio): el lado de envío del mismo brazo
- [Recibir video](/docs/guides/whatsapp/receiving-whatsapp/video): clips, con un pie que el brazo de audio no admite
- [Eventos de WhatsApp](/docs/guides/whatsapp/events): la lista completa de eventos, a través de API o webhooks

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)