Messages audio WhatsApp
Un message audio contient une URL publique que WhatsApp récupère au moment de l'envoi. Il n'a pas de légende et peut optionnellement s'afficher comme une note vocale.
Envoyer un message audio
Définissez 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 forme complète ajoute le flag optionnel voice, le seul autre champ dont dispose audio :
Exemple de code
{
"to": "+16505551234",
"from": "+13124495648",
"audio": { "url": "https://cdn.example.com/voice/9f2e4a.ogg", "voice": true }
}audio n'a aucun champ caption. from est obligatoire sur chaque message de service : un numéro que votre espace de travail possède, pas un numéro géré par Bird.
Limites
| Champ | Limite | Appliqué par |
|---|---|---|
| Taille du fichier | 16 Mo | WhatsApp uniquement, à la récupération (async) |
| Format | AAC, AMR, MP3, M4A ou OGG avec le codec OPUS, mono | WhatsApp uniquement, à la récupération (async) |
| voice: true | nécessite .ogg/OPUS, mono ; les autres formats font échouer la transcription | WhatsApp uniquement, à la récupération (async) |
| caption | champ non valide | Bird, à l'acceptation (422, rejet de schéma) |
| url | absolue, https, possède un hôte, pas d'espace brut | Bird, à l'acceptation (422) |
Bird vérifie la forme de l'URL avant toute mise en file d'attente ; il ne vérifie ni la taille réelle du fichier, ni le format, ni le codec, et il ne vérifie pas qu'un envoi voice: true est réellement en .ogg/OPUS. Seule la récupération par WhatsApp au moment de l'envoi le peut. Envoyer un caption sur un message audio n'est pas une erreur de longueur ; le champ n'existe pas dans le schéma de cette branche, donc il échoue en tant que propriété non reconnue. Voir dans le hub envoyer un média par URL et quand un média échoue.
Lire un message audio entrant
Un message audio entrant contient le même objet audio, plus un id et un mime_type que Bird a appris en récupérant le fichier, et aucun caption dans les deux sens. Voir Recevoir un audio WhatsApp pour la lecture entrante complète, le payload whatsapp.received, et les points à surveiller.
Limites et modes d'échec
- La fenêtre de service client doit être ouverte. Un audio est un message de service, livrable uniquement dans une fenêtre ouverte ; voir dans le hub la fenêtre de service client.
- Bird rejette http ; WhatsApp lui-même la récupérerait. Voir dans le hub envoyer un média par URL pour la vérification complète de la forme.
- Une récupération rejetée est quand même facturée. Voir dans le hub quand un média échoue. Le texte de rejet propre à l'audio provenant de WhatsApp n'a pas été mesuré indépendamment ; considérez la correspondance comme déduite par symétrie plutôt que confirmée par cause.
- Le flag voice change la façon dont le client du destinataire affiche le message, pas ce que Bird valide. voice: true l'affiche comme une note vocale : téléchargement automatique, icône de microphone en ligne et transcription possible. Pour que cela fonctionne correctement, il faut un fichier .ogg encodé en OPUS, mono ; tout autre format est quand même envoyé, mais la transcription échoue côté destinataire. voice vaut par défaut false.
- Le seuil d'icône de lecture et le signal "played" propres à WhatsApp ne sont pas exposés par Bird. WhatsApp documente un comportement client autour des petites notes vocales et d'un état « lu », mais Bird ne modélise ni l'un ni l'autre ; ne construisez pas une intégration qui s'attend à lire l'un ou l'autre depuis le API.
- WhatsApp met en cache une URL récupérée pendant environ 10 minutes. Renvoyer la même URL dans cette fenêtre resert la première récupération ; modifiez l'URL pour en forcer une nouvelle.
Étapes suivantes
- Messages de service WhatsApp : la fenêtre de service client et le modèle partagé par tous les messages de service
- Vidéo : pour un clip vidéo au lieu d'un audio
- Stickers : une autre branche média sans champ de légende
- Envoyer des messages WhatsApp : l'enveloppe de requête, le modèle 202, et les réessais sûrs
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channelComprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builderExplorer la fonctionnalitéWhatsApp
Essayez la pratique et obtenez un guide d'implémentation