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 +16505551234curl -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:
{
"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 flag
voicecambia cómo el cliente del destinatario muestra el mensaje, no lo que Bird valida.voice: truelo 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.oggcodificado con OPUS, mono; cualquier otro formato se envía igual, pero la transcripción falla en el lado del destinatario.voicetiene como valor predeterminadofalse. - 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
202y reintentos seguros
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.