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);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
audio={"url": "https://cdn.example.com/vm/9f2.ogg"},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
Audio: &bird.WhatsAppAudioSend{Url: "https://cdn.example.com/vm/9f2.ogg"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$audio = (new WhatsAppMessageSendRequestAudio())
->setUrl('https://cdn.example.com/vm/9f2.ogg');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
audio: $audio,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--audio https://cdn.example.com/vm/9f2.ogg \
--from +13124495648 \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"audio": {
"url": "https://cdn.example.com/vm/9f2.ogg"
},
"from": "+13124495648",
"to": "+16505551234"
}
}curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"audio": {
"url": "https://cdn.example.com/vm/9f2.ogg"
}
}'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
| Campo | Límite | Validado por |
|---|---|---|
| Tamaño de archivo | 16 MB | Solo WhatsApp, al obtener (async) |
| Formato | AAC, AMR, MP3, M4A u OGG con el códec OPUS, mono | Solo WhatsApp, al obtener (async) |
| voice: true | requiere .ogg/OPUS, mono; otros formatos hacen que la transcripción falle | Solo WhatsApp, al obtener (async) |
| caption | no es un campo válido | Bird, al aceptar (422, rechazo de esquema) |
| url | absoluta, https, tiene host, sin espacios en blanco | Bird, 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
- Mensajes de servicio de WhatsApp: la ventana de atención al cliente y el modelo que comparten todos los mensajes de servicio
- Video: para un clip de video en lugar de audio
- Stickers: otro tipo de multimedia sin campo de pie de texto
- Enviar mensajes de WhatsApp: el sobre de la solicitud, el modelo 202 y reintentos seguros
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 channelComprender el conceptoWhat is the 24-hour customer service window on WhatsApp?Usar la herramientaWhatsApp message builderExplorar la funcionalidadWhatsApp
Prueba el ejercicio y obtén un resumen de implementación