Sign inGet started

Mensajes de audio de WhatsApp

Un mensaje de audio lleva una URL pública que WhatsApp obtiene en el momento del envío. No tiene pie de texto y opcionalmente puede mostrarse como nota de voz.

Enviar un mensaje de audio

Configura audio.url:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  audio: { url: "https://cdn.example.com/vm/9f2.ogg" },
});
console.log(msg.id, msg.status);
La forma completa añade el flag opcional voice, el único otro campo que tiene audio:
Ejemplo de código
{
  "to": "+16505551234",
  "from": "+13124495648",
  "audio": { "url": "https://cdn.example.com/voice/9f2e4a.ogg", "voice": true }
}
audio no tiene campo caption en absoluto. from es obligatorio en cada mensaje de servicio: un número que tu espacio de trabajo posee, no uno gestionado por Bird.

Límites

CampoLímiteValidado por
Tamaño de archivo16 MBSolo WhatsApp, al obtener (async)
FormatoAAC, AMR, MP3, M4A u OGG con el códec OPUS, monoSolo WhatsApp, al obtener (async)
voice: truerequiere .ogg/OPUS, mono; otros formatos hacen que la transcripción falleSolo WhatsApp, al obtener (async)
captionno es un campo válidoBird, al aceptar (422, rechazo de esquema)
urlabsoluta, https, tiene host, sin espacios en blancoBird, al aceptar (422)
Bird comprueba la forma de la URL antes de encolar nada; no comprueba el tamaño real del archivo, el formato ni el códec, y no comprueba que un envío con voice: true sea realmente .ogg/OPUS. Solo la obtención propia de WhatsApp en el momento del envío puede hacerlo. Enviar un caption en un mensaje de audio no es un error de longitud; el campo no existe en el esquema de este tipo, así que falla como propiedad no reconocida. Consulta en el hub enviar multimedia por URL y cuando falla la multimedia.

Leer un mensaje de audio entrante

Un mensaje de audio entrante lleva el mismo objeto audio, más un id y mime_type que Bird obtuvo al descargar el archivo, y sin caption en ninguna dirección. Consulta Recibir audio de WhatsApp para la lectura entrante completa, el payload whatsapp.received y qué tener en cuenta.

Límites y modos de fallo

  • La ventana de atención al cliente tiene que estar abierta. El audio es un mensaje de servicio, entregable solo dentro de una ventana abierta; consulta en el hub la ventana de atención al cliente.
  • Bird rechaza http; WhatsApp sí la obtendría. Consulta en el hub enviar multimedia por URL para la comprobación de forma completa.
  • Una obtención rechazada se cobra igualmente. Consulta en el hub cuando falla la multimedia. El texto de rechazo propio de audio de WhatsApp no se ha medido de forma independiente, así que trata la correspondencia como inferida por simetría en lugar de confirmada por causa.
  • El flag voice cambia cómo el cliente del destinatario muestra el mensaje, no lo que Bird valida. voice: true lo muestra como nota de voz: se descarga automáticamente, muestra un icono de micrófono en línea y puede transcribirse. Para que funcione correctamente necesitas un archivo .ogg codificado con OPUS, mono; cualquier otro formato se envía igual, pero la transcripción falla en el lado del destinatario. voice tiene como valor predeterminado false.
  • El umbral del icono de reproducción de WhatsApp y la señal "played" no son algo que Bird exponga. WhatsApp documenta un comportamiento del cliente con notas de voz pequeñas y un estado de reproducido, pero Bird no modela ninguno de los dos; no construyas una integración que espere leer cualquiera de ellos desde la API.
  • WhatsApp almacena en caché una URL obtenida durante unos 10 minutos. Reenviar la misma URL dentro de esa ventana sirve de nuevo la primera obtención; varía la URL para forzar una nueva.

Siguientes pasos