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

Ejemplo de código

{
  "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 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 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 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:

Ejemplo de código

{
  "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: el sobre entrante, la descarga de medios y el webhook whatsapp.received
Mensajes de audio de WhatsApp: el lado de envío del mismo brazo
Recibir video: clips, con un pie que el brazo de audio no admite
Eventos de WhatsApp: la lista completa de eventos, a través de API o webhooks

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Ver la guíaConnecting WhatsApp to Bird: from buying a number to a live channel Comprender el conceptoWhat is the 24-hour customer service window on WhatsApp?Usar la herramientaWhatsApp message builder Explorar la funcionalidadWhatsApp

Prueba el ejercicio y obtén un resumen de implementación